Run a bounded command
exec sends an argv array by default, streams stdout and stderr, waits for a terminal execution state, and exits non-zero when the remote command fails.
/workspace, OS user sandbox, closed stdin, captured stdout/stderr, and a 600-second remote timeout. Override only what the template and effective policy allow:
--shell only when shell parsing is intentional. Quoting, expansion, pipes, and redirects then follow the template shell and must be treated as code execution.
--background to return the execution resource immediately. Save its ID and inspect it through the API or SDK; background mode does not stream logs in the CLI.
Open an interactive terminal
Work with files safely
File APIs are rooted in approved mounts and reject path escapes and symlink traversal outside those roots. Mutating file actions require the current writer-lease token. Content writes may include an expected checksum; use it to reject a stale overwrite. Recommended editor flow:- Acquire the writer lease and retain its token only in memory.
- Read the file and its checksum/version.
- Submit the write with the lease token and expected checksum.
- On a checksum conflict, reload and merge instead of overwriting.
- Renew an active lease, then release it when editing ends.
Processes and logs
Use a process for a long-lived workload such as a development server. A process retains command metadata, state, readiness, timestamps, and offset-addressed stdout/stderr. Consumers must resume fromnext_offset, handle truncated: true, and stop only when the page is complete and the process is terminal.
Signals, stdin writes, cancellation, and process wait are explicit API operations. Sleep stops running processes; resume restores declared filesystem state and starts a new runtime, not the old process memory.
Interpreter contexts
Interpreter contexts support Python, JavaScript, and TypeScript kernels with ordered run history. Create a context, submit code, inspect the run, and interrupt a stuck run without destroying the sandbox. Reset replaces kernel state. Rich HTML and SVG results are untrusted content. The dashboard sanitizes them and isolates previews. Files written to persistent storage can survive sleep or snapshots; in-memory variables cannot.Agents and retained output
An agent run should record its initiating actor, execution/process IDs, approvals, events, and artifact IDs. Attach credentials through scoped secret bindings rather than command arguments or persisted environment files. In the Agents route, select a run to inspect its thread, current step, linked execution/process, event timeline, requested approval, and produced artifacts. An approval must state the proposed command/action, affected paths or resources, network/secret impact, requester, and expiry. Approve or deny that exact request; approval does not grant broader sandbox permissions or relax effective policy. Cancellation is a durable orchestration action. After cancelling a run, confirm the linked execution/process reaches a terminal state and review partial files/artifacts before starting another run. A failed agent view must link to the canonical sandbox operation or execution failure rather than replace it with a generic agent error. Retain deliverables as artifacts when they must outlive workspace cleanup. Artifact upload is a prepare/upload/complete flow; completion verifies the declared checksum and makes downloads available through current authorization and short-lived URLs.Follow live state
The resumable event stream emits newline-delimited JSON in the CLI. Store the highest processed sequence and reconnect after it:Browser testing
Run browser work and expose private previews.
Troubleshooting
Diagnose failed commands, leases, streams, and readiness.