Tangle Sandbox

Hand this to your agent

Your coding agent sets up Sandbox end to end: it asks you to approve once, gets its own capped key, installs the SDK, and runs a first command in a sandbox.

Raw prompt: https://sandbox.tangle.tools/agent-setup.md

Quickstart

Create a managed Sandbox, run exact code, then add a durable Agent session.

1. Create an account API key

Sign in to the dashboard and create a key at id.tangle.tools/keys.

Bash
export TANGLE_API_KEY="sk-tan-..."
export SANDBOX_BASE_URL="https://sandbox.tangle.tools"

TANGLE_API_KEY is an account credential. Keep it in a trusted backend, CI secret store, or CLI configuration. Never expose it to browser code. Browser applications use short-lived scoped tokens described in Authentication and browser access.

2. Create and use a Sandbox from TypeScript

TypeScript
import { Sandbox } from "@tangle-network/sandbox";

const client = new Sandbox({
  apiKey: process.env.TANGLE_API_KEY!,
  baseUrl: process.env.SANDBOX_BASE_URL!,
});

const box = await client.create({
  agent: false,
  maxLifetimeSeconds: 3600,
});

try {
  await box.waitFor("running");

  const result = await box.exec("node -e 'console.log(1 + 1)'");
  if (result.exitCode !== 0) throw new Error(result.stderr);
  console.log(result.stdout); // 2
} finally {
  await box.delete();
}

Omitting environment uses the server's default image.

agent: false means “managed runtime, no default Agent.” Files, processes, terminals, telemetry, and later Agent sessions remain available. bare: true is different: it removes the managed runtime.

3. Run a durable Agent conversation

Create the Sandbox with a backend, or add a session later. Reuse the session ID to continue the same conversation:

TypeScript
const agentBox = await client.create({
  backend: {
    type: "opencode",
    profile: {
      name: "builder",
      prompt: { appendSystemPrompt: "Run tests before finishing." },
    },
  },
});

try {
  const sessionId = "repo-review-v1";

  const first = await agentBox.prompt("Inspect the repository.", {
    sessionId,
  });
  const second = await agentBox
    .session(sessionId)
    .prompt("Fix the highest-severity issue and run its tests.");

  console.log(first.response);
  console.log(second.response);
} finally {
  await agentBox.delete();
}

To run the agent on your own Claude subscription, ChatGPT plan, or coding plan instead of the Tangle Router, see Start a cloud agent.

For several AgentProfiles sharing one computer, use box.agents. For separate machines or hard resource isolation, use a Fleet.

4. Use the CLI

Bash
curl -fsSL https://sandbox.tangle.tools/install.sh | sh
tangle auth login --api-key "$TANGLE_API_KEY"
tangle sandbox create --name hello --ssh
tangle sandbox list

5. Use Python

Install HTTPX with pip install httpx.

Python
import os
import httpx

with httpx.Client(
    base_url="https://sandbox.tangle.tools",
    headers={"Authorization": f"Bearer {os.environ['TANGLE_API_KEY']}"},
    timeout=30,
) as client:
    response = client.get("/v1/sandboxes").raise_for_status().json()
    for sandbox in response["sandboxes"]:
        print(sandbox["id"], sandbox["status"])

See Python to create a sandbox and run commands.

Lifecycle

  • stop() suspends supported Sandboxes while preserving state.
  • resume() brings a stopped Sandbox back.
  • delete() is permanent.
  • Stable Agent session IDs let another process re-fetch the Sandbox and reattach while the Sandbox still exists.

Next