Sandbox commands

Create, inspect, stop, resume and delete sandboxes; run commands in them; open a shell; and save, restore and branch their disks. Each command lists its flags with defaults, the API request it sends and an example.

tangle sandbox create --name my-box --ssh
tangle exec my-box -- uname -a
tangle snapshot create my-box --tags clean
tangle sandbox delete my-box --force

sandbox create waits up to 120 s for the sandbox to run. Its --timeout is the HTTP timeout in milliseconds; the sandbox’s own limits are --lifetime and --idle-timeout in seconds. A sandbox that hits either limit stops and is not deleted. exec, ssh and the other runtime commands resume it first.

Commands on this page

Create and inspect sandboxes

tangle sandbox create

Create a new sandbox.

Creates a sandbox from flags and, by default, waits up to 120000 ms for it to reach running, then prints its details, SSH command line and URLs.

tangle sandbox create [options]

Request: POST /v1/sandboxes

tangle sandbox create --name my-box --ssh --git-url https://github.com/tangle-network/sandbox-demo

• --wait defaults to true and the CLI defines no --no-wait, so create always waits.
• --timeout is the per-request HTTP timeout in milliseconds, not the sandbox lifetime; use --lifetime and --idle-timeout (seconds) for that.
• --ssh with no --ssh-key, --ssh-keys or --ssh-key-file uploads the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub, id_rsa.pub and fails if none exists.
• Size flags are sent only when typed; an unsized create gets the platform default shape.
• --profile <value>: a value starting with ’.’ or ’/’ or ending in .json is read as a local AgentProfile file; anything else is resolved as a platform profile name.
• --cli-auth needs --backend claude-code or --backend codex and cannot be combined with --backend-api-key-env/--backend-api-key-stdin.
• --secret accepts bare names only; names containing ’@’ or ’:’ are refused in favor of --proxy-secret.
• Each sensitive value comes from an environment variable named by a -env flag or from stdin with a -stdin flag, never from argv; passing both forms for one value is refused.
• --tee routes through createConfidentialSandbox and requires attestation evidence unless the API returns it (requireAttestation defaults true).
• --json prints {id, name, status, resources, createdAt, expiresAt, connection, teamId, gpuLease, confidential, attestation, attestationNonce}; connection.authToken and execToken are replaced by [REDACTED].
• --team and --personal are mutually exclusive; with neither, the active team of the profile is used.

tangle sandbox get

Get sandbox details.

Prints one sandbox’s details: id, name, status, resources, created and expiry times, SSH command line, web terminal URL and runtime URL.

tangle sandbox get <id-or-name> [options]

Request: GET /v1/sandboxes/{id}

tangle sandbox get my-box

• --profile here is a boolean that prints the agent profile provenance (base and effective hash), unlike the --profile flags of other commands.
• The printed SSH line contains the placeholder TANGLE_SSH_PROXY_AUTH_TOKEN=‘<token>’; substitute your API key or use tangle ssh.
• Accepts a sandbox id or a name; an id lookup wins, a generated-looking id that is missing fails without a name search, and an ambiguous name lists every match.

tangle sandbox list

List all sandboxes.

Lists sandboxes in the active scope as a table of ID, status, created time and name.

tangle sandbox list [options]

Request: GET /v1/sandboxes

tangle sandbox list

• --status all sends no status filter; --limit defaults to 50.
• Scope: --team, --personal and --all-scopes are mutually exclusive; with none, the profile’s active team is used.
• --json prints the SDK sandbox array.

tangle sandbox shapes

List the named sandbox sizes, the default, and this account’s ceiling.

Lists the named sandbox sizes, marks the default and whether each fits this account’s ceiling.

tangle sandbox shapes

Request: GET /v1/shapes

tangle sandbox shapes

• The default row reads ‘clamped to ceiling’ when it exceeds the ceiling; naming those numbers explicitly is refused.

tangle sandbox attestation

Fetch TEE attestation evidence for a sandbox.

Fetches TEE attestation evidence for a confidential sandbox, optionally bound to a nonce.

tangle sandbox attestation <id-or-name> [options]

Request: GET /v1/sandboxes/{id}/tee/attestation

tangle sandbox attestation my-box

• With --nonce (or --nonce auto) the request is POST /v1/sandboxes/{id}/tee/attestation with attestation_nonce in the body (sandbox contract snapshot).
• Accepts a sandbox id or a name; an id lookup wins, a generated-looking id that is missing fails without a name search, and an ambiguous name lists every match.

Stop, resume and delete

tangle sandbox stop

Stop a running sandbox.

