In-sandbox runtime routes

These routes act inside one running sandbox: run commands, read and write files, use git, open terminals and run the coding agent. The SDKs call them for exec, read, write, process, git, terminals, previewLinks and prompt.

Address and authentication

Every route on this page is under the sandbox’s runtime prefix:

https://sandbox.tangle.tools/v1/sandboxes/{id}/runtime{path}

Send your account API key as Authorization: Bearer <key>, or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token; see Authentication. Reads need read access to the sandbox, and every other method needs write access. A request that starts paid work, such as a command or an agent run, resumes a stopped sandbox first. Errors use the shape in Error codes.

Run a command

curl -s -X POST "https://sandbox.tangle.tools/v1/sandboxes/$SANDBOX_ID/runtime/process/spawn" \
  -H "Authorization: Bearer $TANGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"executable": "bash", "args": ["-c", "ls -la"], "blocking": true, "timeoutMs": 30000}'

# client.fetch returns the raw httpx.Response; check status_code yourself.
response = client.fetch(
    "POST",
    f"/v1/sandboxes/{box.id}/runtime/process/spawn",
    json={"executable": "bash", "args": ["-c", "ls -la"], "blocking": True, "timeoutMs": 30000},
)
print(response.status_code, response.json()["data"]["stdout"])

A blocking spawn answers 201 when the command exits:

{
  "success": true,
  "data": { "pid": 412, "command": "bash", "exitCode": 0, "stdout": "...", "stderr": "", "durationMs": 38 }
}

A non-zero exit is still a 201; read exitCode. A command that runs past timeoutMs answers 408 with the output so far.

Commands and processes

POST /process/spawn takes:

Range limits for these fields are on Limits and timeouts.

Managed jobs

A managed job is a process the sandbox records durably, so you can read, resume or cancel it by ID.

Code kernels

A kernel keeps variables between calls, like a notebook.

Files

These routes take the path in a JSON body. A relative path is inside the workspace. Add ?sessionId=<id> to use a session’s own workspace.

Upload, download and directories

These routes take the path in the URL; {path} is the path inside the sandbox.

Chunked uploads

For a file larger than one request can carry, upload it in parts:

The TypeScript SDK’s box.fs.upload(localPath, remotePath) does this for you.

Git

These routes act on the repository in the workspace.

Terminals

See Shells and terminals for the SDK and CLI.

Ports and preview links

See Ports and preview links.

Coding-agent runs

The body names the turn and carries the prompt as parts. Text parts are base64-encoded UTF-8:

{
  "id": "default",
  "parts": [{ "type": "text", "text": "TGlzdCB0aGUgZmlsZXMgaW4gdGhpcyByZXBvc2l0b3J5Lg==" }],
  "sessionId": "optional-session-id",
  "backend": { "type": "<type from GET /v1/backends>" }
}

The SDKs build this body for you; see Run a coding agent and Stream output.

Health

The OpenAPI document describes this prefix as one route, /v1/sandboxes/{id}/runtime/{path}.

Next steps

• Sandboxes and GPU routes: create, stop and delete the sandbox these routes run in.
• Run commands and code: the same operations from the SDKs and CLI.
• Files: reading, writing and uploading from the SDKs.