TypeScript SDK

@tangle-network/sandbox creates and drives sandboxes from your server, a Cloudflare Worker or, with a scoped token, a browser. This page covers install, the client, entrypoints, errors, retries and timeouts; the reference pages list every member.

Install

npm install @tangle-network/sandbox

The package is ESM. Optional integrations, such as the agent framework tool packs, use optional peer dependencies: install only the framework you use.

Create a client

import { Sandbox } from "@tangle-network/sandbox";
 
const client = new Sandbox({
  apiKey: process.env.TANGLE_API_KEY!,
  baseUrl: "https://sandbox.tangle.tools",
});
 
const box = await client.create();
try {
  const { stdout } = await box.exec("echo hello from $(hostname)");
  console.log(stdout);
} finally {
  await box.delete();
}

apiKey and baseUrl are both required, and the SDK reads no environment variables: a missing apiKey or baseUrl throws when you construct the client. TANGLE_API_KEY in these docs is only a naming convention.

client.withApiKey(otherKey) returns a client with the same settings and another key.

Choose an entrypoint

@tangle-network/sandbox/agent works by side effect: box.agents exists only after you import it.

import "@tangle-network/sandbox/agent";

Handle errors

Every SDK failure is a SandboxError. Branch on error.code, the server’s code, or error.catalogCode, the platform’s error class. The subclasses such as NotFoundError and StateError are deprecated aliases.

import { SandboxError } from "@tangle-network/sandbox";
 
try {
  await box.exec("make test");
} catch (error) {
  if (!(error instanceof SandboxError)) throw error;
  if (error.catalogCode === "INVALID_STATE") {
    await box.resume();
  } else if (error.retryable) {
    await new Promise((r) => setTimeout(r, error.retryAfterMs ?? 1_000));
  } else {
    console.error(error.code, error.nextStep, error.requestId);
    throw error;
  }
}

Every code and its fix is on Error codes.

A few calls report failure in their result rather than by throwing:

• exec returns a non-zero exitCode.
• prompt returns success: false with error and errorCode, and status: "unknown" when the stream was lost. Check result.success.

Retries and idempotency

The SDK resends a request only when sending it twice is safe: GET, PUT, DELETE and any request with an Idempotency-Key, after a dropped connection, a 502 to 504, or a 429 with Retry-After. It never resends a code the platform marks non-retryable. create() adds its own retry for capacity refusals inside its time budget.

Pass idempotencyKey to create, snapshot, stop, delete, fork and process jobs when your own code may retry. For coding agent turns, a stable sessionId keeps context and a turnId makes the turn safe to retry; see Streaming.

Timeouts

SDK_TIMEOUTS exports the default timeout of each operation. Pass timeoutMs to a call to change it. The values are on Limits.

import { SDK_TIMEOUTS } from "@tangle-network/sandbox";
 
const box = await client.create({}, { timeoutMs: SDK_TIMEOUTS.create * 2 });

Things that catch people out

• A browser or Worker client built from a scoped token uses scoped.sidecarProxyUrl as its baseUrl, and a browser SessionGatewayClient uses it as its url.
• box.search() and box.fs.search() yield matches; read them with for await.
• A command on a stopped sandbox throws INVALID_STATE. Call box.resume() first.
• box.direct() sends runtime calls straight to the sandbox and skips the API’s credential refresh and secret checks. Never use it for prompts.

Python and REST

The Python SDK covers the core lifecycle, commands, files, git, snapshots, egress, prompts, batches, fleets and intelligence reports. Every TypeScript method maps to a REST route, listed on its reference page. From Python, call a route the SDK does not wrap through client.fetch(method, path, json=, params=, headers=, timeout=), which returns the raw response and does not raise on an error status.

Reference

• Client: construction, account reads, create and every option, get, list, deleteMatching.
• Sandbox instance: state, lifecycle, snapshots, branches, egress, GPU and access.
• Runtime: commands, processes, files, git, ports, previews, terminals and the browser clients.
• Agents: prompts, streams, sessions, interactive control and box.agents.
• Resources: secrets, SSH keys, teams, templates, images, instances, fleets, batches, runs and lines.

Next

• Quickstart
• Python SDK
• tangle CLI