Stops a running sandbox and waits for the stop to finish.

tangle sandbox stop <id-or-name> [options]

Request: POST /v1/sandboxes/{id}/stop

tangle sandbox stop my-box

• --no-wait sends POST /v1/sandboxes/{id}/stop?wait=false and prints the accepted operation id and its status URL.
• No CLI command polls that operation; poll the printed status URL or use the SDK.

tangle sandbox resume

Resume a stopped sandbox.

Resumes a stopped sandbox and waits for it to run.

tangle sandbox resume <id-or-name> [options]

Request: POST /v1/sandboxes/{id}/resume

tangle sandbox resume my-box

• --timeout (ms, default 120000) bounds both the resume request and the wait, because a cold resume re-provisions the sandbox.

tangle sandbox delete

Delete a sandbox.

Deletes a sandbox after a y/N confirmation and reports whether it was deleted or already gone.

tangle sandbox delete <id-or-name> [options]

Request: DELETE /v1/sandboxes/{id}

tangle sandbox delete my-box

• Prompts ‘Delete sandbox <id>? [y/N]’ unless --force, even with --json; with no stdin answer it fails with ‘Pass --force to skip the confirmation’.
• --name treats the reference as a name only; --retry-cleanup retries server cleanup for an id that no longer appears in get/list.
• Prints no JSON document; the success line goes to stderr under --json.

Ports and network

tangle sandbox expose

Expose a port and get a public URL.

Exposes a sandbox port and prints its public URL.

tangle sandbox expose <id-or-name> [options]

Request: POST /v1/sandboxes/{id}/runtime/network/expose

tangle sandbox expose my-box --port 3000

• --port defaults to 8000 and must be 1-65535.
• --json prints {port, url}.

tangle sandbox urls

List exposed port URLs for a sandbox.

Lists exposed ports and their public URLs.

tangle sandbox urls <id-or-name>

Request: GET /v1/sandboxes/{id}/runtime/network/urls

tangle sandbox urls my-box

• --json prints an object keyed by port.

tangle sandbox network

Show runtime network state (exposed ports) for a sandbox. Outbound policy is the sandbox’s egress policy.

Shows the sandbox’s exposed ports.

tangle sandbox network <id-or-name>

Request: GET /v1/sandboxes/{id}/runtime/network

tangle sandbox network my-box

• Read-only, although its spinner says ‘Updating network configuration…’.

Choose the active sandbox

tangle use

Set or show the active sandbox (used when a command omits the id).

Sets, shows or clears the active sandbox id in ~/.tangle/config.json.

tangle use [id] [options]

• Only tangle agent prompt with a single argument reads the active sandbox; every other command still requires the sandbox positional.
• The id is stored as typed; it is not validated against the API.
• TANGLE_SANDBOX overrides the stored value for one invocation.

Run commands and open a shell

tangle exec

Execute a command in a sandbox.

Runs a command in a sandbox and waits for it, writing remote stdout and stderr to the matching local streams and exiting with the remote exit code.

tangle exec <id-or-name> <command...> [options]

Request: POST /v1/sandboxes/{id}/runtime/process/spawn

tangle exec my-box -- npm test

• The CLI then reads the result from GET {runtimeUrl}/process/{pid}.
• One argument is sent as a shell script; several arguments are each shell-quoted and joined.
• --json prints {exitCode, stdout, stderr} and still exits with the remote exit code.
• --timeout defaults to 60000 ms.
• If the connection drops before a status arrives, it reports that the remote status is unknown and suggests tangle process spawn for long work.
• Resumes a stopped sandbox first and waits up to 120000 ms for it to run.
• Accepts a sandbox id or a name; an id lookup wins, a generated-looking id that is missing fails without a name search, and an ambiguous name lists every match.

tangle ssh

Open SSH session to a sandbox.

Opens an interactive OpenSSH session to a sandbox through the sandbox API’s WebSocket SSH proxy.

tangle ssh <ref> [sshArgs...] [options]

Request: GET /v1/sandboxes/{id}/runtime/ssh

tangle ssh my-box

• Spawns the local ssh binary with ProxyCommand tangle ssh-proxy <base-url>/v1/sandboxes/<id>/runtime/ssh and passes the API key in TANGLE_SSH_PROXY_AUTH_TOKEN, never in argv.
• SSH must be enabled at create (--ssh, --ssh-key, --ssh-keys or --ssh-key-file); otherwise it prints ‘SSH is not enabled for this sandbox.’ and exits 1.
• Host keys are not checked (StrictHostKeyChecking=no, known_hosts /dev/null); keepalive is 15 s.
• Exits with ssh’s exit code; ‘SSH client not found. Please install OpenSSH.’ when ssh is missing.
• --print prints the full ssh command with a <token> placeholder instead of connecting.
• Resumes a stopped sandbox first and waits up to 120000 ms for it to run.

tangle ssh-proxy

SSH proxy helper that pipes stdin/stdout to WebSocket.

Bridges stdin/stdout to a sandbox SSH WebSocket; used as an ssh ProxyCommand.

tangle ssh-proxy <runtime-url>

Request: GET /v1/sandboxes/{id}/runtime/ssh

• Requires TANGLE_SSH_PROXY_AUTH_TOKEN; exits 1 with ‘TANGLE_SSH_PROXY_AUTH_TOKEN not set’ otherwise.
• Raw binary frames, no framing; exits 0 on a normal close and 1 otherwise.

tangle ssh-keys list

List SSH keys.

Lists stored SSH keys.

tangle ssh-keys list

Request: GET /v1/ssh-keys

• --json prints {sshKeys:[...]}.

tangle ssh-keys add

Add SSH key.

Stores an SSH public key read from --key-file under a name.

tangle ssh-keys add <name> [options]

Request: POST /v1/ssh-keys

• --key-file is required.
• --json prints {sshKey:{...}} including the fingerprint.

tangle ssh-keys delete

Delete SSH key.

Deletes a stored SSH key by name or id.

tangle ssh-keys delete <name>

Request: DELETE /v1/ssh-keys/{id}

• Prints no JSON document.

Snapshots and branches

tangle snapshot create

Create a snapshot of a sandbox.

Snapshots a sandbox and prints the snapshot id and size.

tangle snapshot create <sandbox-id-or-name> [options]

Request: POST /v1/sandboxes/{id}/snapshots

tangle snapshot create my-box --tags green-tests

• --no-wait prints the accepted operation id and status URL instead of waiting.

tangle snapshot list

List snapshots for a sandbox.

Lists a sandbox’s snapshots with id, created time, size and source sandbox.

tangle snapshot list <sandbox-id-or-name>

Request: GET /v1/sandboxes/{id}/snapshots

tangle snapshot list my-box

tangle snapshot restore

Create a new sandbox from a snapshot.

Creates a NEW sandbox from a snapshot and waits up to 120000 ms for it to run; the source sandbox is untouched.

tangle snapshot restore <sandbox-id> <snapshot-id> [options]

Request: POST /v1/sandboxes

tangle snapshot restore <sandbox-id> <snapshot-id>

• The first argument must be a sandbox id; names are not resolved here.
• --json prints {sandboxId, restoredFrom, status}.
• To roll an existing sandbox back in place, use tangle snapshot revert.

tangle snapshot revert

Revert an existing sandbox to a snapshot.

tangle snapshot revert <sandbox-id-or-name> <snapshot-id>

Request: POST /v1/sandboxes/{id}/snapshots/{snapshotId}/restore

tangle snapshot revert my-box <snap-id>

• --json prints {sandboxId, snapshotId, status}.

tangle snapshot delete

Delete a sandbox snapshot.

Deletes a snapshot and reports whether it was deleted or already gone.

tangle snapshot delete <sandbox-id-or-name> <snapshot-id>

Request: DELETE /v1/sandboxes/{id}/snapshots/{snapshotId}

tangle snapshot delete <sandbox-id> <snapshot-id>

• --json prints {success, sandboxId, snapshotId, outcome}; sandboxId is the reference as typed.

tangle branch create

Branch a running sandbox into N copy-on-write children.

Branches a running sandbox into N copy-on-write children; the parent keeps running.

tangle branch create <sandbox-id-or-name> [options]

Request: POST /v1/sandboxes/{id}/branch

• A partial fan-out is reported as ‘Branched X of N’; --idempotency-key replays an earlier fan-out instead of creating a second one.
• --json prints {children:[{sandboxId}], requestedCount, materializedCount, complete, idempotency?}.

Usage

tangle usage

Show account usage and billing information.

Shows account usage (active and total sandboxes, compute minutes, GPU seconds and spend) and the subscription.

tangle usage

Request: GET /usage

tangle usage

• Also calls GET /subscription; --json prints the usage object with a nested subscription field (null when unavailable).

GPUs

tangle sandbox gpu attaches a GPU to a sandbox while a command runs, with a spend cap and a lifetime. GPU leases documents its subcommands and flags: providers, attach, run, list, exec and detach.

Next

• File, git, process and preview commands
• Sandbox lifecycle
• Snapshots