Skip to main content
This guide walks the sandbox verbs: create from an image, inspect, execute, snapshot, branch, and delete.
The runtime under these verbs is being rebuilt in stages. Create, list/get, TTL updates, and delete work end to end today, as do exec, stop/start, and snapshot and branch. ssh is complete, but it needs an endpoint that is off unless your deployment enables it. The authoritative status list is what’s live today.

​
Create

Create accepts the request and the CLI waits until the sandbox is running. With no source flag, the sandbox starts from the platform default image: a small general-purpose base with Python and Node preinstalled. The receipt and JSON output report the image that was selected and the ambient run id that receives this sandbox’s telemetry. To pick the source yourself, pass --image <ref> for a fresh environment or --from <snapshot> to branch from saved state (pass both only to restore onto a different image):
Use a digest-pinned image when reproducibility matters, and pick an image whose entrypoint keeps running: the sandbox runs the image’s own entrypoint. Compute resources are declarative: --cpus and --memory-mb set the shape the sandbox is guaranteed, and CPU may burst into idle capacity beyond its request. --cpus accepts decimal cores from 0.05 through 128, with up to three fractional digits. Omitted values resolve to the deployment’s defaults at admission, and the resolved shape is echoed on every readout — the create receipt, get, and list all show what was actually admitted, never a blank. JSON responses spell CPU as exact integer cpu_millis; 50 means 0.05 CPU and 1000 means one CPU. Automated callers that may retry an ambiguous create should pass a stable replay key:
Reusing the key replays the original accepted sandbox instead of creating a duplicate.

​
Stop when idle

Give a sandbox an idle timeout when it should release compute after a quiet period:
The timeout is measured in seconds and may be set from 60 through 86400. sandbox get shows both the resolved timeout and, while the sandbox is running, its next idle deadline. Execs, SSH sessions, and sandbox updates advance that deadline. Idle stop discards a standard workspace; use durable storage when /workspace must survive the stop. For a foreground command that may run longer than a buffered API request, run it through the managed SSH session. The session keeps the sandbox active while the command lives and releases that hold when it exits:
If the sandbox stops for idleness, sandbox ssh wakes it before opening the session. sandbox exec does not wake a stopped sandbox and returns a stopped-state conflict, so start it explicitly before the next buffered command. Apply any timeout, TTL, or metadata change while it is stopped, then start it as a separate operation:
Omit --idle-timeout to use the deployment default. The interactive hosted profile uses 1800 seconds when idle stopping is enabled; a self-hosted deployment may leave it disabled.

​
Inspect

get shows the observed lifecycle state, the resolved compute shape, who created the sandbox, expiry, and metadata. A sandbox created from a snapshot reads from: <snapshot> and resolves the image it runs through that snapshot. list puts the compact resource shape and the creator in the table, and filters by state, exact name, and exact metadata entries; pass --all to include retained terminated records. Every sandbox verb accepts either the server-issued id or the sandbox’s name. A reference in canonical id shape — sbx- followed by 40 lowercase hex characters — is always treated as an id and addresses that sandbox directly; anything else is looked up as an exact name within the selected project. Ids take precedence, so a name that happens to be minted in the id shape cannot redirect an id-addressed command.

​
Execute a command

exec submits one buffered command, relays its stdout/stderr, and exits with the command’s exit code. It also records that command’s process lifecycle and output under the sandbox’s ambient run; no capture flag or guest credential is required. The full contract (timeouts, output caps, retries) is in commands and executions. Query the run id returned by create to inspect entrypoint, exec, SSH, cooperative HTTP, and OTLP activity together:
An explicit create command receives process and stdio supervision. An image’s implicit entrypoint still receives the shared HTTP proxy and OTLP settings, but its unknown command cannot be prepended without changing the image contract. See capture agent telemetry for the exact boundaries.

​
Connect a shell

ssh opens an interactive shell in a running sandbox using stock OpenSSH. There is nothing to set up: the organization-scoped API credential you already use authorizes the connection, hiloop supplies the session’s key material, and the sandbox’s host key is pinned for you, so you are never prompted to accept an unknown host. This verb needs the sandbox SSH endpoint, which an operator enables per deployment and which is off by default; on the hosted service it is currently enabled only in pre-release environments. Where it is off, a connect is refused with unsupported_capability. Everything after -- goes to ssh, options first and then an optional remote command:
A remote command’s exit code becomes the CLI’s exit code, and stdin and stdout pipe as usual. Non-interactive commands are captured like buffered execs. Interactive PTY sessions record their start, end, and terminal output, but not keystrokes/input. The session runs inside your workload container, so it sees the same filesystem and processes that exec does, and -L reaches a port your workload is listening on. Some SSH features are refused by design, including remote port forwarding (-R), agent forwarding, and root login. Both points are covered in interactive access; the connection model is in shell access.

​
Snapshot and branch

Snapshot a sandbox’s disk state, then create new sandboxes from the snapshot; restore, fork, and branch are the same verb:
Snapshots capture disk, not memory or processes. The model (durability receipts, lineage, and fan-out) is covered in snapshots and branching.

​
Stop and start

Stop seals and stops the workload; start wakes it. A stopped sandbox keeps its identity, its name and — on the durable storage class — its /workspace, which reattaches to the sandbox when it starts again. Running processes do not survive a stop; the filesystem does. See lifecycle.

​
Delete

Delete is permanent and idempotent, and the CLI waits for termination. Snapshots are independent resources: deleting a sandbox does not delete the snapshots taken from it.