How sandboxes work

A sandbox is an isolated Linux workspace with its own filesystem, processes, network policy, size and lifetime. This page explains the states a sandbox moves through, what it keeps when it stops, and the terms the rest of these docs use.

Containers and microVMs

Every sandbox runs on one of two runtimes. Choose with runtime on create, or leave it out for the platform default.

Run tangle environments list to see each image’s runtimes.

No create option picks a region. compliance: { hipaa: true } narrows placement to capacity that can take HIPAA workloads; see Isolation and compliance.

Sandbox sizes

A sandbox gets a CPU, memory and disk size from a named preset or from numbers you pass in resources. Read the presets, the default and the largest size your account can get:

const { presets, default: defaultPreset, ceiling } = await client.shapes();
console.log(defaultPreset, ceiling);

shapes = client.fetch("GET", "/v1/shapes").json()
print(shapes["default"], shapes["ceiling"])

tangle sandbox shapes

A create that names no size gets the default preset, clamped to your ceiling. A create that names numbers above your ceiling is refused with RESOURCES_EXCEED_LIMIT. A create that sends no resources gets a smaller disk than the default preset names, so set resources.diskGB when you need more. See Limits and timeouts.

Sandbox states

box.status is one of these values.

In TypeScript, client.create() returns once the sandbox is running. In Python, create() returns earlier, so call wait_for(SandboxStatus.RUNNING) before running anything.

Timers stop a sandbox; only delete removes it

Leave a timer out and the platform’s policy applies. The CLI sets its own defaults: --lifetime 3600 and --idle-timeout 900, in seconds.

A stopped sandbox does not bill compute. A sandbox you forget to delete stays on your account until deleteAfterStoppedSeconds runs out, so delete sandboxes in a finally block. See Create, stop and delete and Pricing and spend.

What survives a stop

A long stop can release the sandbox’s compute. Resume then starts it again from its saved workspace under the same id, which takes longer.

The coding agent inside a sandbox

By default (agent: true) a sandbox has a coding agent installed: OpenCode, or Claude Code, Codex or another one you pick with backend.type. You talk to it with box.prompt() and sessions.

agent: false gives plain compute. Files, commands and lifecycle work, but the sandbox gets no model credentials, no coding agent and no startup scripts; a create that names a startup script with agent: false is refused with a 400.

List the coding agents your account can use with client.listBackends() or GET /v1/backends; see Run a coding agent.

Network access

With no policy, a sandbox can reach package registries, git hosts, container registries, CDNs and Tangle’s own services, and nothing else. An explicit strict policy reaches only the domains you list, unless you also set includeImplicitDomains: true. See Network access.

Personal and team sandboxes

A sandbox belongs to you or to a team. Pass teamId on create (--team in the CLI) to create it in a team, where the team’s members can see it. client.list({ scope }) takes personal, team, team:<id> or all. See Teams.

The security boundary

A sandbox is one trust domain. Coding agents and processes in the same sandbox can read each other’s files. Use separate sandboxes for separate customers or for code that must not see each other’s data. See Isolation and compliance.

Terms used in these docs

Next steps

• Create, stop and delete: every create option and lifecycle call.
• Run commands and code: exec, processes and code kernels.
• Run a coding agent: pick the agent, model and credential.