VBox · API reference
VBox is controlled through a local HTTP API using /cmd?fun=command¶meters. An "instance" in VBox is one record.
| Item | Value |
|---|---|
| HTTP base URL | http://127.0.0.1:8080 |
| Method | GET |
| Result file | /var/mobile/VBoxResult.txt |
| Export folder | /var/mobile/VBox_export |
Before you call anything
- Keep the VBox main screen in the foreground while calling; do not send it to the background.
Return values
Read /var/mobile/VBoxResult.txt after the call:
| Value | Meaning |
|---|---|
1 | Success |
0 | Failure |
2 | Still running |
Recommended polling
Wait one second after each call before reading the result. If it reads 2, wait another second and read again. That costs you at most one extra second.
Endpoint list
| Function | Command | Parameters |
|---|---|---|
| Create an instance | newRecord | — |
| Original instance | originRecord | — |
| Next instance | nextRecord | — |
| First instance | firstRecord | — |
| Switch to a specific instance | setRecord | recordName |
| Delete a specific instance | deleteRecord | recordName |
| Delete every instance | deleteAllRecords | — |
| Get the current instance name | getCurrentRecordName | — |
| Get every instance name | getAllRecordNames | saveFilePath |
| Rename an instance | setRecordName | oldName newName |
| Get a specific instance's parameters | getRecordParam | recordName saveFilePath |
| Get the current instance's parameters | getCurrentRecordParam | saveFilePath |
| Set a specific instance's parameters | setRecordParam | recordName filePath |
| Set the current instance's parameters | setCurrentRecordParam | filePath |
| Export an instance | exportData | exportKeychain |
| Import an instance | importData | importKeychain |
Endpoint details
Instance names default to the creation time, for example 2020-07-03-21-24-13-52.
Create an instance
GET http://127.0.0.1:8080/cmd?fun=newRecordOriginal instance
GET http://127.0.0.1:8080/cmd?fun=originRecordSwitches back to the real device environment.
Next instance
GET http://127.0.0.1:8080/cmd?fun=nextRecordFirst instance
GET http://127.0.0.1:8080/cmd?fun=firstRecordSwitch to a specific instance
GET http://127.0.0.1:8080/cmd?fun=setRecord&recordName=2020-07-03-21-24-13-52| Parameter | Required | Notes |
|---|---|---|
recordName | Yes | Instance name |
You cannot switch in these cases
The instance currently in use, a disabled instance, or one that does not exist.
Delete a specific instance
GET http://127.0.0.1:8080/cmd?fun=deleteRecord&recordName=2020-07-03-21-24-13-52| Parameter | Required | Notes |
|---|---|---|
recordName | Yes | Instance name |
Delete every instance
GET http://127.0.0.1:8080/cmd?fun=deleteAllRecordsGet the current instance name
GET http://127.0.0.1:8080/cmd?fun=getCurrentRecordNameGet every instance name
GET http://127.0.0.1:8080/cmd?fun=getAllRecordNames&saveFilePath=/var/mobile/record.txt| Parameter | Required | Notes |
|---|---|---|
saveFilePath | Yes | Where to save the list of names |
Rename an instance
GET http://127.0.0.1:8080/cmd?fun=setRecordName&oldName=2020-07-03-21-24-13-52&newName=2020| Parameter | Required | Notes |
|---|---|---|
oldName | Yes | Current name |
newName | Yes | New name |
Warning
Disabled instances and the original instance cannot be renamed.
Get a specific instance's parameters
GET http://127.0.0.1:8080/cmd?fun=getRecordParam&recordName=2020-07-03-21-24-13-52&saveFilePath=/var/mobile/test.plist| Parameter | Required | Notes |
|---|---|---|
recordName | Yes | Instance name |
saveFilePath | Yes | Where to save the parameters (a plist) |
Get the current instance's parameters
GET http://127.0.0.1:8080/cmd?fun=getCurrentRecordParam&saveFilePath=/var/mobile/test.plist| Parameter | Required | Notes |
|---|---|---|
saveFilePath | Yes | Where to save the parameters (a plist) |
Set a specific instance's parameters
GET http://127.0.0.1:8080/cmd?fun=setRecordParam&recordName=2020-07-03-21-24-13-52&filePath=/var/mobile/test.plist| Parameter | Required | Notes |
|---|---|---|
recordName | Yes | Instance name |
filePath | Yes | Path to the edited parameter file |
Set the current instance's parameters
GET http://127.0.0.1:8080/cmd?fun=setCurrentRecordParam&filePath=/var/mobile/test.plist| Parameter | Required | Notes |
|---|---|---|
filePath | Yes | Path to the edited parameter file |
Correct flow: export the plist with a get endpoint, edit the fields, then write it back with a set endpoint.
Export an instance
GET http://127.0.0.1:8080/cmd?fun=exportData&exportKeychain=0| Parameter | Required | Notes |
|---|---|---|
exportKeychain | Yes | 1 exports the Keychain too, 0 does not |
Exports land in /var/mobile/VBox_export, one tar file per instance.
Keychain does not cross devices
Keychain data does not transfer between devices or iOS versions, and carrying it across often leaves the device stuck on the activation screen. If the data is going to another device, you must use exportKeychain=0. For a local backup and restore on the same device, exportKeychain=1 gives you more complete data.
Import an instance
GET http://127.0.0.1:8080/cmd?fun=importData&importKeychain=0| Parameter | Required | Notes |
|---|---|---|
importKeychain | Yes | Same rule as export: use 0 across devices |
Put the tar file in /var/mobile/VBox_export before importing.
Lua example (TouchSprite)
local http = require("szocket.http")
local BASE = "http://127.0.0.1:8080/cmd?fun="
local RESULT = "/var/mobile/VBoxResult.txt"
-- Call and wait for the result: true = success / false = failure
function VBox(query)
local res, code = http.request(BASE .. query)
if code ~= 200 then return false end
while true do
mSleep(1000)
if isFileExist(RESULT) then
local r = readFileString(RESULT)
if r == "1" then return true, res end
if r == "0" then return false, res end
-- "2" means keep waiting
end
end
end
-- Create an instance
if VBox("newRecord") then toast("Instance created", 2) end
-- Current instance name
local ok, name = VBox("getCurrentRecordName")
-- Switch to a specific instance
VBox("setRecord&recordName=2020-07-03-21-24-13-52")
-- Export every instance (without Keychain, safe to move to another device)
VBox("exportData&exportKeychain=0")Tip
Where getCurrentRecordName returns the name depends on the build. If the response body comes back empty, use getAllRecordNames to write the list to a file and read it from there.
For usage, see the VBox user guide.
The interface and supported systems may change with updates. Back up important data before cleaning, resetting or deleting anything.