Desktop API reference
A machine running a Linux desktop with Chromium, for agents that use a computer: screenshot returns what its screen shows and act moves and clicks its mouse and types on its keyboard. It is shown in the browser through noVNC at its preview on port 6080 and to VNC clients on 5900. It pauses after 300 seconds with nothing happening, its memory kept.
Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.
Its states: starting, running, paused, deleted, error.
Endpoints#
| Method | Path | Description |
|---|---|---|
POST |
/v2/desktops |
Create a desktop |
GET |
/v2/desktops/{id} |
Get a desktop |
GET |
/v2/desktops |
List desktops |
DELETE |
/v2/desktops/{id} |
Delete a desktop |
POST |
/v2/desktops/{id}:pause |
pause |
POST |
/v2/desktops/{id}:resume |
resume |
POST |
/v2/desktops/{id}:exec |
exec |
GET |
/v2/desktops/{id}/files |
read |
PUT |
/v2/desktops/{id}/files |
write |
GET |
/v2/desktops/{id}/processes/{process}/output |
processOutput |
POST |
/v2/desktops/{id}/processes/{process}:write |
writeProcess |
POST |
/v2/desktops/{id}/processes/{process}:signal |
signalProcess |
GET |
/v2/desktops/{id}/processes |
listProcesses |
POST |
/v2/desktops/{id}/files:remove |
remove |
GET |
/v2/desktops/{id}/files/stat |
stat |
GET |
/v2/desktops/{id}/files/list |
listFiles |
GET |
/v2/desktops/{id}/files/archive |
downloadFolder |
PUT |
/v2/desktops/{id}/files/archive |
uploadFolder |
POST |
/v2/desktops/{id}/files/archive/uploads |
beginFolderUpload |
PUT |
/v2/desktops/{id}/files/archive/uploads/{upload} |
writeFolderUpload |
POST |
/v2/desktops/{id}/files/archive/uploads/{upload}:commit |
commitFolderUpload |
POST |
/v2/desktops/{id}/files/archive/uploads/{upload}:abort |
abortFolderUpload |
POST |
/v2/desktops/{id}/files:mkdir |
mkdir |
POST |
/v2/desktops/{id}/files:rename |
rename |
POST |
/v2/desktops/{id}/files:link |
link |
POST |
/v2/desktops/{id}/files:revokeLinks |
revokeLinks |
GET |
/v2/desktops/{id}/network |
getNetwork |
GET |
/v2/desktops/{id}/metrics |
metrics |
PUT |
/v2/desktops/{id}/network |
setNetwork |
POST |
/v2/desktops/{id}:fork |
fork |
POST |
/v2/desktops/{id}:snapshot |
snapshot |
POST |
/v2/desktops/{id}:update |
update |
GET |
/v2/desktops/{id}/screenshot |
screenshot |
POST |
/v2/desktops/{id}:act |
act |
Create a desktop#
POST /v2/desktops
Creates a desktop. Asked again with the same Idempotency-Key, it returns the same desktop.
Its action, for a key's grant: desktops:create.
Body: a SandboxCreate.
Returns a Sandbox.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.create();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.create()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.createTerminalruntime desktops createGet a desktop#
GET /v2/desktops/{id}
Returns a desktop.
Its action, for a key's grant: desktops:get.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
wait |
number | No | Seconds to wait, at most 60, for its state to differ from ifState; it answers once it does, or as it is when the wait ends. At least 0. At most 60. |
ifState |
string | No | The state the caller last read, which wait waits for it to leave. |
Returns a Sandbox.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.get("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.get("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.get("DESKTOP_ID")Terminalruntime desktops get DESKTOP_IDList desktops#
GET /v2/desktops
Lists the project's desktops, newest first.
Its action, for a key's grant: desktops:list.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
state |
string | No | Only those in these states, comma-separated. |
name |
string | No | Only the desktop of this name. |
label |
list of string | No | Only those with every label given (repeat it for several): key:value, or a key for any value. |
cursor |
string | No | Where the page starts: a page's next. |
limit |
integer | No | The most items the page holds. At least 1. At most 200. Default: 50. |
Returns a page: items, each a Sandbox, and next, where the next page starts, none on the last.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.list();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.list()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.listTerminalruntime desktops listDelete a desktop#
DELETE /v2/desktops/{id}
Deletes a desktop, its memory and its disk.
Its action, for a key's grant: desktops:delete.
Path: id.
Returns a Sandbox.
Examples:
Terminalcurl -X DELETE "https://api.withruntime.com/v2/desktops/DESKTOP_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.delete("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.delete("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.delete("DESKTOP_ID")Terminalruntime desktops delete DESKTOP_IDpause#
POST /v2/desktops/{id}:pause
Pauses a desktop with its memory and disk kept. A call to it resumes it.
Its action, for a key's grant: desktops:pause.
Path: id.
Returns a Sandbox.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:pause" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.pause("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.pause("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.pause("DESKTOP_ID")Terminalruntime desktops pause DESKTOP_IDresume#
POST /v2/desktops/{id}:resume
Resumes a paused desktop where it was, its memory and processes as they were.
Its action, for a key's grant: desktops:wake.
Path: id.
Returns a Sandbox.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:resume" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.resume("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.resume("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.resume("DESKTOP_ID")Terminalruntime desktops resume DESKTOP_IDexec#
POST /v2/desktops/{id}:exec
Runs a command as a process and returns it once it ended, with its output; with wait false, at once, while it runs. A paused desktop is resumed first. Asked again with the same Idempotency-Key, it runs nothing more: it returns the first run's process, waiting for its end while it runs.
Its action, for a key's grant: desktops:exec.
Path: id.
Body: a ExecRequest.
Returns a Process.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:exec" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cmd": "echo hello" }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.exec("DESKTOP_ID", { cmd: "echo hello" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.exec("DESKTOP_ID", cmd="echo hello")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.exec("DESKTOP_ID", cmd: "echo hello")Terminalruntime desktops exec DESKTOP_ID -- echo helloread#
GET /v2/desktops/{id}/files
Returns a file's bytes.
Its action, for a key's grant: desktops:read.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The file's path in the machine. |
Returns the bytes, application/octet-stream.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files?path=/tmp/hello.txt" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -o out.binTypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.read("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.read("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.read("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops read DESKTOP_ID --path /tmp/hello.txtwrite#
PUT /v2/desktops/{id}/files
Writes the request's bytes to a file as they come, of any size (Content-Length required), its folders made: the file whole when they all came, or as it was. With offset, they are written into it in place.
Its action, for a key's grant: desktops:write.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The file's path in the machine. |
mode |
string | No | Its mode, in octal (644). |
offset |
integer | No | Write the bytes into the file in place from this byte, keeping the bytes before and after them (the file is made when there is none); one that fails part way may leave its range written in part, so send it again. Parts of one file may be written so at once and in any order: write them to a new path, then rename it with its size and sha256 to put it in place whole. At least 0. |
sha256 |
string | No | The bytes' SHA-256 in hex: refused 409 checksum_mismatch, the file as it was, when they differ. Not with offset. |
Body: the bytes, application/octet-stream.
Returns a FileWritten.
Examples:
Terminalcurl -X PUT "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files?path=/tmp/hello.txt" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/octet-stream" \ --data-binary 'hello'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.write("DESKTOP_ID", new TextEncoder().encode("hello\n"), { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.write("DESKTOP_ID", b"hello\n", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.write("DESKTOP_ID", "hello\n", path: "/tmp/hello.txt")Terminalruntime desktops write DESKTOP_ID --path /tmp/hello.txt < hello.txtprocessOutput#
GET /v2/desktops/{id}/processes/{process}/output
Returns a process's output after a cursor, and the cursor to read on from. The latest 1 MiB is kept; truncated says when the cursor fell behind.
Its action, for a key's grant: desktops:exec.
Path: id, process.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Output after this byte. At least 0. Default: 0. |
waitSeconds |
number | No | Seconds to wait for output past the cursor or its exit, at most 8. At least 0. At most 8. |
maxBytes |
integer | No | At most this many bytes. At least 4096. At most 196608. Default: 65536. |
follow |
boolean | No | Answer as NDJSON events from the cursor until it exits (stdout, stderr, truncated, exit; continue with the cursor to follow on from), as Accept: application/x-ndjson does. |
Returns a ProcessOutput.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/processes/PROCESS_ID/output" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.processOutput("DESKTOP_ID", "PROCESS_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.process_output("DESKTOP_ID", "PROCESS_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.process_output("DESKTOP_ID", "PROCESS_ID")Terminalruntime desktops process-output DESKTOP_ID PROCESS_IDwriteProcess#
POST /v2/desktops/{id}/processes/{process}:write
Sends input to a process started with stdinOpen or a pty, and returns how much of its input it has taken.
Its action, for a key's grant: desktops:exec.
Path: id, process.
Body: a ProcessInput.
Returns a ProcessWritten.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/processes/PROCESS_ID:write" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.writeProcess("DESKTOP_ID", "PROCESS_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.write_process("DESKTOP_ID", "PROCESS_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.write_process("DESKTOP_ID", "PROCESS_ID")Terminalruntime desktops write-process DESKTOP_ID PROCESS_IDsignalProcess#
POST /v2/desktops/{id}/processes/{process}:signal
Sends a signal to a process and its group; a process that ended is not signalled, so a retry is safe.
Its action, for a key's grant: desktops:exec.
Path: id, process.
Body: a ProcessSignal.
Returns a Process.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/processes/PROCESS_ID:signal" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.signalProcess("DESKTOP_ID", "PROCESS_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.signal_process("DESKTOP_ID", "PROCESS_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.signal_process("DESKTOP_ID", "PROCESS_ID")Terminalruntime desktops signal-process DESKTOP_ID PROCESS_IDlistProcesses#
GET /v2/desktops/{id}/processes
Lists a desktop's processes, newest first: those running and those that ended lately.
Its action, for a key's grant: desktops:exec.
Path: id.
Returns a ProcessList.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/processes" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.listProcesses("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.list_processes("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.list_processes("DESKTOP_ID")Terminalruntime desktops list-processes DESKTOP_IDremove#
POST /v2/desktops/{id}/files:remove
Removes a file, a link or a directory (recursive for one with contents). One missing is success, removed false.
Its action, for a key's grant: desktops:write.
Path: id.
Body: a FileRemove.
Returns a FileRemoved.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files:remove" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/tmp/hello.txt" }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.remove("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.remove("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.remove("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops remove DESKTOP_ID --path /tmp/hello.txtstat#
GET /v2/desktops/{id}/files/stat
Returns what is at a path: a file, a directory or a link, or nothing (exists false).
Its action, for a key's grant: desktops:read.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The file's path in the machine. |
Returns a FileInfo.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/stat?path=/tmp/hello.txt" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.stat("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.stat("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.stat("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops stat DESKTOP_ID --path /tmp/hello.txtlistFiles#
GET /v2/desktops/{id}/files/list
Lists a directory's entries in path order, to a depth.
Its action, for a key's grant: desktops:read.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | No | The directory. Default: "/workspace". |
depth |
integer | No | How deep to list. At least 1. At most 10. Default: 1. |
limit |
integer | No | At most this many entries. At least 1. At most 2000. Default: 2000. |
hidden |
boolean | No | List entries whose names start with a dot. Default: true. |
glob |
string | No | Only entries whose path relative to the directory matches: * within a name, ** across folders, ? one character, {a,b} either (**/*.py); at most 512 characters, 32 wildcards and 64 texts in braces. The listing then reaches as deep as the glob does (10 folders for **) unless depth says, and is searched past its first 2,000 entries, up to 50,000. At most 512 characters. |
Returns a FileList.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/list" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.listFiles("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.list_files("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.list_files("DESKTOP_ID")Terminalruntime desktops list-files DESKTOP_IDdownloadFolder#
GET /v2/desktops/{id}/files/archive
Returns a folder as a tar archive (application/x-tar, or application/gzip with gzip), packed by tar in the desktop as it streams, of any size; its entries are relative to the folder (./a.txt). A folder that fails part way (a file it may not read, or one that changes as it is read) ends as an archive every tar reader refuses, never as a short one that reads whole. At most 4 at once in a desktop. A paused desktop is woken first.
Its action, for a key's grant: desktops:read.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The folder, absolute, such as /workspace/app. |
gzip |
boolean | No | Compress the archive with gzip. Default: false. |
user |
one of runtime, root |
No | Who packs it: runtime or root; the desktop's user when omitted. |
exclude |
string | No | Paths in the folder to leave out, relative to it and comma-separated (node_modules,.cache): plain names, no wildcards, at most 32. |
Returns the bytes, application/octet-stream.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/archive?path=/tmp/hello.txt" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -o out.binTypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.downloadFolder("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.download_folder("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.download_folder("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops download-folder DESKTOP_ID --path /tmp/hello.txtuploadFolder#
PUT /v2/desktops/{id}/files/archive
Unpacks the request's tar archive (gzip-compressed or not, told by its first bytes) into a folder, made with its parents, by tar in the desktop as the bytes arrive, of any size, nothing of it kept on disk but what tar writes; returns once tar has ended, or 400 invalid_archive with what tar said. A paused desktop is woken first.
Its action, for a key's grant: desktops:write.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The folder, absolute, such as /workspace/app: made with its parents. |
user |
one of runtime, root |
No | Who unpacks it: runtime or root; the desktop's user when omitted. |
Body: the bytes, application/octet-stream.
Returns a FolderUnpacked.
Examples:
Terminalcurl -X PUT "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/archive?path=/tmp/hello.txt" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/octet-stream" \ --data-binary 'hello'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.uploadFolder("DESKTOP_ID", new TextEncoder().encode("hello\n"), { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.upload_folder("DESKTOP_ID", b"hello\n", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.upload_folder("DESKTOP_ID", "hello\n", path: "/tmp/hello.txt")Terminalruntime desktops upload-folder DESKTOP_ID --path /tmp/hello.txt < hello.txtbeginFolderUpload#
POST /v2/desktops/{id}/files/archive/uploads
Begins a folder's upload in parts: tar starts in the desktop, unpacking into the folder each part as it arrives. Send the parts in order by offset (writeFolderUpload), then commitFolderUpload; an upload no call names for 10 minutes is ended. A paused desktop is woken first.
Its action, for a key's grant: desktops:write.
Path: id.
Body: a FolderUploadBegin.
Returns a FolderUpload.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/archive/uploads" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/tmp/hello.txt" }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.beginFolderUpload("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.begin_folder_upload("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.begin_folder_upload("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops begin-folder-upload DESKTOP_ID --path /tmp/hello.txtwriteFolderUpload#
PUT /v2/desktops/{id}/files/archive/uploads/{upload}
Sends the request's bytes, a part of the archive at its offset, into tar's input as they arrive, of any size, and returns the bytes received in all once tar took them. A part past them is refused 409 upload_incomplete, naming them: send the parts in order.
Its action, for a key's grant: desktops:write.
Path: id, upload.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
offset |
integer | No | Where the part starts in the archive: at most the bytes received so far. Bytes before them were taken already and are skipped, so a part sent again is never unpacked twice. At least 0. Default: 0. |
Body: the bytes, application/octet-stream.
Returns a FolderUploadReceived.
Examples:
Terminalcurl -X PUT "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/archive/uploads/UPLOAD_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/octet-stream" \ --data-binary 'hello'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.writeFolderUpload("DESKTOP_ID", "UPLOAD_ID", new TextEncoder().encode("hello\n"));Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.write_folder_upload("DESKTOP_ID", "UPLOAD_ID", b"hello\n")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.write_folder_upload("DESKTOP_ID", "UPLOAD_ID", "hello\n")Terminalruntime desktops write-folder-upload DESKTOP_ID UPLOAD_ID < hello.txtcommitFolderUpload#
POST /v2/desktops/{id}/files/archive/uploads/{upload}:commit
Ends a folder upload's input and returns once tar has ended, as an exec returns once its command has: the folder, or 400 invalid_archive with what tar said. A front that restarts meanwhile returns 503 run_goes_on; sent again, it returns how tar ended. An upload no call has named for 10 minutes since its last part or commit is ended.
Its action, for a key's grant: desktops:write.
Path: id, upload.
Returns a FolderUnpacked.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/archive/uploads/UPLOAD_ID:commit" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.commitFolderUpload("DESKTOP_ID", "UPLOAD_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.commit_folder_upload("DESKTOP_ID", "UPLOAD_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.commit_folder_upload("DESKTOP_ID", "UPLOAD_ID")Terminalruntime desktops commit-folder-upload DESKTOP_ID UPLOAD_IDabortFolderUpload#
POST /v2/desktops/{id}/files/archive/uploads/{upload}:abort
Stops a folder upload's tar; what it unpacked so far stays.
Its action, for a key's grant: desktops:write.
Path: id, upload.
Returns a FolderUploadAborted.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files/archive/uploads/UPLOAD_ID:abort" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.abortFolderUpload("DESKTOP_ID", "UPLOAD_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.abort_folder_upload("DESKTOP_ID", "UPLOAD_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.abort_folder_upload("DESKTOP_ID", "UPLOAD_ID")Terminalruntime desktops abort-folder-upload DESKTOP_ID UPLOAD_IDmkdir#
POST /v2/desktops/{id}/files:mkdir
Makes a directory, and its parents unless parents is false. One there already is success, created false.
Its action, for a key's grant: desktops:write.
Path: id.
Body: a FileMkdir.
Returns a FileMade.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files:mkdir" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/tmp/hello.txt" }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.mkdir("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.mkdir("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.mkdir("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops mkdir DESKTOP_ID --path /tmp/hello.txtrename#
POST /v2/desktops/{id}/files:rename
Moves a file, a link or a directory; refused 409 when something is at its new path, unless overwrite. With sha256 or size, a file written in parts is put in place once whole: its writes ended, then only a file of that size with every byte written and whose bytes hash to it moves; refused 409 upload_incomplete or checksum_mismatch, nothing moved.
Its action, for a key's grant: desktops:write.
Path: id.
Body: a FileRename.
Returns a FileRenamed.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files:rename" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "example", "to": "example" }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.rename("DESKTOP_ID", { from: "example", to: "example" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.rename("DESKTOP_ID", from="example", to="example")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.rename("DESKTOP_ID", from: "example", to: "example")Terminalruntime desktops rename DESKTOP_ID --from example --to examplelink#
POST /v2/desktops/{id}/files:link
Makes an expiring address for one file that anyone may open with no API key, from a browser, curl or another service: GET downloads it (Range works, so videos play and downloads resume; archive: true downloads a folder as .tar.gz), PUT with the raw body uploads it (up to maxBytes, written whole; Content-Length required). The link acts as the key that made it: an upload link needs write, and the link ends with its key, with revokeLinks or with its desktop. A paused desktop is woken for it unless wake is false.
Its action, for a key's grant: desktops:read.
Path: id.
Body: a FileLinkCreate.
Returns a FileLink.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files:link" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/tmp/hello.txt" }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.link("DESKTOP_ID", { path: "/tmp/hello.txt" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.link("DESKTOP_ID", path="/tmp/hello.txt")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.link("DESKTOP_ID", path: "/tmp/hello.txt")Terminalruntime desktops link DESKTOP_ID --path /tmp/hello.txtrevokeLinks#
POST /v2/desktops/{id}/files:revokeLinks
Ends every file link made for a desktop so far; links made after work.
Its action, for a key's grant: desktops:write.
Path: id.
Returns a FileLinksRevoked.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID/files:revokeLinks" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.revokeLinks("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.revoke_links("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.revoke_links("DESKTOP_ID")Terminalruntime desktops revoke-links DESKTOP_IDgetNetwork#
GET /v2/desktops/{id}/network
Returns where a desktop may connect out.
Its action, for a key's grant: desktops:get.
Path: id.
Returns a SandboxNetwork.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/network" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.getNetwork("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.get_network("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.get_network("DESKTOP_ID")Terminalruntime desktops get-network DESKTOP_IDmetrics#
GET /v2/desktops/{id}/metrics
Returns a desktop's CPU, memory, disks and pressure, as its host reads them from the desktop's own cgroup over a fifth of a second: never a call into the desktop, so it does not wake a paused one nor keep one from its idle pause. One that is not running has no reading.
Its action, for a key's grant: desktops:get.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
range |
one of 15m, 1h, 6h, 24h, 7d, 30d |
No | The window: 15m, 1h, 6h, 24h, 7d or 30d. Default: "1h". |
Returns a SandboxMetrics.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/metrics" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.metrics("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.metrics("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.metrics("DESKTOP_ID")Terminalruntime desktops metrics DESKTOP_IDsetNetwork#
PUT /v2/desktops/{id}/network
Replaces where a desktop may connect out, for its next connection and within a second for its open ones: those the new rules refuse are cut.
Its action, for a key's grant: desktops:network.
Path: id.
Body: a NetworkRules.
Returns a SandboxNetwork.
Examples:
Terminalcurl -X PUT "https://api.withruntime.com/v2/desktops/DESKTOP_ID/network" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.setNetwork("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.set_network("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.set_network("DESKTOP_ID")Terminalruntime desktops set-network DESKTOP_IDfork#
POST /v2/desktops/{id}:fork
Copies a desktop as it is now, memory and disk, into count copies of its own, each running on its host. Asked again with the same Idempotency-Key, it returns the same copies.
Its action, for a key's grant: desktops:fork.
Path: id.
Body: a ForkRequest.
Returns a Forked.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:fork" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.fork("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.fork("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.fork("DESKTOP_ID")Terminalruntime desktops fork DESKTOP_IDsnapshot#
POST /v2/desktops/{id}:snapshot
Keeps a desktop's memory and disk as they are now, a snapshot to start desktops from; with image, its disk alone as that image's next version. The desktop runs on. Asked again with the same Idempotency-Key, it returns the same snapshot.
Its action, for a key's grant: desktops:snapshot.
Path: id.
Body: a SnapshotRequest.
Returns a Stored.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:snapshot" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.snapshot("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.snapshot("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.snapshot("DESKTOP_ID")Terminalruntime desktops snapshot DESKTOP_IDupdate#
POST /v2/desktops/{id}:update
Changes its name, labels, idle pause, maxCost, environment or sizes; each field left out stays as it is. A running one holds a changed environment before this answers (a paused one's at its wake): each process it starts after the answer has it, and its running processes keep the one they started with. Its vCPUs, memory and disk grow while it runs, its commands running on; a smaller size, or a sandbox that is not running, is refused 409 naming why, and nothing is changed. With If-Match, made only while its revision is that one, else 412.
Its action, for a key's grant: desktops:update.
Path: id.
Body: a MachineUpdate.
Returns a Sandbox.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:update" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.update("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.update("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.update("DESKTOP_ID")Terminalruntime desktops update DESKTOP_IDscreenshot#
GET /v2/desktops/{id}/screenshot
Returns what a desktop's screen shows now, as image/png (or image/jpeg): its X display :1, whole. Refused 409 display_not_running when none runs. A paused desktop is resumed first.
Its action, for a key's grant: desktops:exec.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
format |
one of png, jpeg |
No | png, or jpeg: smaller and quicker to send, for a model that reads it. Default: "png". |
quality |
integer | No | A jpeg's quality, 1 to 100. At least 1. At most 100. Default: 80. |
Returns the bytes, application/octet-stream.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/desktops/DESKTOP_ID/screenshot" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -o out.binTypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.screenshot("DESKTOP_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.screenshot("DESKTOP_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.screenshot("DESKTOP_ID")Terminalruntime desktops screenshot DESKTOP_IDact#
POST /v2/desktops/{id}:act
Moves, clicks, drags and scrolls the mouse and types on the keyboard of a desktop's screen (its X display :1), each step in turn as one command, and returns where the mouse is then. It stops at the first step that fails, refused 409 act_failed naming it; refused 409 display_not_running when no display runs. A paused desktop is resumed first.
Its action, for a key's grant: desktops:exec.
Path: id.
Body: a ActRequest.
Returns a Acted.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/desktops/DESKTOP_ID:act" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "actions": [{ "type": "move" }] }'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.desktops.act("DESKTOP_ID", { actions: [{ type: "move" }] });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.desktops.act("DESKTOP_ID", actions=[{"type": "move"}])rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.desktops.act("DESKTOP_ID", actions: [{ type: "move" }])Terminalruntime desktops act DESKTOP_ID --actions { "type": "move" }Objects#
MachineStart
A command a machine starts at every fresh boot.
| Field | Type | Required | Description |
|---|---|---|---|
cmd |
string (run by bash -lc) or list of strings (the program and its arguments) |
Yes | The command: text, run by bash -lc, or the program and its arguments as a list, run without a shell. |
cwd |
string | No | The directory it runs in; the user's home when omitted. |
env |
object of strings | No | Environment variables to add. |
readyPort |
integer | No | A port it listens on once ready: a create answers once something listens there. At least 1. At most 65535. |
readyCommand |
string | No | A shell command that exits 0 once it is ready, run by /bin/sh -c in cwd until it does: a create answers once it has. |
readyTimeoutSeconds |
integer | No | How long a create waits for readyPort or readyCommand, 1 to 300 seconds: 60 when omitted. At least 1. At most 300. |
VolumeMount
A volume a machine attaches at its create, mounted read-write in it, one machine at a time; detached when the machine is deleted.
| Field | Type | Required | Description |
|---|---|---|---|
volume |
string | Yes | The volume, by name or ID, in the machine's project. |
path |
string | Yes | Where it is mounted, such as /data: an absolute path, not under /proc, /sys, /dev, /etc, /usr, /bin, /sbin, /lib or /boot. |
SandboxRun
A command a sandbox runs once it starts: when it ends, the sandbox stops.
| Field | Type | Required | Description |
|---|---|---|---|
cmd |
string (run by bash -lc) or list of strings (the program and its arguments) |
Yes | The command: text, run by bash -lc, or the program and its arguments as a list, run without a shell. |
cwd |
string | No | The directory it runs in; the user's home when omitted. |
env |
object of strings | No | Environment variables to add. |
timeoutSeconds |
number | No | Seconds it may run before it is stopped (1.5 for 1,500 ms); no limit when omitted or 0. At least 0. |
NetworkRules
Where a sandbox may connect out, past the walls every machine has.
| Field | Type | Required | Description |
|---|---|---|---|
allowOutbound |
list of string | No | The only places it may reach, each a host, *. and a name for every name under it, an address or a CIDR ([ and ] around an IPv6 address), every port when it names none; :port for that port alone, on a host name for a port beyond 80 and 443, which go together. * is every public host. Every public host when omitted; nothing when empty. |
denyOutbound |
list of string | No | Places it may never reach, written as in allowOutbound with no port: a deny wins over every allow. |
SandboxSettings
A sandbox's settings: what a create sets on its machine.
| Field | Type | Required | Description |
|---|---|---|---|
vcpu |
integer | No | Its vCPUs. At least 1. Default: 2. |
memoryGB |
number | No | Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (1.5). At least 1. Default: 4. |
diskGB |
number | No | Its disk in GB (1 GB is 1,024 MiB), to the MiB. At least 1. Default: 4. |
image |
string | No | The image it boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
secrets |
list of string | No | The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. At most 64 items. |
start |
MachineStart | No | The command it starts at every fresh boot and keeps running, as a service: a web server, a runner, a desktop. A wake with its memory kept does not start it again. Its image's when omitted. |
user |
one of runtime, root |
No | Who every command, process, terminal and code run in it runs as when the call names no user: runtime (uid 1000, with passwordless sudo) or root. Its image's when omitted, else runtime. |
SandboxCreate
A sandbox to create.
| Field | Type | Required | Description |
|---|---|---|---|
vcpu |
integer | No | Its vCPUs. At least 1. Default: 2. |
memoryGB |
number | No | Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (1.5). At least 1. Default: 4. |
diskGB |
number | No | Its disk in GB (1 GB is 1,024 MiB), to the MiB. At least 1. Default: 4. |
image |
string | No | The image it boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
secrets |
list of string | No | The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. At most 64 items. |
start |
MachineStart | No | The command it starts at every fresh boot and keeps running, as a service: a web server, a runner, a desktop. A wake with its memory kept does not start it again. Its image's when omitted. |
user |
one of runtime, root |
No | Who every command, process, terminal and code run in it runs as when the call names no user: runtime (uid 1000, with passwordless sudo) or root. Its image's when omitted, else runtime. |
volumes |
list of VolumeMount | No | Volumes it attaches and mounts at its create, at most one; detached when it is deleted, to attach to another. |
run |
SandboxRun | No | A command it runs once it starts. When the command ends, the sandbox is paused with its disk kept (exitCode says how it ended) and a call starts it again. Needs the exec permission too. |
name |
string | No | Its name, unique in its project. |
labels |
labels (keys under runtime. are Runtime's) |
No | Labels to find it by. |
getOrCreate |
boolean | No | With a name: the sandbox of that name when there is one, else a new one. |
maxCost |
string (US dollars, decimal) | No | The most it may cost in all, in US dollars ("5.00"): once it has cost that it pauses, and starts again only once its maxCost is raised (update); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave. |
idlePauseSeconds |
integer | No | Seconds with nothing happening before it pauses, 60 to 86400; 0 never; 300 when omitted. A fork keeps its source's. At least 0. At most 86400. |
snapshot |
string | No | A snapshot it starts as: a copy of it running, at its sizes, in its project, with its secrets. |
network |
NetworkRules | No | Where it may connect out from its first start, as setNetwork takes it; the open internet behind every machine's walls when omitted. |
env |
object of strings | No | Environment variables for every command and process in it and its start, at most 32 and 32768 bytes of names and values; values are never answered. A copy keeps them. |
MachineReady
How a create's wait for its start's ready check (start.readyPort, start.readyCommand) went.
| Field | Type | Required | Description |
|---|---|---|---|
state |
one of ready, timeout, not_running |
Yes | ready (the check passed), timeout (not within readyTimeoutSeconds), or not_running (it never ran). |
waitedMs |
integer | Yes | How long it waited, in milliseconds. |
Sandbox
A sandbox.
| Field | Type | Required | Description |
|---|---|---|---|
vcpu |
integer | No | Its vCPUs. At least 1. Default: 2. |
memoryGB |
number | No | Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (1.5). At least 1. Default: 4. |
diskGB |
number | No | Its disk in GB (1 GB is 1,024 MiB), to the MiB. At least 1. Default: 4. |
image |
string | No | The image it boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
secrets |
list of string | No | The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. At most 64 items. |
start |
MachineStart | No | The command it starts at every fresh boot and keeps running, as a service: a web server, a runner, a desktop. A wake with its memory kept does not start it again. Its image's when omitted. |
user |
one of runtime, root |
No | Who every command, process, terminal and code run in it runs as when the call names no user: runtime (uid 1000, with passwordless sudo) or root. Its image's when omitted, else runtime. |
id |
string | Yes | Its ID. |
object |
one of sandbox, function, app, site, ci, browser, desktop, notebook, workspace, container, build |
Yes | Always sandbox. |
name |
string | No | Its name, unique in its project. |
state |
one of starting, running, paused, deleted, error |
Yes | Where it is. |
labels |
labels (keys under runtime. are Runtime's) |
Yes | Its labels. |
createdAt |
string (RFC 3339) | No | When it was created. |
deletedAt |
string (RFC 3339) | No | When it was deleted: a delete's answer alone. |
revision |
integer | No | Its revision, changed by every change to it: what an update's If-Match names. |
idlePauseSeconds |
integer | No | Seconds with nothing happening before it pauses; 0 never. Default: 300. |
maxCost |
string (US dollars, decimal) | No | The most it may cost in all, in US dollars; none when it has no such cap. |
exitCode |
integer | No | Its run's exit code, once its run ended; none for one a signal or its timeout ended. |
endedAt |
string (RFC 3339) | No | When its run ended. |
ready |
MachineReady | No | A create's answer alone, for a start with a ready check: how its wait went. |
Terminal
A terminal's size.
| Field | Type | Required | Description |
|---|---|---|---|
cols |
integer | Yes | Its columns. At least 1. At most 65535. |
rows |
integer | Yes | Its rows. At least 1. At most 65535. |
ExecRequest
A command to run: to its end, or started and answered at once (wait: false).
| Field | Type | Required | Description |
|---|---|---|---|
cmd |
string (run by bash -lc) or list of strings (the program and its arguments) |
Yes | The command: text, run by bash -lc ("npm test"), or a list, the program and its arguments run without a shell (["npm", "test"]). |
cwd |
string | No | The directory it runs in; the user's home when omitted. |
env |
object of strings | No | Environment variables to add. |
stdin |
string (base64) | No | Bytes sent to its standard input. |
timeoutSeconds |
number | No | Seconds it may run before it is stopped (1.5 for 1,500 ms); it runs to its end when omitted or 0. At least 0. |
stream |
boolean | No | Answer as NDJSON events while it runs (start, stdout, stderr, exit), as Accept: application/x-ndjson does. |
wait |
boolean | No | Wait for it to end and return it with its output. False returns it at once, running: read its output with processes.output, send it input with processes.write and signals with processes.signal. Default: true. |
stdinOpen |
boolean | No | Keep its standard input open for processes.write; not with stdin, and not with a wait for its end. |
outputEncoding |
one of utf8, base64 |
No | How processes.output answers its output. Default: "utf8". |
pty |
Terminal | No | Run it on a terminal of this size: its input, output and controlling terminal; not with a wait for its end. |
user |
one of runtime, root |
No | Who it runs as: runtime (uid 1000, with passwordless sudo) or root; the sandbox's user when omitted. |
Process
A process.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Its ID. |
object |
one of process |
Yes | Always process. |
state |
one of running, exited, killed, timed_out |
Yes | Where it is. |
exitCode |
integer | No | Its exit code once it exited; negative when a signal ended it. |
command |
string | Yes | The command it runs. |
cwd |
string | No | The directory it runs in. |
pty |
boolean | Yes | It runs on a terminal. |
stdinOpen |
boolean | Yes | Its standard input is open for processes.write. |
stdinOffset |
integer | Yes | Bytes of input it has taken. |
outputEncoding |
one of utf8, base64 |
Yes | How its output is answered. |
startedAt |
string (RFC 3339) | Yes | When it started. |
endedAt |
string (RFC 3339) | No | When it ended. |
timeoutSeconds |
number | No | Seconds it may run before it is killed. |
outputBytes |
integer | Yes | Bytes of output it has written: the cursor past its last. |
firstOffset |
integer | Yes | The oldest byte of its output still kept. |
stdout |
string | No | What it wrote to standard output, as UTF-8: given once an exec waited for its end. |
stderr |
string | No | What it wrote to standard error, as UTF-8: given once an exec waited for its end. |
stdoutTruncated |
boolean | No | stdout holds only part of what it wrote (its first 1 MiB). |
stderrTruncated |
boolean | No | stderr holds only part of what it wrote (its first 1 MiB). |
durationSeconds |
number | No | How long it ran, in seconds, to the millisecond, once it ended. |
FileWritten
A file written.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Its path. |
size |
integer | Yes | Its size in bytes, after the write. |
sha256 |
string | No | Its SHA-256 in hex: given for a file written whole. |
offset |
integer | No | Where the bytes were written: given for a write at an offset. |
OutputChunk
Some of a process's output.
| Field | Type | Required | Description |
|---|---|---|---|
offset |
integer | Yes | Where it starts in the process's output. |
stream |
one of stdout, stderr |
Yes | The stream it was written to. |
text |
string | Yes | It, as text. |
base64 |
string (base64) | No | It, as bytes, when the process answers base64. |
ProcessOutput
A process's output after a cursor.
| Field | Type | Required | Description |
|---|---|---|---|
chunks |
list of OutputChunk | Yes | The output, in the order it was written. |
nextCursor |
integer | Yes | The cursor to read on from. |
truncated |
boolean | Yes | Output past the cursor was dropped before it was read. |
droppedBytes |
integer | Yes | How many bytes were dropped. |
process |
Process | No | The process. |
ProcessInput
Input to send a process.
| Field | Type | Required | Description |
|---|---|---|---|
data |
string (base64) | No | The bytes. |
offset |
integer | No | Bytes of input sent before these (its stdinOffset): a resend is then never taken twice. They go after every other write when omitted. |
eof |
boolean | No | Close its input after these (^D on a terminal). |
ProcessWritten
Input a process took.
| Field | Type | Required | Description |
|---|---|---|---|
offset |
integer | Yes | Bytes of input it has taken in all. |
process |
Process | No | The process. |
ProcessSignal
A signal to send a process and its group.
| Field | Type | Required | Description |
|---|---|---|---|
signal |
one of SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2, SIGKILL |
No | The signal; SIGTERM when omitted. |
ProcessList
A machine's processes, newest first.
| Field | Type | Required | Description |
|---|---|---|---|
items |
list of Process | Yes | Each process. |
FileRemove
A file, a link or a directory to remove.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Its path. |
recursive |
boolean | No | A directory with its contents; refused for a directory with contents when omitted. |
FileRemoved
A file, a link or a directory removed.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Its path. |
removed |
boolean | Yes | It was there and is removed; false when it was missing. |
FileInfo
A path in a sandbox: what is there, if anything.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Its path. |
exists |
boolean | Yes | Something is there. |
name |
string | No | Its last part. |
type |
one of file, directory, symlink, other |
No | What it is: file, directory, symlink or other. |
size |
integer | No | Its size in bytes. |
mode |
string | No | Its permissions, in octal (0644). |
modifiedAt |
string (RFC 3339) | No | When it last changed. |
uid |
integer | No | Its owner's user ID. |
gid |
integer | No | Its group's ID. |
symlinkTarget |
string | No | Where a link points. |
FileList
What a directory holds, in path order.
| Field | Type | Required | Description |
|---|---|---|---|
items |
list of FileInfo | Yes | Each entry. |
truncated |
boolean | Yes | There were more entries than limit. |
FolderUnpacked
A folder unpacked.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The folder. |
received |
integer | Yes | The archive's bytes tar took. |
FolderUploadBegin
A folder upload to begin: a tar archive sent in parts, unpacked into a folder as they arrive.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The folder, absolute and plain, such as /workspace/app: made with its parents. |
gzip |
boolean | No | The archive is gzip-compressed (.tar.gz). Default: false. |
user |
one of runtime, root |
No | Who unpacks it: runtime or root; the machine's user when omitted. |
FolderUpload
A folder upload begun: its parts go to it in order, then its commit.
| Field | Type | Required | Description |
|---|---|---|---|
uploadId |
string | Yes | Its ID, which its parts, its commit and its abort name. |
path |
string | Yes | The folder it unpacks into. |
gzip |
boolean | Yes | The archive is gzip-compressed. |
chunkBytes |
integer | Yes | The most bytes a part should carry. |
FolderUploadReceived
A folder upload's part taken.
| Field | Type | Required | Description |
|---|---|---|---|
received |
integer | Yes | The archive's bytes tar has taken so far: the next part's offset. |
FolderUploadAborted
A folder upload ended unfinished.
| Field | Type | Required | Description |
|---|---|---|---|
aborted |
boolean | Yes | Always true: tar was stopped; what it unpacked stays. |
FileMkdir
A directory to make.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Its path. |
parents |
boolean | No | Its parents are made too; true when omitted. |
FileMade
A directory made.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Its path. |
created |
boolean | Yes | It was made; false when it was there already. |
FileRename
A file, a link or a directory to move.
| Field | Type | Required | Description |
|---|---|---|---|
from |
string | Yes | Where it is. |
to |
string | Yes | Where it goes. |
overwrite |
boolean | No | Replace what is at to; refused 409 when something is there and this is omitted. |
sha256 |
string | No | The file's SHA-256 in hex: only a file whose bytes hash to it moves. |
size |
integer | No | The file's size in bytes: only a file of this size, every byte of it written, moves. At least 0. |
FileRenamed
A file, a link or a directory moved.
| Field | Type | Required | Description |
|---|---|---|---|
from |
string | Yes | Where it was. |
to |
string | Yes | Where it is now. |
size |
integer | No | Its size in bytes: given for a move checked by sha256. |
sha256 |
string | No | Its SHA-256 in hex: given for a move checked by sha256. |
FileLinkCreate
A file link to make: an expiring address for one file of a sandbox (or, with archive, a folder) that anyone may open with no API key.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | The file's absolute path in the sandbox. For GET it must exist when the link is made. |
method |
one of GET, PUT |
No | GET (default): a download link. PUT: an upload link; the request's body becomes the file. |
expiresInSeconds |
integer | No | How long the link works, in seconds. At least 60. At most 604800. Default: 3600. |
filename |
string | No | Download as this name (Content-Disposition: attachment). Without it a picture, video, sound or plain text shows in the browser; anything else downloads. |
maxBytes |
integer | No | PUT only: the largest body the link takes, in bytes; 5 GiB by default and at most. At least 0. At most 5368709120. |
wake |
boolean | No | false: a paused sandbox is not woken for the link, which answers 409 sandbox_paused. Unset or true: it is woken. |
archive |
boolean | No | GET only: path is a folder, downloaded as a .tar.gz. Default: false. |
FileLink
A file link.
| Field | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | Its address, opened with no key: GET to download, PUT the file's bytes to upload. |
method |
one of GET, PUT |
Yes | GET or PUT. |
path |
string | Yes | The file's path in the sandbox. |
sandboxId |
string | Yes | The sandbox. |
expiresAt |
string (RFC 3339) | Yes | When it stops working. |
filename |
string | No | The name it downloads as. |
maxBytes |
integer | No | The largest body an upload link takes. |
archive |
boolean | No | It downloads a folder as a .tar.gz. |
FileLinksRevoked
A sandbox's file links ended.
| Field | Type | Required | Description |
|---|---|---|---|
sandboxId |
string | Yes | The sandbox. |
revokedAt |
string (RFC 3339) | Yes | When they ended: every link made before it. |
SandboxNetwork
Where a sandbox may connect out.
| Field | Type | Required | Description |
|---|---|---|---|
allowOutbound |
list of string | No | The only places it may reach, each a host, *. and a name for every name under it, an address or a CIDR ([ and ] around an IPv6 address), every port when it names none; :port for that port alone, on a host name for a port beyond 80 and 443, which go together. * is every public host. Every public host when omitted; nothing when empty. |
denyOutbound |
list of string | No | Places it may never reach, written as in allowOutbound with no port: a deny wins over every allow. |
id |
string | Yes | The sandbox's ID. |
MetricPoint
A machine's CPU and memory as its host measures them from the machine's own cgroup, never by a call into the machine, so reading them does not wake it or keep it awake. Either the current reading (over the host's last 5 seconds, with disk and pressure) or one step of a window (averaged over the time the machine ran in it).
| Field | Type | Required | Description |
|---|---|---|---|
at |
string (RFC 3339) | Yes | When it was read; for a step, where the step starts. |
cpuPercent |
number | Yes | Its CPU, as a percent of all its vCPUs (0 to 100). |
cpuCores |
number | No | The same as a number of cores. |
cpuPeakPercent |
number | No | Its busiest minute, as a percent of all its vCPUs. |
cpuWaitPercent |
number | No | Percent of the last 10 seconds some task of it waited for a CPU. |
memoryStallPercent |
number | No | Percent of the last 10 seconds some task of it waited for memory. |
memoryBytes |
integer | Yes | Memory it holds, in bytes: its resident memory on its host. |
memoryPeakBytes |
integer | No | The most memory it has held, in bytes; for a step, its highest minute's average. |
samples |
integer | Yes | How many measures it is made of: two reads for the reading now; for a step, the minutes the host measured it in. |
diskReadBytesPerSecond |
number | No | Bytes its disks read a second. |
diskWriteBytesPerSecond |
number | No | Bytes its disks wrote a second. |
diskReadOpsPerSecond |
number | No | Reads its disks completed a second. |
diskWriteOpsPerSecond |
number | No | Writes its disks completed a second. |
MetricsBase
A sandbox's CPU and memory over a time window, in steps, and its current reading (with disk and pressure) while it runs. Steps are returned in every state, including paused and stopped. Ranges: 15m and 1h in 60-second steps, 6h in 120-second steps, 24h in 480-second steps, 7d and 30d in 1-hour steps. Defaults to 1h.
| Field | Type | Required | Description |
|---|---|---|---|
state |
one of starting, running, paused, deleted, error |
Yes | Its state. |
range |
one of 15m, 1h, 6h, 24h, 7d, 30d |
Yes | The window asked for. |
stepSeconds |
integer | Yes | The window's step, in seconds. |
since |
string (RFC 3339) | Yes | Where the window starts: the start of the step that holds the range's start. |
until |
string (RFC 3339) | Yes | Where it ends: now. |
vcpu |
integer | Yes | Its vCPUs. |
memoryLimitBytes |
integer | Yes | Its memory, in bytes. |
diskLimitBytes |
integer | Yes | Its disk, in bytes. |
latest |
MetricPoint | No | The reading taken now; none when it is not running or its host could not read it. |
points |
list of MetricPoint | Yes | The window's steps, oldest first, each averaged over the time the sandbox ran in it. Steps in which it did not run are omitted. A minute appears about a minute after it ends; latest holds the current reading. |
SandboxMetrics
A sandbox's metrics.
| Field | Type | Required | Description |
|---|---|---|---|
state |
one of starting, running, paused, deleted, error |
Yes | Its state. |
range |
one of 15m, 1h, 6h, 24h, 7d, 30d |
Yes | The window asked for. |
stepSeconds |
integer | Yes | The window's step, in seconds. |
since |
string (RFC 3339) | Yes | Where the window starts: the start of the step that holds the range's start. |
until |
string (RFC 3339) | Yes | Where it ends: now. |
vcpu |
integer | Yes | Its vCPUs. |
memoryLimitBytes |
integer | Yes | Its memory, in bytes. |
diskLimitBytes |
integer | Yes | Its disk, in bytes. |
latest |
MetricPoint | No | The reading taken now; none when it is not running or its host could not read it. |
points |
list of MetricPoint | Yes | The window's steps, oldest first, each averaged over the time the sandbox ran in it. Steps in which it did not run are omitted. A minute appears about a minute after it ends; latest holds the current reading. |
id |
string | Yes | The sandbox's ID. |
ForkRequest
Copies of a sandbox to make, as it is now.
| Field | Type | Required | Description |
|---|---|---|---|
count |
integer | No | How many. At least 1. At most 100. Default: 1. |
name |
string | No | Its name, for a fork of one. |
labels |
labels (keys under runtime. are Runtime's) |
No | Labels each copy gets. |
secrets |
list of string | No | The secrets each copy gets, by name: only these, never one its source may not use; its source's when omitted. At most 64 items. |
maxCost |
string (US dollars, decimal) | No | The most each may cost in all, in US dollars ("5.00"): once one has cost that it pauses, as a create's maxCost. When omitted, the least of its key's caps and its source's maxCost. |
Forked
The copies a fork made, each running.
| Field | Type | Required | Description |
|---|---|---|---|
sandboxes |
list of Sandbox | Yes | The copies, in the order made. |
SnapshotRequest
A snapshot of a sandbox to take.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | No | Its name, unique among the project's snapshots. |
labels |
labels (keys under runtime. are Runtime's) |
No | Labels to find it by. |
image |
string | No | Keeps its disk alone, synced, as the next version of the image of this name (name:1, name:2, ...) in place of a snapshot: an image machines are created from, each booting fresh over a disk of its own. Its memory is not kept; name is ignored. |
start |
MachineStart | No | With image: the command each machine created from the image starts at every fresh boot; the sandbox's own when omitted. |
Stored
Stored data: a snapshot, an image or a volume.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Its ID. |
object |
one of snapshot, image, volume |
Yes | Its kind: snapshot, image or volume. |
name |
string | No | Its name, unique in its project among its kind. |
state |
one of making, ready, failed, deleted |
Yes | Where it is. |
labels |
labels (keys under runtime. are Runtime's) |
Yes | Its labels. |
sizeBytes |
integer | Yes | What it was made to hold, in bytes. |
storedBytes |
integer | Yes | What it holds now, in bytes. |
parentId |
string | No | What it was made from (a snapshot's sandbox, an image's base), if anything. |
attachedTo |
string | No | The machine it is attached to now, if any. |
createdAt |
string (RFC 3339) | No | When it was made. |
version |
integer | No | An image's version of its name: each build or keep of a name is its next. |
tags |
list of string | No | An image's tags, each name:tag. |
error |
string | No | Why an image's build failed. |
deletedAt |
string (RFC 3339) | No | When it was deleted: a delete's answer, its state deleted. |
MachineUpdate
A change to a machine's settings: each field left out stays as it is.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | No | Its name, unique in its project. |
labels |
labels (keys under runtime. are Runtime's) |
No | Its labels, in place of its own; those under runtime. are kept. |
idlePauseSeconds |
integer | No | Seconds with nothing happening before it pauses, 60 to 86400; 0 never. |
vcpu |
integer | No | Its vCPUs, grown while it runs; a running sandbox's vCPUs only grow. At least 1. |
memoryGB |
number | No | Its memory in GB (1 GB is 1,024 MiB), grown while it runs; a running sandbox's memory only grows. At least 1. |
diskGB |
number | No | Its disk in GB (1 GB is 1,024 MiB), grown while it runs, its file system with it; a disk only grows. At least 1. |
user |
one of runtime, root |
No | Who its commands run as from now when a call names no user: runtime or root. Running ones keep theirs. |
env |
object of strings | No | Environment variables to set, each over its own value, the others kept: the update answers once a running one holds the change (a paused one is given it at its wake), so each process, command and terminal it starts after the answer has them; processes already running keep the environment they started with. At most 32 variables and 32768 bytes of names and values in all, as a create's; values are never answered. |
removeEnv |
list of string | No | Names of environment variables to take out, the same way: gone from the next process it starts; processes already running keep them. |
maxCost |
string (US dollars, decimal) | No | The most it may cost in all, in US dollars ("5.00"), in place of its own: one paused at its old maxCost wakes at its next call under a higher one. |
Action
One step of an act: a mouse move, click, drag or scroll, typed text, a key chord, or a wait.
| Field | Type | Required | Description |
|---|---|---|---|
type |
one of move, click, mouseDown, mouseUp, drag, scroll, type, key, wait |
Yes | What it does: move to x,y; click (at x,y when given, count times, with keys held); mouseDown and mouseUp of button; drag from x,y to toX,toY; scroll by dx,dy wheel clicks (at x,y when given); type text; key the chords in keys; wait ms. |
x |
integer | No | Pixels from the screen's left edge. At least 0. At most 16384. |
y |
integer | No | Pixels from the screen's top edge. At least 0. At most 16384. |
toX |
integer | No | A drag's end, from the left edge. At least 0. At most 16384. |
toY |
integer | No | A drag's end, from the top edge. At least 0. At most 16384. |
button |
one of left, middle, right |
No | The mouse button of a click, a drag, a mouseDown or a mouseUp. Default: "left". |
count |
integer | No | A click's count: 2 a double click, 3 a triple click. At least 1. At most 3. Default: 1. |
dx |
integer | No | A scroll's wheel clicks to the right (negative to the left). At least -100. At most 100. |
dy |
integer | No | A scroll's wheel clicks down (negative up). At least -100. At most 100. |
text |
string | No | The text a type types, as it is: any Unicode, newlines and tabs. At most 8192 characters. |
keys |
string | No | For key, chords pressed in turn, space-separated, each keys joined by + in X keysym names (ctrl+l, Return, ctrl+shift+t); for click and scroll, the modifiers held during it (shift, ctrl+alt). At most 1000 characters. |
ms |
integer | No | A wait's milliseconds. At least 0. At most 10000. |
ActRequest
Steps of the mouse and keyboard, run in order as one command.
| Field | Type | Required | Description |
|---|---|---|---|
actions |
list of Action | Yes | The steps, in order; the act stops at the first that fails. At least 1 item. At most 100 items. |
Point
A point on the screen, in pixels from its top left corner.
| Field | Type | Required | Description |
|---|---|---|---|
x |
integer | Yes | |
y |
integer | Yes |
ScreenSize
The screen's size, in pixels.
| Field | Type | Required | Description |
|---|---|---|---|
width |
integer | Yes | |
height |
integer | Yes |
Acted
The screen once an act's steps ran.
| Field | Type | Required | Description |
|---|---|---|---|
cursor |
Point | Yes | Where the mouse is. |
screen |
ScreenSize | Yes | The screen's size. |