Skip to content

Ci API reference

A machine that runs a repository's checks to their end (its run) with git, Docker, Node, Bun, Python and a compiler, and is stopped then. As an Actions runner, it starts GitHub's runner for the one job of its just-in-time configuration (start runtime-runner, RUNNER_JITCONFIG in its environment) and ends with it.

Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.

Its states: starting, running, paused, deleted, error.

Updated .md

Endpoints#

Method Path Description
POST /v2/ci Create a ci
GET /v2/ci/{id} Get a ci
GET /v2/ci List ci
DELETE /v2/ci/{id} Delete a ci
POST /v2/ci/{id}:pause pause
POST /v2/ci/{id}:resume resume
POST /v2/ci/{id}:exec exec
GET /v2/ci/{id}/files read
PUT /v2/ci/{id}/files write
GET /v2/ci/{id}/processes/{process}/output processOutput
POST /v2/ci/{id}/processes/{process}:write writeProcess
POST /v2/ci/{id}/processes/{process}:signal signalProcess
GET /v2/ci/{id}/processes listProcesses
POST /v2/ci/{id}/files:remove remove
GET /v2/ci/{id}/files/stat stat
GET /v2/ci/{id}/files/list listFiles
GET /v2/ci/{id}/files/archive downloadFolder
PUT /v2/ci/{id}/files/archive uploadFolder
POST /v2/ci/{id}/files/archive/uploads beginFolderUpload
PUT /v2/ci/{id}/files/archive/uploads/{upload} writeFolderUpload
POST /v2/ci/{id}/files/archive/uploads/{upload}:commit commitFolderUpload
POST /v2/ci/{id}/files/archive/uploads/{upload}:abort abortFolderUpload
POST /v2/ci/{id}/files:mkdir mkdir
POST /v2/ci/{id}/files:rename rename
POST /v2/ci/{id}/files:link link
POST /v2/ci/{id}/files:revokeLinks revokeLinks
GET /v2/ci/{id}/network getNetwork
GET /v2/ci/{id}/metrics metrics
PUT /v2/ci/{id}/network setNetwork
POST /v2/ci/{id}:fork fork
POST /v2/ci/{id}:snapshot snapshot
POST /v2/ci/{id}:update update
GET /v2/ci/{id}/screenshot screenshot
POST /v2/ci/{id}:act act

Create a ci#

POST /v2/ci

Creates a CI machine. Asked again with the same Idempotency-Key, it returns the same ci.

Its action, for a key's grant: ci:create.

Body: a SandboxCreate.

Returns a Sandbox.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci" \  -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.ci.create();
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.create()
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.create
Terminalruntime ci create

Get a ci#

GET /v2/ci/{id}

Returns a CI machine.

Its action, for a key's grant: ci: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/ci/CI_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ci.get("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.get("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.get("CI_ID")
Terminalruntime ci get CI_ID

List ci#

GET /v2/ci

Lists the project's ci, newest first.

Its action, for a key's grant: ci:list.

Query:

Field Type Required Description
state string No Only those in these states, comma-separated.
name string No Only the ci 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/ci" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ci.list();
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.list()
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.list
Terminalruntime ci list

Delete a ci#

DELETE /v2/ci/{id}

Deletes a CI machine, its memory and its disk.

Its action, for a key's grant: ci:delete.

Path: id.

Returns a Sandbox.

Examples:

