Sandboxes#

A sandbox is a persistent cloud computer for one agent: a full Firecracker microVM with its own kernel, disk, IP address and network namespace. It keeps its state between sessions and costs nothing for compute while paused.

TaskCloud is in private beta. Latency numbers on this page are targets, not guarantees.

What is inside#

Isolation: each sandbox runs in its own Firecracker jailer, cgroup and network namespace. Sandboxes cannot see each other or the host API. See Security.

Sizes#

Billing is per second while the VM runs. Paused sandboxes cost $0 for compute. Set disk_gb (20–1000) for more disk; disk above the included amount is billed per GB-month. Details: Billing.

The desktop (desktop template) needs size default or larger.

Create a sandbox#

A sandbox starts from exactly one source:

• a template (template, default base), see Templates;
• a snapshot (snapshot_id), which restores RAM and disk, see Snapshots and fork;
• an OCI image (image.ref).

With wait: true (the default) the call returns 201 once the sandbox is running (target p95 < 500 ms from a template). With wait: false it returns 202 in state creating.

import { Client } from "@taskcloud/sdk";

const client = new Client(); // reads TASKCLOUD_API_KEY

const sandbox = await client.sandboxes.create({
  template: "base",
  size: "default",
  name: "user-42",
  labels: { customer: "acme", user: "42" },
  env: { NODE_ENV: "development" },
  auto_pause: { enabled: true, idle_timeout_seconds: 300 },
});
console.log(sandbox.id, sandbox.state); // sbx_2fqxnt4bkq7m running

from taskcloud import Client

client = Client()  # reads TASKCLOUD_API_KEY

sandbox = client.sandboxes.create(
    template="base",
    size="default",
    name="user-42",
    labels={"customer": "acme", "user": "42"},
    env={"NODE_ENV": "development"},
    auto_pause={"enabled": True, "idle_timeout_seconds": 300},
)
print(sandbox.id, sandbox.state)

curl -sS -X POST https://api.task.cloud/v1/sandboxes \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-user-42" \
  -d '{"template":"base","size":"default","name":"user-42","labels":{"customer":"acme"}}'

taskcloud create --template base --size default --name user-42 --label customer=acme

Create options#

Send an Idempotency-Key header to make retries safe: replaying the same key with the same body returns the original sandbox.

Inspect, list, update, delete#

const sbx = await client.sandboxes.get("sbx_2fqxnt4bkq7m"); // does not wake a paused sandbox

for await (const s of client.sandboxes.list({ state: ["running", "paused"], label: ["customer=acme"] })) {
  console.log(s.id, s.state, s.last_activity_at);
}

await sbx.update({ name: "user-42-main", labels: { customer: "acme", tier: "pro" } });
await sbx.delete();

sbx = client.sandboxes.get("sbx_2fqxnt4bkq7m")
for s in client.sandboxes.list(state=["running", "paused"], label=["customer=acme"]):
    print(s.id, s.state)
sbx.update(name="user-42-main")
sbx.delete()

• GET /sandboxes is paginated (limit, cursor) and filters by state, label, name_prefix and template_id.
• PATCH /sandboxes/{sandbox_id} changes name, labels, auto_pause, always_on, ttl_seconds and metadata.
• DELETE /sandboxes/{sandbox_id} returns 202. The sandbox moves to deleting, then deleted. Its disk and automatic pause snapshot are removed. Named snapshots are kept.

The sandbox object#

Key fields of Sandbox (full schema in the API reference):

One sandbox per end user#

The most common pattern for agent platforms: give each of your users their own sandbox, label it with your user ID, and let auto-pause stop billing while the user is away. Create a restricted API key per user with restrict.labels so that a leaked key only reaches that user's sandboxes. See Security.

Related#

• Lifecycle: states, auto-pause, wake on request, billing per state
• Snapshots and fork
• Exec and files
• Networking
• Limits