SandboxSDK & APICustomer workspaces

Sandboxes for your customers

Use a named instance when each customer needs a persistent workspace. client.instances.ensure() creates or resumes the sandbox for your customer key.

Run a customer turn

Set TANGLE_CUSTOMER_ID from your application’s authenticated customer record. Set TANGLE_TURN_ID to the saved ID for this message and reuse it when retrying that message.

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 customerId = process.env.TANGLE_CUSTOMER_ID;
const turnId = process.env.TANGLE_TURN_ID;
if (!customerId || !turnId) throw new Error("Set TANGLE_CUSTOMER_ID and TANGLE_TURN_ID");
const instance = await client.instances.ensure({
  key: `customer:${customerId}`,
  profile: { version: "v1", backend: { type: "opencode" } },
  create: {
    idleTimeoutSeconds: 300,
    deleteAfterStoppedSeconds: 30 * 86400,
  },
});
const result = await instance.turn("List the workspace files without changing them.", {
  thread: "main",
  turnId,
});
console.log(instance.sandboxId, result);

The example sets a five-minute idle timeout and 30-day workspace retention after stopping. Changing profile.version starts new conversations on that profile without replacing the workspace. The same thread and version select the same conversation.

Lifecycle

OperationEffect
client.instances.get(key)Read the recorded sandbox binding.
client.instances.ensure(options)Return a running sandbox for the key.
instance.turn(message, options)Send a turn to a versioned conversation.
client.instances.release(key)Remove the binding; leave the sandbox intact.
instance.box.stop()Stop compute while retaining the workspace.
instance.box.delete()Delete the sandbox when the customer no longer needs it.

ensure() can replace a deleted sandbox or one that repeatedly fails to start. Authentication, billing, and capacity refusals do not authorize replacement. Use adopt to associate an existing sandbox with an unbound key.

For groups of workers serving one job, use Fleets.

Interactive agentsParallel tasks & batches