Tangle Sandbox
Tangle Sandbox gives your application and your coding agents isolated Linux sandboxes. Create one in a call, run commands and coding agents in it, keep or fork its disk, and delete it when the work is done.
What you can do in a sandbox
| Task | Where to read |
|---|---|
| Run shell commands, long-running processes and Python, Node, TypeScript or Bash code | Run commands and code |
| Run a coding agent such as Claude Code, Codex or OpenCode on a task | Run a coding agent |
| Drive a coding agent’s own terminal UI inside the sandbox, from your terminal or a browser | Interactive mode |
| Read, write, upload and download files | Files |
| Clone repositories, commit and push | Git |
| Share a web server running in the sandbox through a public preview link | Ports and preview links |
| Snapshot a sandbox, restore it, or fork a running sandbox into copies | Snapshots and forks |
| Limit which hosts the sandbox can reach | Network access |
| Give a coding agent a desktop it can see and control (computer use) | MCP clients |
| Open a shell over SSH or a terminal in your own app | Shells and terminals |
| Run the same work across many sandboxes | Fleets |
| Attach a GPU for a fixed time and spend cap | GPU leases |
The coding agents a deployment offers come from the API, not from this page. List them with client.listBackends() in TypeScript, or GET /v1/backends from Python, the CLI or any HTTP client:
const { backends } = await client.listBackends();
for (const backend of backends) console.log(backend.type, backend.name);Each entry says whether the agent runs only on your own credential (callerCredentialOnly) and what it supports, such as streaming, MCP and sessions.
Four ways to use it
| Way in | Install | Reference |
|---|---|---|
| TypeScript SDK | npm install @tangle-network/sandbox | TypeScript SDK |
| Python SDK | pip install tangle-sandbox (PyPI) | Python SDK |
CLI, the tangle command | npm install -g @tangle-network/sandbox-cli | CLI |
REST API at https://sandbox.tangle.tools | Any HTTP client | REST API |
All four call the same API with the same account key, so a sandbox created from one can be used from the others. The dashboard at sandbox.tangle.tools/dashboard shows the same sandboxes; see Dashboard.
Never run bare npx tangle: that npm name belongs to an unrelated package. Use npx @tangle-network/sandbox-cli.
The Python SDK covers creating, running and deleting sandboxes, files, git, prompts, snapshots, egress rules, fleets and batches. Interactive terminals, preview links, sessions and GPU leases are TypeScript, CLI or REST only; each guide names the path to use.
The parts of a sandbox
Each term has a full explanation in How sandboxes work.
- Sandbox: an isolated Linux workspace with its own filesystem, network policy, size and lifetime.
- Coding agent: the agent installed in a sandbox, such as Claude Code, Codex or OpenCode. Pick it with
backend.type. - AgentProfile: the agent’s model, instructions, tools, MCP servers and permissions. See AgentProfiles.
- Session: one conversation with a coding agent. Reuse its id to continue it. See Sessions.
- Template and snapshot: a saved starting state and a saved copy of a sandbox’s files. See Snapshots and forks.
- Scoped token: a short-lived token that lets a browser reach one sandbox without your account key. See API keys and tokens.
- Fleet: several sandboxes under one budget and lifecycle. See Fleets.
Choose a starting point
| You want | Start with |
|---|---|
| One command or an exact process | box.exec() |
| A coding agent on your own Claude, ChatGPT or coding plan | backend.model.cliAuth; see Run a coding agent |
| One continuing agent conversation | box.prompt() with a sessionId, or box.session(id) |
| Several agents sharing one sandbox | box.agents |
| Separate machines or hard resource limits | A fleet |
| A lead agent that hands work to workers in their own sandboxes | Agent graphs |
| A browser view of a sandbox or session | A short-lived scoped token |
box.agents exists only after you import @tangle-network/sandbox/agent, which adds it to every sandbox handle:
import { Sandbox } from "@tangle-network/sandbox/agent";Next steps
- Quickstart: create a sandbox, run a command and prompt a coding agent.
- How sandboxes work: states, lifetimes and what survives a stop.
- API keys and tokens: keys, CLI login and browser tokens.
Changes to the SDKs, CLI and API are listed in the Sandbox release notes.