Terminalcurl -X DELETE "https://api.withruntime.com/v2/ci/CI_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ci.delete("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.delete("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.delete("CI_ID")
Terminalruntime ci delete CI_ID

pause#

POST /v2/ci/{id}:pause

Pauses a CI machine with its memory and disk kept. A call to it resumes it.

Its action, for a key's grant: ci:pause.

Path: id.

Returns a Sandbox.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.pause("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.pause("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.pause("CI_ID")
Terminalruntime ci pause CI_ID

resume#

POST /v2/ci/{id}:resume

Resumes a paused ci where it was, its memory and processes as they were.

Its action, for a key's grant: ci:wake.

Path: id.

Returns a Sandbox.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.resume("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.resume("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.resume("CI_ID")
Terminalruntime ci resume CI_ID

exec#

POST /v2/ci/{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 ci 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: ci:exec.

Path: id.

Body: a ExecRequest.

Returns a Process.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.exec("CI_ID", { cmd: "echo hello" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.exec("CI_ID", cmd="echo hello")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.exec("CI_ID", cmd: "echo hello")
Terminalruntime ci exec CI_ID -- echo hello

read#

GET /v2/ci/{id}/files

Returns a file's bytes.

Its action, for a key's grant: ci: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/ci/CI_ID/files?path=/tmp/hello.txt" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -o out.bin
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ci.read("CI_ID", { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.read("CI_ID", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.read("CI_ID", path: "/tmp/hello.txt")
Terminalruntime ci read CI_ID --path /tmp/hello.txt

write#

PUT /v2/ci/{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: ci: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/ci/CI_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.ci.write("CI_ID", new TextEncoder().encode("hello\n"), { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.write("CI_ID", b"hello\n", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.write("CI_ID", "hello\n", path: "/tmp/hello.txt")
Terminalruntime ci write CI_ID --path /tmp/hello.txt < hello.txt

processOutput#

GET /v2/ci/{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: ci: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/ci/CI_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.ci.processOutput("CI_ID", "PROCESS_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.process_output("CI_ID", "PROCESS_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.process_output("CI_ID", "PROCESS_ID")
Terminalruntime ci process-output CI_ID PROCESS_ID

writeProcess#

POST /v2/ci/{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: ci:exec.

Path: id, process.

Body: a ProcessInput.

Returns a ProcessWritten.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.writeProcess("CI_ID", "PROCESS_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.write_process("CI_ID", "PROCESS_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.write_process("CI_ID", "PROCESS_ID")
Terminalruntime ci write-process CI_ID PROCESS_ID

signalProcess#

POST /v2/ci/{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: ci:exec.

Path: id, process.

Body: a ProcessSignal.

Returns a Process.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.signalProcess("CI_ID", "PROCESS_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.signal_process("CI_ID", "PROCESS_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.signal_process("CI_ID", "PROCESS_ID")
Terminalruntime ci signal-process CI_ID PROCESS_ID

listProcesses#

GET /v2/ci/{id}/processes

Lists a CI machine's processes, newest first: those running and those that ended lately.

Its action, for a key's grant: ci:exec.

Path: id.

Returns a ProcessList.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/ci/CI_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.ci.listProcesses("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.list_processes("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.list_processes("CI_ID")
Terminalruntime ci list-processes CI_ID

remove#

POST /v2/ci/{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: ci:write.

Path: id.

Body: a FileRemove.

Returns a FileRemoved.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.remove("CI_ID", { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.remove("CI_ID", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.remove("CI_ID", path: "/tmp/hello.txt")
Terminalruntime ci remove CI_ID --path /tmp/hello.txt

stat#

GET /v2/ci/{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: ci: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/ci/CI_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.ci.stat("CI_ID", { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.stat("CI_ID", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.stat("CI_ID", path: "/tmp/hello.txt")
Terminalruntime ci stat CI_ID --path /tmp/hello.txt

listFiles#

GET /v2/ci/{id}/files/list

Lists a directory's entries in path order, to a depth.

Its action, for a key's grant: ci: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/ci/CI_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.ci.listFiles("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.list_files("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.list_files("CI_ID")
Terminalruntime ci list-files CI_ID

downloadFolder#

GET /v2/ci/{id}/files/archive

Returns a folder as a tar archive (application/x-tar, or application/gzip with gzip), packed by tar in the ci 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 CI machine. A paused ci is woken first.

Its action, for a key's grant: ci: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 ci'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/ci/CI_ID/files/archive?path=/tmp/hello.txt" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -o out.bin
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ci.downloadFolder("CI_ID", { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.download_folder("CI_ID", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.download_folder("CI_ID", path: "/tmp/hello.txt")
Terminalruntime ci download-folder CI_ID --path /tmp/hello.txt

uploadFolder#

PUT /v2/ci/{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 ci 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 ci is woken first.

Its action, for a key's grant: ci: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 ci's user when omitted.

Body: the bytes, application/octet-stream.

Returns a FolderUnpacked.

Examples:

Terminalcurl -X PUT "https://api.withruntime.com/v2/ci/CI_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.ci.uploadFolder("CI_ID", new TextEncoder().encode("hello\n"), { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.upload_folder("CI_ID", b"hello\n", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.upload_folder("CI_ID", "hello\n", path: "/tmp/hello.txt")
Terminalruntime ci upload-folder CI_ID --path /tmp/hello.txt < hello.txt

beginFolderUpload#

POST /v2/ci/{id}/files/archive/uploads

Begins a folder's upload in parts: tar starts in the ci, 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 ci is woken first.

Its action, for a key's grant: ci:write.

Path: id.

Body: a FolderUploadBegin.

Returns a FolderUpload.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.beginFolderUpload("CI_ID", { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.begin_folder_upload("CI_ID", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.begin_folder_upload("CI_ID", path: "/tmp/hello.txt")
Terminalruntime ci begin-folder-upload CI_ID --path /tmp/hello.txt

writeFolderUpload#

PUT /v2/ci/{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: ci: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/ci/CI_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.ci.writeFolderUpload("CI_ID", "UPLOAD_ID", new TextEncoder().encode("hello\n"));
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.write_folder_upload("CI_ID", "UPLOAD_ID", b"hello\n")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.write_folder_upload("CI_ID", "UPLOAD_ID", "hello\n")
Terminalruntime ci write-folder-upload CI_ID UPLOAD_ID < hello.txt

commitFolderUpload#

POST /v2/ci/{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: ci:write.

Path: id, upload.

Returns a FolderUnpacked.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.commitFolderUpload("CI_ID", "UPLOAD_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.commit_folder_upload("CI_ID", "UPLOAD_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.commit_folder_upload("CI_ID", "UPLOAD_ID")
Terminalruntime ci commit-folder-upload CI_ID UPLOAD_ID

abortFolderUpload#

POST /v2/ci/{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: ci:write.

Path: id, upload.

Returns a FolderUploadAborted.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.abortFolderUpload("CI_ID", "UPLOAD_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.abort_folder_upload("CI_ID", "UPLOAD_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.abort_folder_upload("CI_ID", "UPLOAD_ID")
Terminalruntime ci abort-folder-upload CI_ID UPLOAD_ID

mkdir#

POST /v2/ci/{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: ci:write.

Path: id.

Body: a FileMkdir.

Returns a FileMade.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.mkdir("CI_ID", { path: "/tmp/hello.txt" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.mkdir("CI_ID", path="/tmp/hello.txt")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.mkdir("CI_ID", path: "/tmp/hello.txt")
Terminalruntime ci mkdir CI_ID --path /tmp/hello.txt

rename#

POST /v2/ci/{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: ci:write.

Path: id.

Body: a FileRename.

Returns a FileRenamed.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.rename("CI_ID", { from: "example", to: "example" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.rename("CI_ID", from="example", to="example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.rename("CI_ID", from: "example", to: "example")
Terminalruntime ci rename CI_ID --from example --to example

getNetwork#

GET /v2/ci/{id}/network

Returns where a CI machine may connect out.

Its action, for a key's grant: ci:get.

Path: id.

Returns a SandboxNetwork.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/ci/CI_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.ci.getNetwork("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.get_network("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.get_network("CI_ID")
Terminalruntime ci get-network CI_ID

metrics#

GET /v2/ci/{id}/metrics

Returns a CI machine's CPU, memory, disks and pressure, as its host reads them from the ci's own cgroup over a fifth of a second: never a call into the ci, 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: ci: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/ci/CI_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.ci.metrics("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.metrics("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.metrics("CI_ID")
Terminalruntime ci metrics CI_ID

setNetwork#

PUT /v2/ci/{id}/network

Replaces where a CI machine 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: ci:network.

Path: id.

Body: a NetworkRules.

Returns a SandboxNetwork.

Examples:

Terminalcurl -X PUT "https://api.withruntime.com/v2/ci/CI_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.ci.setNetwork("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.set_network("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.set_network("CI_ID")
Terminalruntime ci set-network CI_ID

fork#

POST /v2/ci/{id}:fork

Copies a CI machine 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: ci:fork.

Path: id.

Body: a ForkRequest.

Returns a Forked.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.fork("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.fork("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.fork("CI_ID")
Terminalruntime ci fork CI_ID

snapshot#

POST /v2/ci/{id}:snapshot

Keeps a CI machine's memory and disk as they are now, a snapshot to start ci from; with image, its disk alone as that image's next version. The ci runs on. Asked again with the same Idempotency-Key, it returns the same snapshot.

Its action, for a key's grant: ci:snapshot.

Path: id.

Body: a SnapshotRequest.

Returns a Stored.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.snapshot("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.snapshot("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.snapshot("CI_ID")
Terminalruntime ci snapshot CI_ID

update#

POST /v2/ci/{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: ci:update.

Path: id.

Body: a MachineUpdate.

Returns a Sandbox.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.update("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.update("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.update("CI_ID")
Terminalruntime ci update CI_ID

screenshot#

GET /v2/ci/{id}/screenshot

Returns what a CI machine'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 ci is resumed first.

Its action, for a key's grant: ci: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/ci/CI_ID/screenshot" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -o out.bin
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.ci.screenshot("CI_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.screenshot("CI_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.screenshot("CI_ID")
Terminalruntime ci screenshot CI_ID

act#

POST /v2/ci/{id}:act

Moves, clicks, drags and scrolls the mouse and types on the keyboard of a CI machine'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 ci is resumed first.

Its action, for a key's grant: ci:exec.

Path: id.

Body: a ActRequest.

Returns a Acted.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/ci/CI_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.ci.act("CI_ID", { actions: [{ type: "move" }] });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.ci.act("CI_ID", actions=[{"type": "move"}])
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.ci.act("CI_ID", actions: [{ type: "move" }])
Terminalruntime ci act CI_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.

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.
Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial