Sandbox lifecycle

Create a sandbox for a job, reuse it while work continues, and delete it when you finish.

Create a sandbox

Create with the default image and set the resources and runtime limit your job needs.

TypeScript

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

const apiKey = process.env.TANGLE_API_KEY;
if (!apiKey) throw new Error("Set TANGLE_API_KEY");

const client = new Sandbox({
  apiKey,
  baseUrl: "https://sandbox.tangle.tools",
});

const box = await client.create({
  maxLifetimeSeconds: 900,
  name: "my-project",
  backend: { type: "opencode" },
  env: { NODE_ENV: "development" },
  resources: { cpuCores: 2, memoryMB: 4096, diskGB: 20 },
  idleTimeoutSeconds: 300,
});
await box.waitFor("running");

console.log(box.id);

await box.delete();

Omit environment to use the server’s default image. Set it when you need a container image such as python:3.12-slim or an SDK-built image. For named environments, use the IDs from client.environments.list(). Language names such as python or node do not select versioned container images. backend.type selects the initial agent harness.

Find an existing sandbox

Set TANGLE_SANDBOX_ID to a sandbox you own. This example lists running sandboxes and reconnects to that sandbox without creating another one.

TypeScript

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

const apiKey = process.env.TANGLE_API_KEY;
if (!apiKey) throw new Error("Set TANGLE_API_KEY");

const client = new Sandbox({
  apiKey,
  baseUrl: "https://sandbox.tangle.tools",
});

const sandboxId = process.env.TANGLE_SANDBOX_ID;
if (!sandboxId) throw new Error("Set TANGLE_SANDBOX_ID");

const running = await client.list({ status: "running", limit: 10 });
const box = await client.get(sandboxId);
if (!box) throw new Error("Sandbox not found");
const usage = await client.usage();
console.log(running, box.id, usage);

Stop, resume, and delete

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

const apiKey = process.env.TANGLE_API_KEY;
if (!apiKey) throw new Error('Set TANGLE_API_KEY');

const tangle = new Sandbox({
  apiKey,
  baseUrl: 'https://sandbox.tangle.tools',
});
const box = await tangle.create({
  maxLifetimeSeconds: 900,
});
await box.waitFor('running');

await box.write('/workspace/notes.txt', 'Continue from here.');
await box.stop();
await box.waitFor('stopped');

await box.resume();
await box.waitFor('running');
console.log(await box.read('/workspace/notes.txt'));

await box.delete();

stop() keeps the workspace for later use. resume() starts it again; wait for running before sending work. delete() releases the sandbox.

maxLifetimeSeconds limits each running interval on deployments that support suspension. It suspends the sandbox rather than deleting its workspace. Delete unneeded sandboxes explicitly, including sandboxes left behind by a failed script.

HTTP endpoints

Python and other HTTP clients use the same API key. See the Python quickstart for complete request setup and startup polling.

Method	Endpoint	Action
`POST`	`/v1/sandboxes`	Create a sandbox.
`GET`	`/v1/sandboxes`	List sandboxes.
`GET`	`/v1/sandboxes/{id}`	Read its current state.
`POST`	`/v1/sandboxes/{id}/stop`	Stop the sandbox.
`POST`	`/v1/sandboxes/{id}/resume`	Resume it.
`DELETE`	`/v1/sandboxes/{id}`	Delete it.

Python Commands & files