# TaskCloud documentation (full text)

> All pages of https://task.cloud/docs/ concatenated in navigation order, for LLMs and agents.
> Generated by website/tools/build_docs.py from website/docs/**/*.md. Short index: https://task.cloud/docs/llms.txt


---

<!-- source: https://task.cloud/docs/index.md -->

# TaskCloud documentation

`TaskCloud` gives every AI agent its own persistent cloud computer. You pay only while it works.

> **Status:** private beta (waitlist). APIs may still change before general availability. Latency figures on these pages are **targets**, not guarantees.

## What a sandbox is

Each sandbox is a full **Firecracker microVM**, not a container:

- Its own Linux kernel, **Ubuntu 24.04**, root access, **systemd** and **Docker** inside.
- A **persistent disk** (50 GB included for the `default` size).
- Isolation per VM: Firecracker jailer, cgroups, and a separate network namespace.
- Runs in the **EU** on dedicated AMD Ryzen servers.

## What you can do with it

| Capability | Summary | Page |
| --- | --- | --- |
| Pause and resume | RAM and disk are snapshotted together. Processes, open windows and sessions survive. Resume target: p95 < 800 ms. | [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md) |
| Auto-pause and wake on request | Pauses after N minutes idle (default 5). An HTTP request, SSH connection or API call wakes it. Paused = $0 compute. | [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md) |
| Fork | Copy a running VM **including memory**. Target: < 2 s. | [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md) |
| Exec | Sync, background, SSE streaming, interactive PTY over WebSocket. 10+ concurrent commands per VM. | [Exec and files](https://task.cloud/docs/guides/exec-and-files.md) |
| Files | Read, write, list, upload, download, watch. | [Exec and files](https://task.cloud/docs/guides/exec-and-files.md) |
| Networking | Public HTTPS URL per port (`https://<short_id>-<port>.taskhost.cloud`), SSH through a gateway. | [Networking](https://task.cloud/docs/guides/networking.md) |
| Desktop | Browser desktop streaming (KasmVNC, 1920x1080), signed links with TTL and read-only mode, screenshot + input API for computer use. | [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md) |
| Templates | Start from a snapshot or your own OCI/Docker image. | [Templates](https://task.cloud/docs/concepts/templates.md) |
| Account | Scoped API keys, spend limits, signed webhooks, usage API. | [Security](https://task.cloud/docs/security.md), [Webhooks](https://task.cloud/docs/guides/webhooks.md), [Billing](https://task.cloud/docs/billing.md) |
| Tooling | TypeScript and Python SDKs (typed by hand from the OpenAPI spec), CLI, MCP server, `llms.txt`. | [SDKs](https://task.cloud/docs/sdk/typescript.md), [CLI](https://task.cloud/docs/cli.md), [MCP](https://task.cloud/docs/mcp.md) |

## Start here

1. [Quickstart](https://task.cloud/docs/quickstart.md): first sandbox and first command in TypeScript, Python, CLI or curl.
2. [Sandboxes](https://task.cloud/docs/concepts/sandboxes.md) and [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md): the mental model.
3. [API reference](https://task.cloud/docs/api-reference.md): every endpoint, plus the [OpenAPI spec](https://api.task.cloud/v1/openapi.yaml).

## All pages

**Concepts**
- [Sandboxes](https://task.cloud/docs/concepts/sandboxes.md)
- [Lifecycle and auto-pause](https://task.cloud/docs/concepts/lifecycle.md)
- [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md)
- [Templates](https://task.cloud/docs/concepts/templates.md)

**Guides**
- [Exec and files](https://task.cloud/docs/guides/exec-and-files.md)
- [Networking: ports and SSH](https://task.cloud/docs/guides/networking.md)
- [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md)
- [Webhooks](https://task.cloud/docs/guides/webhooks.md)
- [Migrate from E2B](https://task.cloud/docs/guides/migrate-from-e2b.md)
- [Migrate from boat.dev](https://task.cloud/docs/guides/migrate-from-boat.md)

**Reference**
- [API reference](https://task.cloud/docs/api-reference.md)
- [TypeScript SDK](https://task.cloud/docs/sdk/typescript.md)
- [Python SDK](https://task.cloud/docs/sdk/python.md)
- [CLI](https://task.cloud/docs/cli.md)
- [MCP server](https://task.cloud/docs/mcp.md)
- [Billing and pricing](https://task.cloud/docs/billing.md)
- [Limits](https://task.cloud/docs/limits.md)
- [Security](https://task.cloud/docs/security.md)
- [llms.txt](https://task.cloud/docs/llms.txt) (index for LLM agents)

## Not in the MVP

These are on the roadmap and are **not** available today: WebRTC desktop streaming at 60 fps, an AI-key proxy, a `full` VM class with nested KVM, GPUs, an open-source core with self-hosting, regions outside the EU, SSO and audit logs. We do not hold a SOC 2 report.


---

<!-- source: https://task.cloud/docs/quickstart.md -->

# Quickstart

Create a sandbox, run a command, expose a port, and pause it. Takes about five minutes.

> **Private beta.** You need a beta account. [Join the waitlist](https://task.cloud/#waitlist). The Free plan includes 20 one-time hours of the `default` size, no card required.

## 1. Get an API key

Create a key in the dashboard (**Settings → API keys**) or with the CLI after `taskcloud login`:

```bash
taskcloud key create --name quickstart --preset full-sandbox
```

Keys look like `taskcloud_sk_...` and are shown once. Export it:

```bash
export TASKCLOUD_API_KEY="taskcloud_sk_..."
```

The SDKs and the CLI read `TASKCLOUD_API_KEY` automatically.

## 2. Install

```bash
npm install @taskcloud/sdk        # TypeScript / JavaScript (Node.js 20+; PTY needs Node.js 22+ or the `ws` package)
pip install taskcloud             # Python 3.9+
```

The CLI is built from source during the beta (`go build` in `cli/`, Go 1.27.3+); see [CLI](https://task.cloud/docs/cli.md). The install script (`curl -fsSL https://task.cloud/install.sh | sh`) and prebuilt binaries work once the first CLI release is tagged.

## 3. Create a sandbox and run a command

### TypeScript

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

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

const sandbox = await client.sandboxes.create({
  template: "base",
  size: "default",
  name: "quickstart",
  auto_pause: { enabled: true, idle_timeout_seconds: 300 },
});
console.log(sandbox.id, sandbox.state); // sbx_... running

const result = await sandbox.exec({ command: "uname -a && python3 --version" });
console.log(result.exit_code, result.stdout);
```

### Python

```python
from taskcloud import Client

client = Client()  # reads TASKCLOUD_API_KEY

sandbox = client.sandboxes.create(
    template="base",
    size="default",
    name="quickstart",
    auto_pause={"enabled": True, "idle_timeout_seconds": 300},
)
print(sandbox.id, sandbox.state)

result = sandbox.exec(command="uname -a && python3 --version")
print(result.exit_code, result.stdout)
```

### CLI

```bash
id=$(taskcloud create --template base --size default --name quickstart --json | jq -r .id)
taskcloud exec "$id" -- uname -a
```

### curl

```bash
API=https://api.task.cloud/v1

id=$(curl -sS -X POST "$API/sandboxes" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"base","size":"default","name":"quickstart"}' | jq -r .id)

curl -sS -X POST "$API/sandboxes/$id/exec" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"uname -a && python3 --version"}'
# {"command_id":"cmd_...","exit_code":0,"stdout":"Linux ...","stderr":"","duration_ms":41}
```

`POST /sandboxes` waits until the sandbox is `running` (target p95 < 500 ms from a template) and returns `201`. Pass `"wait": false` to get `202` immediately.

## 4. Start a server and open it in the browser

```ts
await sandbox.files.write("/home/user/www/index.html", "<h1>Hello from TaskCloud</h1>");
await sandbox.exec({ command: "python3 -m http.server 8080", cwd: "/home/user/www", background: true });
const port = await sandbox.ports.expose({ port: 8080, visibility: "public" });
console.log(port.url); // https://<short_id>-8080.taskhost.cloud
```

```python
sandbox.files.write("/home/user/www/index.html", "<h1>Hello from TaskCloud</h1>")
sandbox.exec(command="python3 -m http.server 8080", cwd="/home/user/www", background=True)
port = sandbox.ports.expose(port=8080, visibility="public")
print(port.url)
```

```bash
taskcloud exec "$id" --background --cwd /home/user/www -- python3 -m http.server 8080
taskcloud port expose "$id" 8080 --public
```

## 5. Pause, then wake it with a request

```ts
await sandbox.pause();            // RAM + disk snapshot; compute billing stops
// ...later: any request wakes it. Opening port.url, an SSH login or an API call all work:
const again = await sandbox.exec({ command: "echo still here" }); // resumes transparently
```

```bash
curl -sS -X POST "$API/sandboxes/$id/pause" -H "Authorization: Bearer $TASKCLOUD_API_KEY"
short=${id#sbx_}                                # hostnames use the ID without sbx_
curl -sS "https://$short-8080.taskhost.cloud/"   # wakes the sandbox, then serves the page
```

You do not have to pause manually: with the default `auto_pause`, a sandbox with no activity for 5 minutes pauses itself. See [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md).

## 6. Clean up

```ts
await sandbox.delete();
```

```bash
taskcloud delete "$id" --yes
```

## Next steps

- [Exec and files](https://task.cloud/docs/guides/exec-and-files.md): streaming, background jobs, PTY, uploads, file watching.
- [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md): clone a running VM with its memory.
- [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md): give an agent a screen.
- [Webhooks](https://task.cloud/docs/guides/webhooks.md): get notified when sandboxes pause, resume or fail.
- [Billing](https://task.cloud/docs/billing.md): what you pay for, per state.


---

<!-- source: https://task.cloud/docs/templates.md -->

# Template gallery

Official templates give your agent a working environment in one call: the runtime, libraries and tools are already installed, and the sandbox starts from a RAM snapshot of the booted system (target p95 < 500 ms), not from a cold boot.

```python
sandbox = client.sandboxes.create(template="python")
print(sandbox.exec(command="python -c 'import pandas; print(pandas.__version__)'").stdout)
```

Every official template is built from a declarative recipe with pinned versions and digests, ships with an SBOM, stays within a size budget, and passes an in-sandbox smoke test (`taskcloud-smoke`) before release.

> **Private beta.** The gallery is rolling out region by region. `GET /templates?owner=builtin` lists the templates available to your account; `base` and `desktop` are available everywhere.

## Gallery

| Template | What's inside | Default size | Ports | Good for |
| --- | --- | --- | --- | --- |
| `base` | Ubuntu 24.04, systemd, Docker, Python 3.12, git, build-essential | `default` | – | anything; the default |
| `python` | Python 3.12 (default venv) and 3.13 via uv; NumPy, pandas, Polars, SciPy, scikit-learn, DuckDB, PyArrow, Matplotlib | `default` | – | data analysis, code interpreters, ML without GPU |
| `node` | Node.js 22 LTS, npm, pnpm, Bun, TypeScript | `default` | – | JS/TS agents, web app builders |
| `browser` | headless Chromium, Playwright for Python and Node, Noto/CJK/emoji fonts, Xvfb | `default` | – | browser automation, scraping, computer use without a desktop |
| `coding-agent` | git, gh, ripgrep, fd, build-essential, Docker in the VM, Node 22, Python 3.12; Codex CLI, Gemini CLI, OpenCode, Aider | `default` | – | coding agents, CI-like tasks, repo work |
| `jupyter` | JupyterLab (already running), Python 3.12 data stack | `default` | 8888 | notebooks, data exploration |
| `desktop` | `base` + XFCE, KasmVNC, Chromium, Firefox, xdotool | `default` | – | computer use with a visible desktop, see [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md) |

All templates run as user `user` (uid 1000) with passwordless `sudo`, have SSH, and keep the full disk persistent across pause and resume. Templates are not tied to a size: pass `size` to override the default (`desktop` needs `default` or `large`).

## Create a sandbox from a template

Use the template name, or its ID (`tpl_python`). The same call works for every template.

### TypeScript

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

const client = new Client();
const sandbox = await client.sandboxes.create({ template: "python" });
const result = await sandbox.exec({ command: "taskcloud-smoke" });
console.log(result.exit_code, result.stdout); // 0 ... TASKCLOUD_SMOKE_OK python
```

### Python

```python
from taskcloud import Client

client = Client()
sandbox = client.sandboxes.create(template="python")
result = sandbox.exec(command="taskcloud-smoke")
print(result.exit_code, result.stdout)  # 0 ... TASKCLOUD_SMOKE_OK python
```

### CLI

```bash
id=$(taskcloud create --template python --json | jq -r .id)
taskcloud exec "$id" -- taskcloud-smoke
taskcloud template ls          # the gallery and your own templates
```

### curl

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"template":"python","name":"analysis-1"}'

curl -sS "https://api.task.cloud/v1/templates?owner=builtin" -H "Authorization: Bearer $TASKCLOUD_API_KEY"
```

### MCP

The `create_sandbox` tool of the [MCP server](https://task.cloud/docs/mcp.md) describes the official templates, so an agent can pick one by itself. Tool call:

```json
{ "name": "create_sandbox", "arguments": { "template": "browser" } }
```

## Templates

### base

Ubuntu 24.04 with systemd, Docker, Python 3.12 (system `python3`), git and build-essential. This is what you get without a `template`. Built with debootstrap rather than from an OCI image.

```ts
const sandbox = await client.sandboxes.create({ template: "base" });
await sandbox.exec({ command: "docker run --rm alpine echo hello" });
```

### python

The default virtualenv `/opt/taskcloud/venv` (Python 3.12.16) is on `PATH` and owned by `user`, so `pip install` and `uv pip install` work without `sudo`. Python 3.13 is installed for `uv`: `uv run --python 3.13 ...`. Matplotlib uses the `Agg` backend (no display).

```python
sandbox = client.sandboxes.create(template="python")
sandbox.files.write("/home/user/sales.csv", "region,amount\neu,10\nus,32\n")
r = sandbox.exec(command="python -c \"import pandas as pd; print(pd.read_csv('sales.csv').amount.sum())\"")
print(r.stdout)  # 42
```

### node

Node.js 22 LTS in `/opt/taskcloud/node` (owned by `user`: `npm install -g` works without `sudo`), pnpm, Bun and TypeScript.

```ts
const sandbox = await client.sandboxes.create({ template: "node" });
await sandbox.exec({ command: "pnpm create vite@latest app -- --template react-ts && cd app && pnpm install" });
await sandbox.exec({ command: "cd app && pnpm dev --host 0.0.0.0 --port 5173", background: true });
const port = await sandbox.ports.expose({ port: 5173, visibility: "public" });
console.log(port.url);
```

### browser

Headless Chromium from Playwright, shared by the Python and Node bindings (same Playwright version, one browser build in `/ms-playwright`). Fonts cover Latin, CJK and emoji, so screenshots of real pages render correctly. For headed runs use `xvfb-run`; for a visible desktop use `desktop`.

```python
sandbox = client.sandboxes.create(template="browser")
script = """
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    page = p.chromium.launch().new_page()
    page.goto("https://example.com")
    page.screenshot(path="/home/user/shot.png")
    print(page.title())
"""
sandbox.files.write("/home/user/shot.py", script)
print(sandbox.exec(command="python shot.py").stdout)
png = sandbox.files.read("/home/user/shot.png")  # bytes
```

From Node, `require("playwright")` works out of the box (`NODE_PATH` points at the global modules). In your own project, install the same version (`npm i playwright@1.64.1`) and it reuses the installed browser.

### coding-agent

Everything a coding agent needs in a repository: git, the GitHub CLI, ripgrep, fd, build-essential, Docker (the daemon runs inside the VM; `user` is in the `docker` group), Node 22 and Python 3.12.

Agent CLIs: open-source ones are preinstalled (Codex CLI, Gemini CLI, OpenCode, Aider). Proprietary CLIs are not redistributed in the image; install them inside the sandbox from the vendor, under the vendor's terms, with `taskcloud-agents install`:

```bash
taskcloud-agents list                    # what is installed, licenses, which env var each CLI reads
taskcloud-agents install claude-code     # npm install -g @anthropic-ai/claude-code (vendor's official method)
```

No credentials are in the image. Pass API keys as sandbox env when you create the sandbox:

```ts
const sandbox = await client.sandboxes.create({
  template: "coding-agent",
  env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY!, GH_TOKEN: process.env.GH_TOKEN! },
});
await sandbox.exec({ command: "gh repo clone acme/app && cd app && codex exec 'fix the failing test'", timeout_seconds: 1800 });
```

### jupyter

JupyterLab is already running on port 8888 when the sandbox starts. Every sandbox has its own token: pass `JUPYTER_TOKEN` in `env` at create, or read the generated one with `taskcloud-jupyter-token`. A token or login cookie from another sandbox (including a fork) does not work.

```python
import secrets

token = secrets.token_urlsafe(32)
sandbox = client.sandboxes.create(
    template="jupyter",
    env={"JUPYTER_TOKEN": token},
    ports=[{"port": 8888, "visibility": "public"}],
)
print(f"{sandbox.ports.url(8888)}/lab?token={token}")
```

```ts
const sandbox = await client.sandboxes.create({ template: "jupyter", ports: [{ port: 8888, visibility: "public" }] });
const token = (await sandbox.exec({ command: "taskcloud-jupyter-token" })).stdout.trim();
console.log(`${sandbox.ports.url(8888)}/lab?token=${token}`);
```

With `visibility: "private"` (the default) the edge also requires a sandbox access token; see [Networking](https://task.cloud/docs/guides/networking.md). Health check without a token: `curl -fsS http://127.0.0.1:8888/api`.

### desktop

`base` plus an XFCE desktop streamed with KasmVNC, Chromium and Firefox. The desktop is already running. See [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md) for screenshots, input and the stream URL.

## Smoke tests

Every official template contains `taskcloud-smoke`, the same test we run before each release. It needs no network and no credentials, prints one line per check and ends with `TASKCLOUD_SMOKE_OK <template>` (exit code 0) or `TASKCLOUD_SMOKE_FAIL <template>` (exit code 1). Run it to check a sandbox after you changed it:

```bash
taskcloud exec sbx_2fqxnt4bkq7m -- taskcloud-smoke
```

| Template | What `taskcloud-smoke` checks |
| --- | --- |
| `base` | user, sudo, Python, compiler, Docker |
| `python` | Python 3.12 and 3.13, NumPy/pandas/Polars/scikit-learn/DuckDB, a Matplotlib PNG, a new venv with uv |
| `node` | Node 22, npm, pnpm, Bun running TypeScript, `tsc` |
| `browser` | a Chromium screenshot from Python and from Node, fonts, a headed run under Xvfb |
| `coding-agent` | git + ripgrep in a repo, gh, a C build, Docker, each agent CLI, no credentials in the image |
| `jupyter` | `/api` health, token required (403 without), a kernel start and stop |
| `desktop` | KasmVNC, X display, a desktop screenshot, Chromium and Firefox |

## How official templates are built

- **Recipes:** a Dockerfile per template on Ubuntu 24.04 pinned by digest (`base` and `desktop`: debootstrap), converted to a VM root filesystem by our template builder, booted, and snapshotted with RAM.
- **Pinned versions:** language runtimes and tools by exact version, downloads checked against SHA-256, Python packages from hash-locked requirement files, Ubuntu packages from a dated archive snapshot.
- **SBOM:** an SPDX and a CycloneDX SBOM per release, plus a package list at `/usr/share/doc/taskcloud-template/packages.txt` inside the sandbox.
- **Size budget:** the release fails if an image grows past its budget, so start times and storage stay predictable.
- **Metadata:** `/etc/taskcloud/template.json` in the sandbox names the template and version.

Current versions: Python 3.12.16 / 3.13.18, uv 0.13.7, Node.js 22.23.4, pnpm 12.18.0, Bun 1.4.4, TypeScript 7.0.2, Playwright 1.64.1, JupyterLab 4.6.6, gh 2.103.3, Codex CLI 0.167.0, Gemini CLI 0.67.0, OpenCode 1.19.5, Aider 0.86.2.

## Listing templates

`GET /templates` returns official templates with `official: true`, `tags`, `ports`, `docs_url` and `example_command`; your own templates have `official: false` and empty `tags` and `ports`.

```json
{
  "id": "tpl_jupyter",
  "name": "jupyter",
  "official": true,
  "builtin": true,
  "state": "ready",
  "size": "default",
  "tags": ["jupyter", "notebooks", "python", "data"],
  "ports": [{ "port": 8888, "name": "jupyterlab", "protocol": "http", "description": "JupyterLab; ..." }],
  "docs_url": "https://task.cloud/docs/templates.html#jupyter"
}
```

If your account already has a template with the same name as an official one (for example your own `python`), the name keeps resolving to yours; use the ID (`tpl_python`) for the official one.

## Customize

Start from an official template, install what you need, then save it as your own template so every new sandbox starts with it:

```ts
const sandbox = await client.sandboxes.create({ template: "python" });
await sandbox.exec({ command: "pip install transformers==4.57.0 && python -c 'import transformers'" });
const snap = await sandbox.snapshots.create({ name: "py-transformers" });
await client.templates.create({ name: "py-transformers", snapshot_id: snap.id });
```

Or build a template from your own OCI image; see [Templates](https://task.cloud/docs/concepts/templates.md).

## Related

- [Templates](https://task.cloud/docs/concepts/templates.md): versions, building your own from an image or a snapshot
- [Exec and files](https://task.cloud/docs/guides/exec-and-files.md)
- [Networking](https://task.cloud/docs/guides/networking.md): ports and access tokens
- [API reference](https://task.cloud/docs/api-reference.md)


---

<!-- source: https://task.cloud/docs/concepts/sandboxes.md -->

# 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

| Property | Value |
| --- | --- |
| OS | Ubuntu 24.04 LTS, x86_64, own Linux kernel |
| Users | `user` (home `/home/user`, passwordless `sudo`); `root` is allowed |
| Init | real systemd: services you enable come back after pause/resume and fork |
| Containers | Docker inside the VM |
| Disk | persistent, survives pause, resume and host restarts |
| GPU | none (software rendering only); GPU is on the roadmap |
| Nested virtualization (`/dev/kvm`) | not available; on the roadmap |
| Region | EU only. `auto` (default) places the sandbox on any EU host; `eu-de` and `eu-fi` pin it to a location |

Isolation: each sandbox runs in its own Firecracker jailer, cgroup and network namespace. Sandboxes cannot see each other or the host API. See [Security](https://task.cloud/docs/security.md).

## Sizes

| `size` | vCPU | RAM | Included disk | Price per active hour |
| --- | --- | --- | --- | --- |
| `small` | 2 | 4 GB | 20 GB | $0.015 |
| `default` | 4 | 8 GB | 50 GB | $0.030 |
| `large` | 8 | 16 GB | 100 GB | $0.060 |

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](https://task.cloud/docs/billing.md).

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](https://task.cloud/docs/concepts/templates.md);
- a **snapshot** (`snapshot_id`), which restores RAM and disk, see [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md);
- 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`.

```ts
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
```

```python
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)
```

```bash
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"}}'
```

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

### Create options

| Field | Default | Notes |
| --- | --- | --- |
| `template` | `base` | name, ID, or `name:version` |
| `snapshot_id` | – | start from a named snapshot |
| `image` | – | `{ "ref": "ghcr.io/acme/env:1.4", "registry_auth": {...} }` |
| `size` | `default` | `small`, `default`, `large` |
| `name` | – | up to 120 chars |
| `labels` | – | up to 32 key/value pairs; filter with `?label=key=value` |
| `env` | – | up to 100 variables, 64 KiB; write-only, never returned |
| `auto_pause` | `{enabled: true, idle_timeout_seconds: 300}` | see [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md) |
| `always_on` | `false` | never auto-pause; `default` size only, monthly price |
| `priority` | `standard` | `batch` = −50%, may wait in `queued` |
| `region` | `auto` | `eu-de`, `eu-fi` |
| `ttl_seconds` | `null` | delete automatically after N seconds |
| `disk_gb` | size's included disk | 20–1000 |
| `ports` | – | up to 20 ports to expose at creation |
| `metadata` | – | free-form JSON up to 16 KiB, returned as-is |
| `wait` | `true` | ignored for `priority: "batch"` |

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

```ts
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();
```

```python
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](https://task.cloud/docs/api-reference.md)):

| Field | Meaning |
| --- | --- |
| `id` | `sbx_...` |
| `state` | `queued`, `creating`, `running`, `pausing`, `paused`, `resuming`, `deleting`, `deleted`, `error` |
| `size`, `vcpus`, `memory_mb`, `disk_gb` | resources |
| `template_id`, `snapshot_id`, `image`, `forked_from` | where it came from |
| `auto_pause`, `always_on`, `priority`, `ttl_seconds`, `expires_at` | lifecycle settings |
| `url_template` | `https://a2b3c4d5e6f7-{port}.taskhost.cloud` |
| `ports` | exposed ports |
| `desktop` | `true` if the sandbox has a desktop |
| `error` | `{code, message}` when `state` is `error` |
| `created_at`, `started_at`, `paused_at`, `last_activity_at` | timestamps |

## 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](https://task.cloud/docs/security.md).

## Related

- [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md): states, auto-pause, wake on request, billing per state
- [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md)
- [Exec and files](https://task.cloud/docs/guides/exec-and-files.md)
- [Networking](https://task.cloud/docs/guides/networking.md)
- [Limits](https://task.cloud/docs/limits.md)


---

<!-- source: https://task.cloud/docs/concepts/lifecycle.md -->

# Lifecycle

A sandbox moves between a few well-defined states. The important ones for your bill are `running` (billed per second) and `paused` ($0 compute, full RAM and disk state kept).

## States

```
                    (priority: "batch" only)
                         ┌─────────┐
                         │ queued  │  waiting for capacity, not billed
                         └────┬────┘
                              ▼
   POST /sandboxes ──► ┌──────────┐
                       │ creating │  not billed
                       └────┬─────┘
                            ▼
                       ┌──────────┐  pause / auto-pause  ┌─────────┐       ┌────────┐
          ┌──────────► │ running  │ ───────────────────► │ pausing │ ────► │ paused │
          │            └──────────┘                      └─────────┘       └───┬────┘
          │                                                                    │ resume /
          │            ┌──────────┐                                            │ wake on request
          └─────────── │ resuming │ ◄──────────────────────────────────────────┘
                       └──────────┘

   any state ── DELETE / ttl expired ──► deleting ──► deleted
   any state ── VM failure ──────────► error   (see sandbox.error)
```

| State | Meaning |
| --- | --- |
| `queued` | `priority: "batch"` only; waiting for capacity |
| `creating` | VM is being started from a template, snapshot or image |
| `running` | VM is running; exec, files, ports, SSH and desktop work |
| `pausing` | RAM and disk are being snapshotted at the same instant |
| `paused` | VM is stopped; RAM and disk are kept in a snapshot |
| `resuming` | VM is being restored (target p95 < 800 ms) |
| `deleting`, `deleted` | sandbox and its data are being removed / gone |
| `error` | VM failed; `sandbox.error` has `code` and `message` |

Processes, open TCP connections, terminal sessions, desktop windows and browser tabs survive a pause: resume restores memory, it does not reboot.

## Pause and resume

```ts
await sandbox.pause();   // waits until "paused" (wait: true by default)
await sandbox.resume();  // waits until "running"
```

```python
sandbox.pause()
sandbox.resume()
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/pause \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"wait": false}'    # 202, state "pausing"
```

```bash
taskcloud pause sbx_2fqxnt4bkq7m
taskcloud resume sbx_2fqxnt4bkq7m
```

With `wait: true` (default) the call blocks until the transition finishes (max 60 s, then `202`). Pausing a paused sandbox or resuming a running one is a no-op that returns `200`.

## Auto-pause

Every sandbox pauses itself after `auto_pause.idle_timeout_seconds` without activity. Defaults: `enabled: true`, `idle_timeout_seconds: 300` (5 minutes). Range: 60–86400 seconds.

Activity means any of:

- a running exec command or an open PTY session;
- inbound traffic on an exposed port or over SSH;
- a connected desktop viewer, or desktop input;
- CPU usage above a low threshold.

An open file watch (`GET .../files/watch`) does **not** count as activity.

```ts
await sandbox.update({ auto_pause: { enabled: true, idle_timeout_seconds: 900 } });
```

```python
sandbox.update(auto_pause={"enabled": True, "idle_timeout_seconds": 900})
```

```bash
curl -sS -X PATCH https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"auto_pause":{"enabled":true,"idle_timeout_seconds":900}}'

taskcloud update sbx_2fqxnt4bkq7m --idle-timeout 15m
taskcloud update sbx_2fqxnt4bkq7m --no-auto-pause
```

## Wake on request

You rarely need to call `resume`. A paused sandbox wakes automatically when it receives:

- an HTTP request to one of its port URLs (`https://<short_id>-<port>.taskhost.cloud`) or its desktop URL;
- an SSH connection through `ssh.taskhost.cloud`;
- an API call that needs a running VM: exec, PTY, files, screenshot, input.

The request waits for the resume (target p95 < 800 ms) and then completes normally, without an error on the client side. `GET /sandboxes/{sandbox_id}` does not wake a sandbox.

To fail fast instead, pass `auto_resume=false` on API calls; a paused sandbox then returns `409 sandbox_paused`:

```bash
curl -sS -X POST "https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/exec?auto_resume=false" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"command":"uptime"}'
```

## Always-on

`always_on: true` disables auto-pause. Instead of hourly billing, the sandbox costs a flat $19.90 per month (prorated). Available for size `default` only.

```ts
await sandbox.update({ always_on: true });
```

```bash
taskcloud update sbx_2fqxnt4bkq7m --always-on
```

## TTL

`ttl_seconds` deletes the sandbox automatically N seconds after creation (min 60; `null` keeps it until you delete it). `expires_at` shows the deadline. Change it with `PATCH`. Expiry sends `sandbox.deleted` with `reason: "ttl_expired"`.

## Batch priority

`priority: "batch"` is billed at −50%. In exchange the sandbox may wait in `queued` until capacity is available, and the create call always returns `202` (`wait` is ignored). Use it for evals, CI and other jobs that are not interactive. Work run during the EU night window (22:00–07:00 CET) gets the same −50% automatically.

```ts
const job = await client.sandboxes.create({ template: "base", priority: "batch", wait: false });
await job.waitFor("running");
```

```python
job = client.sandboxes.create(template="base", priority="batch", wait=False)
job.wait_for("running")
```

```bash
taskcloud create --template base --batch --no-wait
```

## Billing per state

Compute is billed per second while the VM runs. Prices per active hour: `small` $0.015, `default` $0.030, `large` $0.060.

| State | Compute | Storage |
| --- | --- | --- |
| `queued`, `creating` | not billed | – |
| `running` | per second at the size rate | disk above the included amount: $0.05/GB-month |
| `pausing`, `resuming` | per second, as `running` | – |
| `paused` | **$0** | pause snapshot free for 30 days, then $0.03/GB-month; extra disk as above |
| `deleting`, `deleted` | not billed | not billed |
| `error` | not billed | disk kept until you delete the sandbox |
| `always_on: true` | flat $19.90/month (`default`) instead of per second | as above |

Batch priority and the off-peak window (22:00–07:00 CET) are billed at −50%. See [Billing](https://task.cloud/docs/billing.md) for plans and credit.

## Checkpoints and host failures

TaskCloud saves sandboxes to replicated object storage, encrypted with a key of your account:

- **Pause:** a paused sandbox's memory and disk are uploaded a few minutes after the pause. It can then resume on any host, even if its original host fails.
- **Running sandboxes:** after about 15 minutes of activity since the last resume or checkpoint, TaskCloud takes a **disk checkpoint**. The sandbox keeps running; there is no pause. The checkpoint is crash-consistent, like the disk after a power cut: files flushed to disk are in it, data still in the guest's page cache may not be.

If the host running a sandbox fails, TaskCloud restores the sandbox on another host from its newest saved state and sends [`sandbox.restored_from_checkpoint`](https://task.cloud/docs/guides/webhooks.md):

| Newest saved state | After the restore |
| --- | --- |
| pause snapshot (`kind: memory`) | memory, processes and files as of that pause |
| disk checkpoint (`kind: disk`, `ram_lost: true`) | files as of the checkpoint; the sandbox booted, so processes and `/dev/shm` restarted |

At most about 15 minutes of disk work is lost (`data_loss_window_seconds` in the webhook tells you how much). Long-running agents should keep their progress in files (and call `sync` after important steps) so they can continue from a disk checkpoint. Paused sandboxes are not affected: their pause snapshot is restored as is.

A sandbox paused less than a few minutes before its host failed may not be uploaded yet. It stays `paused` until the host returns.

## Webhooks per transition

| Event | Sent when | Typical `reason` |
| --- | --- | --- |
| `sandbox.ready` | sandbox first becomes `running` after create or fork | `api` |
| `sandbox.paused` | state becomes `paused` | `api`, `auto_pause`, `spend_limit`, `host_maintenance` |
| `sandbox.resumed` | state becomes `running` after `resuming` | `api`, `wake_on_request` |
| `sandbox.error` | state becomes `error` | an error code |
| `sandbox.deleted` | state becomes `deleted` | `api`, `ttl_expired` |
| `sandbox.restored_from_checkpoint` | sandbox runs again from an older saved state after a host failure | `host_lost`, `restore_interrupted` |

Each event carries `previous_state`, `state`, `reason` and the full sandbox. Setup and signature verification: [Webhooks](https://task.cloud/docs/guides/webhooks.md).

## Related

- [Sandboxes](https://task.cloud/docs/concepts/sandboxes.md)
- [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md)
- [Billing](https://task.cloud/docs/billing.md), [Limits](https://task.cloud/docs/limits.md)


---

<!-- source: https://task.cloud/docs/concepts/snapshots-and-fork.md -->

# Snapshots and fork

A snapshot captures a sandbox's RAM and disk at the same instant. Fork uses the same mechanism to clone a sandbox, including its memory, into a new, independent sandbox (target p95 < 2 s).

## Three kinds of saved state

| | Pause snapshot | Named snapshot | Template |
| --- | --- | --- | --- |
| Created by | `pause` / auto-pause | `POST /sandboxes/{sandbox_id}/snapshots` | `POST /templates` |
| Lifetime | until the sandbox is deleted | until you delete it (outlives the sandbox) | until you delete it |
| Contains | RAM + disk | RAM + disk (or disk only with `memory: false`) | RAM + disk |
| Use | resume the same sandbox | `POST /sandboxes` with `snapshot_id`; base for a template | `POST /sandboxes` with `template` |
| ID | internal | `snap_...` | `tpl_...` / name |

Storage for snapshots is free for 30 days (`free_storage_until`), then $0.03/GB-month on the stored size after compression and deduplication (`storage_bytes`).

## Create a named snapshot

A running sandbox is paused briefly (typically a few hundred milliseconds) and continues afterwards. A paused sandbox is snapshotted from its pause state.

```ts
const snap = await sandbox.snapshots.create({ name: "after-npm-install", labels: { repo: "web" } });
console.log(snap.id, snap.state); // snap_3kd7wq2mzn5x ready
```

```python
snap = sandbox.snapshots.create(name="after-npm-install", labels={"repo": "web"})
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/snapshots \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"after-npm-install"}'

taskcloud snapshot create sbx_2fqxnt4bkq7m --name after-npm-install
```

Set `memory: false` for a smaller, disk-only snapshot. Sandboxes started from it boot instead of resuming memory.

Start a new sandbox from the snapshot:

```ts
const copy = await client.sandboxes.create({ snapshot_id: snap.id });
```

```bash
taskcloud create --snapshot snap_3kd7wq2mzn5x
```

List and delete: `GET /snapshots` (filter `sandbox_id`), `GET /snapshots/{snapshot_id}`, `DELETE /snapshots/{snapshot_id}`. Deleting a snapshot used by a template returns `409 snapshot_in_use`.

Named snapshots are copied to replicated object storage (encrypted with your account's key) right after they are created. A sandbox created from a snapshot can start on any host, also when the host that took the snapshot is down. The first sandbox from a snapshot on a new host waits for the download; later ones start from the local copy.

A sandbox created from a snapshot is a copy of the original machine: limits that apply to the original sandbox (for example a network restriction) apply to the copy too, as with fork.

## Fork

`POST /sandboxes/{sandbox_id}/fork` creates a new sandbox from the current state of the source, memory included.

- A running source is paused for a few hundred milliseconds while RAM and disk are captured, then continues.
- A paused source is forked from its pause snapshot and stays paused.
- The fork has its own IP, network namespace and copy-on-write disk. Changes in the fork never affect the source.
- The fork has the same size as the source. You can set `name`, `labels`, `env`, `auto_pause`, `priority`, `ttl_seconds`, `metadata`.
- `forked_from` on the new sandbox records `sandbox_id` and `snapshot_id`.

```ts
const fork = await sandbox.fork({ name: "attempt-1", labels: { run: "eval-17" } });
const r = await fork.exec({ command: "pytest -x" });
```

```python
fork = sandbox.fork(name="attempt-1", labels={"run": "eval-17"})
r = fork.exec(command="pytest -x")
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/fork \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: eval-17-attempt-1" \
  -d '{"name":"attempt-1","labels":{"run":"eval-17"}}'

taskcloud fork sbx_2fqxnt4bkq7m --name attempt-1
```

### Parallel attempts from one state

Prepare a sandbox once (clone the repo, install dependencies, start services), then fork it for each attempt:

```ts
const base = await client.sandboxes.create({ template: "base" });
await base.exec({ command: "git clone https://github.com/acme/app && cd app && npm ci", timeout_seconds: 600 });
await base.pause();

const attempts = await Promise.all(
  [1, 2, 3, 4].map((i) => base.fork({ name: `attempt-${i}`, ttl_seconds: 3600 })),
);
// Or in one call, with a single capture of the source (see Bulk fork below):
// const attempts = await base.fork({ count: 4, ttl_seconds: 3600 });
```

Fork counts against your concurrency limit and the `starts` rate limit like any create.

### Bulk fork

For RL rollouts and evals, `count` creates up to **50 forks in one call** from a single capture of the source (higher limits on request). The source pauses once, not once per fork.

- **All or nothing.** If your concurrency limit or the capacity next to the source cannot take every fork, nothing is created: the call fails with `409 concurrency_limit_reached` or `503 capacity_unavailable` (retryable; consider `priority: "batch"`).
- **Response.** With `count` omitted or `1` you get one `Sandbox`, as before. With `count > 1` you get `{"data": [Sandbox, ...]}` with exactly `count` items: `201` when every fork is running, `202` with `wait: false` or `priority: "batch"`.
- **Batch priority.** With `priority: "batch"` the forks are created in `queued` from one snapshot, billed at the batch rate and started as capacity frees up.
- `name`, `labels`, `env`, `metadata`, `auto_pause`, `priority` and `ttl_seconds` apply to every fork. Each fork counts toward the concurrency limit; the call counts as one request in the `starts` rate limit.

```ts
const forks = await base.fork({ count: 20, labels: { run: "eval-17" }, ttl_seconds: 3600 }); // Sandbox[]
const results = await Promise.all(forks.map((f) => f.exec({ command: "pytest -x" })));
```

```python
forks = base.fork(count=20, labels={"run": "eval-17"}, ttl_seconds=3600)  # list[Sandbox]
results = [f.exec(command="pytest -x") for f in forks]
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/fork \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: eval-17-rollouts" \
  -d '{"count":20,"labels":{"run":"eval-17"},"ttl_seconds":3600}'

taskcloud fork sbx_2fqxnt4bkq7m --count 20
```

## What a snapshot does not cover

- Secrets you passed in `env` are part of the VM's memory and environment. A fork or a sandbox created from a snapshot inherits them; override with `env` on fork, or avoid baking secrets into templates.
- The external IP address may change after resume or fork.
- Active TCP connections to the outside world may be dropped by the remote side during a long pause.

## Related

- [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md)
- [Templates](https://task.cloud/docs/concepts/templates.md)
- [Billing](https://task.cloud/docs/billing.md)


---

<!-- source: https://task.cloud/docs/concepts/templates.md -->

# Templates

A template is a reusable starting point for new sandboxes. Every template is stored as a RAM snapshot of a booted VM, so a sandbox created from it starts from a ready system instead of booting (target p95 < 500 ms).

## Official templates

| Template | Contents |
| --- | --- |
| `base` | Ubuntu 24.04, systemd, Docker, Python 3.12, common build tools; user `user` with passwordless sudo |
| `python`, `node`, `browser`, `coding-agent`, `jupyter` | language runtimes, a headless browser, coding-agent tools or JupyterLab, ready in one call; see the [Template gallery](https://task.cloud/docs/templates.md) |
| `desktop` | `base` + XFCE, KasmVNC, Chromium, Firefox, xdotool and fonts; desktop is already running. Needs size `default` or larger |

`template` defaults to `base` when you create a sandbox without a source.

## Your own templates

Create a template from **either** an OCI/Docker image **or** a snapshot.

### From an OCI image

We pull the image (linux/amd64), turn it into a VM root filesystem and add our guest agent. If the image has systemd, the agent and `start_command` run as systemd services; if it doesn't, a small init (`taskcloud-init`) starts the agent and your `start_command` (or the image's ENTRYPOINT/CMD). We then boot it, wait for `ready_check` to exit 0, and take a RAM snapshot. The call returns `202` with state `building`.

```ts
const tpl = await client.templates.create({
  name: "agent-env",
  image: { ref: "ghcr.io/acme/agent-env:1.4", registry_auth: { username: "acme-bot", password: process.env.GHCR_TOKEN! } },
  start_command: "/usr/local/bin/warmup.sh",
  ready_check: { command: "curl -sf localhost:8080/health", timeout_seconds: 120 },
  size: "default",
});
```

```python
tpl = client.templates.create(
    name="agent-env",
    image={"ref": "ghcr.io/acme/agent-env:1.4",
           "registry_auth": {"username": "acme-bot", "password": os.environ["GHCR_TOKEN"]}},
    start_command="/usr/local/bin/warmup.sh",
    ready_check={"command": "curl -sf localhost:8080/health", "timeout_seconds": 120},
    size="default",
)
```

```bash
curl -sS -X POST https://api.task.cloud/v1/templates \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"agent-env","image":{"ref":"ghcr.io/acme/agent-env:1.4"},"size":"default"}'

taskcloud template create --name agent-env --image ghcr.io/acme/agent-env:1.4
taskcloud template logs agent-env --follow
```

Follow the build with `GET /templates/{template_id}/logs` (plain text, or SSE with `Accept: text/event-stream`). The template becomes `ready` or `failed` (see `error`).

Image build options:

| Field | Notes |
| --- | --- |
| `image.ref` | OCI reference, linux/amd64 |
| `image.registry_auth` | `username`, `password` (write-only) for private registries |
| `start_command` | started before the snapshot |
| `ready_check` | `command` that must exit 0; `timeout_seconds` default 300, max 1800 |
| `env` | baked into the template |
| `desktop` | `true` adds the XFCE + KasmVNC desktop stack (coming soon for custom images; use the `desktop` base template today) |
| `size` | size used for the build snapshot |

### From a snapshot

Set up a sandbox by hand or with exec, take a named snapshot, then turn it into a template. It is `ready` immediately (`201`) and keeps that exact RAM and disk state.

```ts
const snap = await sandbox.snapshots.create({ name: "python-preinstalled" });
await client.templates.create({ name: "python-preinstalled", snapshot_id: snap.id });
```

```bash
taskcloud template create --name python-preinstalled --snapshot snap_3kd7wq2mzn5x
```

## Versions

Creating a template with an existing `name` adds a new `version`. `template: "agent-env"` uses the latest `ready` version; pin one with `template: "agent-env:3"`. Deleting a template does not affect sandboxes already created from it.

```ts
const sbx = await client.sandboxes.create({ template: "agent-env:3" });
```

## Templates vs. images vs. snapshots

- Use an **image** directly (`POST /sandboxes` with `image`) for one-offs. Each create converts and boots the image, so it is slower than a template.
- Use a **template** for anything you start often.
- Use a **snapshot** to continue from one specific sandbox's state. See [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md).

Template storage is billed like snapshot storage. See [Billing](https://task.cloud/docs/billing.md).

## Related

- [Sandboxes](https://task.cloud/docs/concepts/sandboxes.md)
- [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md)
- [API reference](https://task.cloud/docs/api-reference.md)


---

<!-- source: https://task.cloud/docs/guides/exec-and-files.md -->

# Exec and files

Run commands in a sandbox (sync, in the background, as an SSE stream, or in an interactive PTY) and move files in and out. All calls wake a paused sandbox automatically unless you pass `auto_resume=false`.

## Run a command (sync)

`POST /sandboxes/{sandbox_id}/exec` waits for the command to exit and returns `ExecResult`.

```ts
const r = await sandbox.exec({ command: "npm test", cwd: "/home/user/app", timeout_seconds: 300 });
console.log(r.exit_code, r.stdout, r.stderr, r.duration_ms);
```

```python
r = sandbox.exec(command="npm test", cwd="/home/user/app", timeout_seconds=300)
print(r.exit_code, r.stdout)
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/exec \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"command":"npm test","cwd":"/home/user/app","timeout_seconds":300}'
# {"command_id":"cmd_9fz2cq4kd7mw","exit_code":0,"stdout":"...","stderr":"","truncated":false,"duration_ms":8123}

taskcloud exec sbx_2fqxnt4bkq7m --cwd /home/user/app --timeout 300 -- npm test
```

Request fields:

| Field | Default | Notes |
| --- | --- | --- |
| `command` | – | run with `/bin/bash -lc` |
| `args` | – | program + arguments, executed without a shell (use instead of `command`) |
| `cwd` | `/home/user` | |
| `env` | – | extra variables for this command |
| `user` | `user` | `user` has passwordless sudo; `root` is allowed |
| `stdin` | – | written to stdin, then closed (sync and stream) |
| `timeout_seconds` | 60 | max 600; sync and stream only |
| `background` | `false` | return immediately, no time limit |
| `stream` | `false` | respond with SSE (same as `Accept: text/event-stream`) |

- A non-zero exit code is a normal `200` response, not an error.
- If the command exceeds `timeout_seconds`, it is killed and the API returns `408 exec_timeout` with partial output in `details`.
- Captured output is limited to 8 MiB per stream; `truncated: true` tells you it was cut. Use stream mode for large output.
- Non-UTF-8 output is returned base64-encoded with `encoding: "base64"`.
- At least 10 commands can run concurrently in one sandbox.

## Background commands

For dev servers, long builds and agents: `background: true` returns `202` with a `Command` right away. There is no time limit.

```ts
const server = await sandbox.exec({ command: "npm run dev -- --port 3000", cwd: "/home/user/app", background: true });
console.log(server.id); // cmd_...

// later
for await (const ev of server.stream()) {
  if (ev.type === "stdout") process.stdout.write(ev.data);
  if (ev.type === "exit") console.log("exited", ev.exit_code);
}
await server.kill({ signal: "SIGTERM" });
```

```python
server = sandbox.exec(command="npm run dev -- --port 3000", cwd="/home/user/app", background=True)
for ev in server.stream():
    if ev.type == "stdout":
        print(ev.data, end="")
server.kill(signal="SIGTERM")
```

```bash
taskcloud exec sbx_2fqxnt4bkq7m --background -- npm run dev -- --port 3000
taskcloud commands list sbx_2fqxnt4bkq7m
taskcloud commands logs sbx_2fqxnt4bkq7m cmd_9fz2cq4kd7mw --follow
taskcloud commands kill sbx_2fqxnt4bkq7m cmd_9fz2cq4kd7mw
```

Endpoints:

| Endpoint | Purpose |
| --- | --- |
| `GET /sandboxes/{sandbox_id}/commands` | recent commands (last 7 days), filter `state` |
| `GET /sandboxes/{sandbox_id}/commands/{command_id}` | state: `running`, `exited`, `killed`, `timed_out`, `lost` |
| `GET .../commands/{command_id}/stream` | SSE; replays earlier output (up to 8 MiB per stream); resume with `Last-Event-ID` |
| `POST .../commands/{command_id}/stdin` | `{data, encoding, eof}` |
| `POST .../commands/{command_id}/kill` | `{signal}`; default `SIGTERM` |

A running command counts as activity, so the sandbox will not auto-pause while it runs. For a service that should survive pause/resume and forks, a systemd unit is more robust than a background command.

## Streaming output (SSE)

Stream mode returns Server-Sent Events: `start`, `stdout`, `stderr`, `exit`, `error`. There is no output limit.

```ts
for await (const ev of sandbox.execStream({ command: "pip install -r requirements.txt" })) {
  if (ev.type === "stdout" || ev.type === "stderr") process.stdout.write(ev.data);
  if (ev.type === "exit") console.log("exit", ev.exit_code);
}
```

```python
for ev in sandbox.exec_stream(command="pip install -r requirements.txt"):
    if ev.type in ("stdout", "stderr"):
        print(ev.data, end="")
```

```bash
curl -sS -N -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/exec \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"command":"pip install -r requirements.txt"}'
```

```
event: start
data: {"type":"start","command_id":"cmd_9fz2cq4kd7mw","pid":4211}

event: stdout
data: {"type":"stdout","command_id":"cmd_9fz2cq4kd7mw","data":"Collecting requests\n"}

event: exit
data: {"type":"exit","command_id":"cmd_9fz2cq4kd7mw","exit_code":0,"duration_ms":8123}
```

## Interactive terminal (PTY over WebSocket)

`POST /sandboxes/{sandbox_id}/pty` starts a pseudo-terminal and returns `websocket_url`, a signed URL valid for 60 s until first connect. It needs no `Authorization` header, so you can hand it to a browser terminal such as xterm.js.

Protocol:

- **Binary frames:** raw keystrokes (client → server) and raw terminal output (server → client).
- **Text frames (JSON):** client sends `{"type":"resize","cols":120,"rows":40}`, `{"type":"signal","signal":"SIGINT"}`, `{"type":"ping"}`; server sends `{"type":"ready","pty_id":"..."}`, `{"type":"exit","exit_code":0}`, `{"type":"pong"}`, `{"type":"error","error":{...}}`.
- After a drop, call `GET .../pty/{pty_id}` within 60 s for a fresh URL; up to 64 KiB of missed output is replayed.
- The session ends when the process exits or after `idle_timeout_seconds` (default 1800) without traffic. An open PTY prevents auto-pause.

```ts
const term = await sandbox.pty.connect({
  cols: 120,
  rows: 40,
  onData: (bytes) => process.stdout.write(bytes),
});
term.write("htop\r");
term.resize(160, 48);
term.close();
```

```bash
# Raw API
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/pty \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"cols":120,"rows":40}'
# {"id":"pty_7hc2zq5mxk3d","state":"waiting","websocket_url":"wss://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/pty/pty_7hc2zq5mxk3d/connect?token=pt_...","expires_at":"..."}

# Or simply
taskcloud shell sbx_2fqxnt4bkq7m
```

## Files

Paths are absolute, or relative to `/home/user`.

### Read and write

```ts
await sandbox.files.write("/home/user/app/.env", "PORT=3000\n", { mode: "0600" });
const text = await sandbox.files.readText("/home/user/app/package.json");
const bytes = await sandbox.files.read("/home/user/app/logo.png"); // Uint8Array
```

```python
sandbox.files.write("/home/user/app/.env", "PORT=3000\n", mode="0600")
text = sandbox.files.read_text("/home/user/app/package.json")
data = sandbox.files.read("/home/user/app/logo.png")  # bytes
```

```bash
# write (raw body)
curl -sS -X PUT "https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/files/content?path=/home/user/app/.env&mode=0600" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/octet-stream" \
  --data-binary @.env

# read (raw bytes; supports Range)
curl -sS "https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/files/content?path=/home/user/app/package.json" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY"
```

- `PUT .../files/content` creates parent directories by default (`create_parents=true`), accepts `mode` and `owner`, and supports `If-Match` with the file's `ETag` (`412 precondition_failed` on mismatch).
- `GET .../files/content` streams the file and supports `Range`.
- Up to 1 GiB per request; larger files return `413 payload_too_large`. Use signed URLs for those.

### List, stat, mkdir, move, delete

```ts
const entries = await sandbox.files.list("/home/user/app", { recursive: true });
const info = await sandbox.files.stat("/home/user/app/package.json");
await sandbox.files.mkdir("/home/user/data");
await sandbox.files.move("/home/user/a.txt", "/home/user/data/a.txt");
await sandbox.files.remove("/home/user/tmp", { recursive: true });
```

| Endpoint | Notes |
| --- | --- |
| `GET /sandboxes/{sandbox_id}/files?path=` | `recursive`, `max_depth` (default 8), paginated |
| `GET .../files/stat?path=` | `FileEntry`: `name`, `path`, `type`, `size`, `mode`, `owner`, `modified_at`, `etag` |
| `POST .../files/mkdir` | `{path, parents, mode}` |
| `POST .../files/move` | `{from, to, overwrite}` |
| `DELETE /sandboxes/{sandbox_id}/files?path=` | `recursive=true` for non-empty directories |

### Upload and download many files

```ts
await sandbox.files.upload("/home/user/app", {
  "src/index.ts": "console.log('hi')\n",   // relative name -> string, Uint8Array or Blob
  "package.json": pkgJson,
});
const archive = await sandbox.files.downloadArchive("/home/user/app/dist", { format: "tar.gz" });
```

```python
sandbox.files.upload("/home/user/app", [("src/index.ts", b"print('hi')\n")])
archive = sandbox.files.download_archive("/home/user/app/dist", format="tar.gz")
```

```bash
# multipart upload; filenames may include sub-directories
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/files/upload \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -F path=/home/user/app -F extract=true -F files=@repo.tar.gz

# directory as an archive (tar.gz, tar or zip)
curl -sS -o dist.tar.gz "https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/files/download?path=/home/user/app/dist&format=tar.gz" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY"

taskcloud cp -r ./app sbx_2fqxnt4bkq7m:/home/user/app
taskcloud cp sbx_2fqxnt4bkq7m:/home/user/app/report.pdf ./report.pdf
```

### Signed URLs (large files, browsers)

Pre-signed URLs work without an API key, for a single `PUT` (upload) or `GET` (download) of up to 10 GiB. Default lifetime 900 s, max 3600 s.

```ts
const up = await sandbox.files.uploadUrl({ path: "/home/user/data/dataset.parquet", expires_in_seconds: 900 });
// up.method === "PUT"; give up.url to your user's browser or a worker
const down = await sandbox.files.downloadUrl({ path: "/home/user/app/out.zip" });
```

```python
up = sandbox.files.upload_url(path="/home/user/data/dataset.parquet")
down = sandbox.files.download_url(path="/home/user/app/out.zip")
```

### Watch for changes

`GET .../files/watch?path=` streams `FileEvent`s (`created`, `modified`, `deleted`, `renamed`) as SSE. Options: `recursive` (default `true`), `include_hidden` (default `false`). A watch does not keep the sandbox awake; it stays open across pause/resume and delivers events again after the VM wakes.

```ts
for await (const ev of sandbox.files.watch("/home/user/app/src", { recursive: true })) {
  console.log(ev.type, ev.path);
}
```

```python
for ev in sandbox.files.watch("/home/user/app/src", recursive=True):
    print(ev.type, ev.path)
```

```bash
taskcloud files watch sbx_2fqxnt4bkq7m /home/user/app/src
```

## Errors you will see

| Status | `code` | Retry? | Meaning |
| --- | --- | --- | --- |
| 404 | `not_found` | no | sandbox, command or path does not exist |
| 408 | `exec_timeout` | no | sync command killed after `timeout_seconds` |
| 409 | `sandbox_paused` | no | only with `auto_resume=false` |
| 409 | `sandbox_busy` | yes | transient; retry after `Retry-After` |
| 413 | `payload_too_large` | no | use signed URLs |
| 502 | `sandbox_unreachable` | per `retryable` | guest did not answer; the command may have run |

Always branch on `error.code` and `error.retryable`:

```ts
import { ApiError } from "@taskcloud/sdk";
try {
  await sandbox.exec({ command: "make build", timeout_seconds: 600 });
} catch (e) {
  if (e instanceof ApiError && e.retryable) { /* back off and retry */ }
  else throw e;
}
```

## Related

- [Networking](https://task.cloud/docs/guides/networking.md): expose the dev server you just started
- [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md)
- [Limits](https://task.cloud/docs/limits.md)
- [API reference](https://task.cloud/docs/api-reference.md)


---

<!-- source: https://task.cloud/docs/guides/networking.md -->

# Networking

Every port in a sandbox can get a public HTTPS URL, and every sandbox is reachable over SSH through our gateway. Both wake a paused sandbox on the first request.

## Public URLs for ports

`POST /sandboxes/{sandbox_id}/ports` publishes a port at:

```
https://<short_id>-<port>.taskhost.cloud
```

`<short_id>` is the sandbox ID without the `sbx_` prefix (`sbx_a2b3c4d5e6f7` → `a2b3c4d5e6f7`): an underscore is not valid in hostnames. Use `port.url` or the sandbox's `url_template` instead of building URLs by hand.

HTTP/1.1, HTTP/2 and WebSocket are supported. TLS terminates at our edge; your server listens on plain HTTP inside the VM (bind to `0.0.0.0` or `127.0.0.1`).

Sandbox URLs live on `taskhost.cloud`, a registrable domain separate from `task.cloud` (website, API and docs). Code running in a sandbox is therefore never same-site with the API and cannot set cookies for `task.cloud`. `taskhost.cloud` is submitted to the [Public Suffix List](https://publicsuffix.org/) so that browsers also treat each sandbox hostname as a separate site from other sandboxes.

```ts
await sandbox.exec({ command: "npm run dev -- --port 3000", cwd: "/home/user/app", background: true });
const port = await sandbox.ports.expose({ port: 3000, visibility: "public" });
console.log(port.url); // https://a2b3c4d5e6f7-3000.taskhost.cloud
```

```python
sandbox.exec(command="npm run dev -- --port 3000", cwd="/home/user/app", background=True)
port = sandbox.ports.expose(port=3000, visibility="public")
print(port.url)
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/ports \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"port":3000,"visibility":"public"}'

taskcloud port expose sbx_2fqxnt4bkq7m 3000 --public
```

You can also expose ports at creation time with `ports: [{"port": 3000, "visibility": "public"}]` (up to 20). List with `GET .../ports`, remove with `DELETE .../ports/{port}`. Exposing an already exposed port updates its settings. Target: the URL responds within 1 s of your server starting.

### Visibility

| `visibility` | Who can open the URL |
| --- | --- |
| `private` (default) | requests with an access token (header `X-Sandbox-Token` or query `sandbox_token`), or an API key with `sandboxes:read` |
| `public` | anyone with the URL |

For a private preview in your end user's browser, mint a short-lived **access token** instead of exposing an API key. It grants HTTP access to this sandbox's private ports only.

```ts
const { token, expires_at } = await sandbox.accessTokens.create({ ttl_seconds: 3600, ports: [3000] });
const previewUrl = `${sandbox.ports.url(3000)}/?sandbox_token=${token}`;
```

```python
t = sandbox.access_tokens.create(ttl_seconds=3600, ports=[3000])
preview_url = f"{sandbox.ports.url(3000)}/?sandbox_token={t.token}"
```

`ttl_seconds` ranges from 60 to 86400 (default 3600). The token is shown once.

### Wake on request

A request to the URL of a paused sandbox resumes it (target p95 < 800 ms) and is then served normally. Inbound traffic on exposed ports counts as activity, so an app with visitors stays awake, and it auto-pauses once traffic stops. See [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md).

### Not yet supported

- Raw TCP/UDP ports (`protocol` other than `http`): **Coming soon**. Use SSH port forwarding meanwhile.
- Custom domains: not available.

## SSH

`POST /sandboxes/{sandbox_id}/ssh` returns connection details for the gateway `ssh.taskhost.cloud:22`. The gateway username is the sandbox ID.

Three ways to authenticate:

1. **Account SSH keys** (`POST /ssh-keys`): work for every sandbox in the account.
2. **A key for this sandbox only:** pass `public_key` in the request; valid for `ttl_seconds` (default 3600, max 604800).
3. **One-time password:** returned in `password` when you pass no key and the account has none.

```ts
const access = await sandbox.ssh({ public_key: "ssh-ed25519 AAAA... me@laptop", ttl_seconds: 3600 });
console.log(access.command); // ssh sbx_2fqxnt4bkq7m@ssh.taskhost.cloud
```

```python
access = sandbox.ssh(public_key=open(os.path.expanduser("~/.ssh/id_ed25519.pub")).read(), ttl_seconds=3600)
print(access.command)
```

```bash
curl -sS -X POST https://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/ssh \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d "{\"public_key\":\"$(cat ~/.ssh/id_ed25519.pub)\"}"
# {"host":"ssh.taskhost.cloud","port":22,"username":"sbx_2fqxnt4bkq7m","password":null,"expires_at":"...","command":"ssh sbx_2fqxnt4bkq7m@ssh.taskhost.cloud","host_key_fingerprint":"SHA256:..."}

taskcloud ssh sbx_2fqxnt4bkq7m          # sends ~/.ssh/id_ed25519.pub as a temporary key and connects
```

The response also contains `host_key_fingerprint`; verify it on first connect. Log in as another Linux user with `user` (default `user`).

SSH supports everything OpenSSH does through the gateway:

```bash
ssh sbx_2fqxnt4bkq7m@ssh.taskhost.cloud 'uname -a'               # one command
ssh -L 5432:localhost:5432 sbx_2fqxnt4bkq7m@ssh.taskhost.cloud     # local forward
ssh -R 8080:localhost:8080 sbx_2fqxnt4bkq7m@ssh.taskhost.cloud     # reverse forward
scp ./data.csv sbx_2fqxnt4bkq7m@ssh.taskhost.cloud:/home/user/
```

VS Code and Cursor Remote-SSH work with a host entry:

```
Host sbx_2fqxnt4bkq7m
  HostName ssh.taskhost.cloud
  User sbx_2fqxnt4bkq7m
  IdentityFile ~/.ssh/id_ed25519
```

Connecting to a paused sandbox wakes it. An open SSH session counts as activity.

## Outbound traffic

Outbound internet access from the sandbox is open by default. An **egress allowlist** (restricting outbound traffic to listed domains) is **Coming soon**. Abuse such as mining, spam or scanning leads to suspension; see [Security](https://task.cloud/docs/security.md).

Inbound traffic reaches the VM only through exposed ports and the SSH gateway. Each sandbox has its own network namespace and cannot reach other sandboxes.

## Required scopes

| Operation | Scope |
| --- | --- |
| list ports | `sandboxes:read` |
| expose / remove ports, access tokens | `sandboxes:write` |
| SSH access, SSH keys | `ssh` |

## Related

- [Exec and files](https://task.cloud/docs/guides/exec-and-files.md)
- [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md): the desktop has its own URL, `https://<short_id>-desktop.taskhost.cloud`
- [Security](https://task.cloud/docs/security.md)
- [Limits](https://task.cloud/docs/limits.md)


---

<!-- source: https://task.cloud/docs/guides/desktop-and-computer-use.md -->

# Desktop and computer use

A `TaskCloud` sandbox can run a full Linux desktop. People can watch and control it in the browser, and AI agents can drive it through a screenshot and input API.

The desktop has two paths:

- **People** open a signed stream URL (KasmVNC) in a browser, or in an `<iframe>` inside your product.
- **Agents** take screenshots (`GET /sandboxes/{sandbox_id}/screenshot`) and send mouse and keyboard actions (`POST /sandboxes/{sandbox_id}/input`). Agents don't need the video stream, and screenshots cost much less.

> Private beta. Latency numbers on this page are targets, not guarantees.

## The `desktop` template

| Property | Value |
| --- | --- |
| OS | Ubuntu 24.04 + XFCE |
| Browsers | Chromium, Firefox |
| Streaming | KasmVNC over HTTPS/WebSocket (no UDP, no TURN) |
| Resolution | 1920x1080 |
| Minimum size | `default` (4 vCPU / 8 GB). Image encoding runs on the sandbox's own vCPUs. |
| GPU | None. Rendering is done in software. |

The template is a RAM snapshot of a desktop that is already running, so a new sandbox starts with the screen ready.

**No GPU.** WebGL, 3D maps and video playback run slowly. Office apps, web apps and ordinary browsing work well.

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

const client = new Client(); // reads TASKCLOUD_API_KEY
const sandbox = await client.sandboxes.create({ template: "desktop", size: "default" });
```

```python
from taskcloud import Client

client = Client()
sandbox = client.sandboxes.create(template="desktop", size="default")
```

```bash
taskcloud create --template desktop
```

To add the desktop stack to your own image, set `desktop: true` when you create a template from an image. See [Templates](https://task.cloud/docs/concepts/templates.md).

## Watching in a browser: stream URLs

`POST /sandboxes/{sandbox_id}/desktop` returns a signed URL of the form `https://<short_id>-desktop.taskhost.cloud/?token=...`.

| Field | Default | Description |
| --- | --- | --- |
| `ttl_seconds` | `600` | URL lifetime, 60 to 86400. An open session is disconnected when the URL expires. |
| `read_only` | `false` | The viewer can watch but cannot send input. |
| `single_use` | `false` | The URL can be opened only once. |

```bash
curl -X POST https://api.task.cloud/v1/sandboxes/$SANDBOX_ID/desktop \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 900, "read_only": true}'
```

```json
{
  "id": "dsk_7zab3kq2mxw5",
  "url": "https://a2b3c4d5e6f7-desktop.taskhost.cloud/?token=dt_...",
  "read_only": true,
  "single_use": false,
  "expires_at": "2026-11-09T12:15:00Z",
  "created_at": "2026-11-09T12:00:00Z"
}
```

```ts
const stream = await sandbox.desktop.stream({ ttl_seconds: 900, read_only: true });
console.log(stream.url);

// Later, before it expires:
await sandbox.desktop.revoke(stream.id);
```

```python
stream = sandbox.desktop.stream(ttl_seconds=900, read_only=True)
sandbox.desktop.revoke(stream.id)
```

```bash
taskcloud desktop $SANDBOX_ID --ttl 15m --read-only --open
```

- **List active URLs:** `GET /sandboxes/{sandbox_id}/desktop`.
- **Revoke a URL:** `DELETE /sandboxes/{sandbox_id}/desktop/{stream_id}`. This invalidates the URL and disconnects anyone using it.
- **Embed it** in your product:

  ```html
  <iframe src="https://a2b3c4d5e6f7-desktop.taskhost.cloud/?token=dt_..."
          style="width:100%;aspect-ratio:16/9;border:0" allow="clipboard-read; clipboard-write"></iframe>
  ```

- **Wake on request:** opening the URL of a paused sandbox resumes it. The target is under 2 s from click to desktop.
- **Auto-pause:** an active viewer counts as activity, so the sandbox doesn't pause while someone is watching. A desktop with no viewers and no input pauses normally after its idle timeout. See [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md).
- **The session survives a pause.** Pausing snapshots RAM, so windows, open browser tabs and logged-in sessions are all still there after a resume. The viewer reconnects automatically.

## Screenshots

`GET /sandboxes/{sandbox_id}/screenshot`. Target p95 is under 300 ms.

| Query parameter | Default | Description |
| --- | --- | --- |
| `format` | `png` | `png` or `jpeg` |
| `quality` | `80` | JPEG quality, 1 to 100 |
| `scale` | `1` | Downscales the output image, 0.1 to 1 |
| `region` | none | Crop to `x0,y0,x1,y1` in full-screen pixels |
| `include_cursor` | `true` | Draw the cursor |

The response format depends on the `Accept` header:

- **Default:** the raw image, with `X-Screen-Width` and `X-Screen-Height` headers.
- **`Accept: application/json`:** a JSON object `{ data, media_type, width, height, screen_width, screen_height, taken_at }`, where `data` is base64.

```bash
curl -s https://api.task.cloud/v1/sandboxes/$SANDBOX_ID/screenshot \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -o shot.png
# or
taskcloud screenshot $SANDBOX_ID -o shot.png
```

```ts
const shot = await sandbox.desktop.screenshot({ format: "png" });
// shot.data is base64; shot.screen_width x shot.screen_height is the coordinate space
```

## Input

`POST /sandboxes/{sandbox_id}/input` runs a batch of actions in order. Action names and fields follow the Anthropic computer-use tool, so a model's tool call can be forwarded as `{ "action": <tool name>, ...input }`.

| `action` | Fields |
| --- | --- |
| `mouse_move` | `coordinate` |
| `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click` | optional `coordinate` (default: current cursor position); optional `text` with held modifiers (`shift`, `ctrl`, `alt`, `super`, joined with `+`) |
| `left_click_drag` | `start_coordinate`, `coordinate` |
| `left_mouse_down`, `left_mouse_up` | none |
| `scroll` | `scroll_direction` (`up`, `down`, `left`, `right`), `scroll_amount` (wheel clicks, default `3`), optional `coordinate`, optional `text` modifiers |
| `type` | `text` (Unicode, up to 65,536 characters) |
| `key` | `text`: a key or chord in xdotool syntax (`Return`, `ctrl+s`, `ctrl+shift+t`); optional `repeat` (1 to 100) |
| `hold_key` | `text`, `duration` (seconds) |
| `wait` | `duration` (seconds, up to 300) |

Coordinates are `[x, y]` in full-screen pixels, with the origin at the top left.

Request options:

- `return_screenshot: true` returns a screenshot taken after the last action. It is taken after `screenshot_delay_ms` (default 300) so the UI can settle.
- `coordinate_scale` divides incoming coordinates. Use it when they come from a screenshot taken with `scale` < 1.

If an action fails, the actions after it are not run and are reported with `status: "skipped"`. The cursor position is available at `GET /sandboxes/{sandbox_id}/cursor`.

```bash
curl -X POST https://api.task.cloud/v1/sandboxes/$SANDBOX_ID/input \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"action": "left_click", "coordinate": [640, 412]},
      {"action": "type", "text": "hello world"},
      {"action": "key", "text": "Return"}
    ],
    "return_screenshot": true
  }'
```

```json
{
  "results": [
    {"index": 0, "action": "left_click", "status": "ok", "error": null},
    {"index": 1, "action": "type", "status": "ok", "error": null},
    {"index": 2, "action": "key", "status": "ok", "error": null}
  ],
  "cursor": {"x": 640, "y": 412},
  "screenshot": {"data": "iVBORw0...", "media_type": "image/png", "width": 1920, "height": 1080, "screen_width": 1920, "screen_height": 1080}
}
```

## Example: a computer-use agent loop with Claude

These examples connect Claude's computer-use toolset (`computer_toolset_20260801`) to a sandbox. The toolset is generally available on the Claude API with no beta header. The tool entry takes no `name` and no display size.

How the toolset maps to the sandbox API:

- **Calls:** each call from Claude is a `tool_use` block with `toolset_name: "computer"`, and the block's `name` is the action (`screenshot`, `zoom`, `left_click`, `type`, `key`, ...). One turn can contain several blocks.
- **Results:** return one `tool_result` per block, all in the next `user` message, and each one must include `toolset_name: "computer"`. Return results for every block:
  - `screenshot` and `zoom` return an image.
  - `cursor_position` returns text such as `X=512, Y=384`.
  - Other actions return `OK`.
  - If an action fails, set `is_error: true` on its result, and answer every later block in that turn with `Not executed: an earlier computer action in this turn failed.`
- **Mapping to the sandbox:**
  - `screenshot` → `sandbox.desktop.screenshot()`
  - `zoom` → a screenshot with `region`
  - `cursor_position` → `sandbox.desktop.cursor()`
  - Everything else → `sandbox.desktop.input({ actions: [{ action: block.name, ...block.input }] })`
- **No scaling needed at 1920x1080.** That resolution fits the model's image limits (up to 2576 px on the long edge), so coordinates pass through unchanged. If you downscale screenshots with `scale`, also send `coordinate_scale` with the same value on input.
- **Optional config:** `configs: { zoom: { enabled: false } }` turns off the zoom action if you don't want it.

### TypeScript

```ts
import Anthropic from "@anthropic-ai/sdk";
import { Client } from "@taskcloud/sdk";

const anthropic = new Anthropic();
const client = new Client();

const sandbox = await client.sandboxes.create({ template: "desktop", size: "default" });
console.log("Watch live:", (await sandbox.desktop.stream({ read_only: true, ttl_seconds: 3600 })).url);

type Block = { type: string; id?: string; name?: string; input?: any; toolset_name?: string };

async function runAction(block: Block) {
  const input = block.input ?? {};
  switch (block.name) {
    case "screenshot": {
      const s = await sandbox.desktop.screenshot({ format: "png" });
      return [{ type: "image", source: { type: "base64", media_type: "image/png", data: s.data } }];
    }
    case "zoom": {
      const [x0, y0, x1, y1] = input.region;
      const s = await sandbox.desktop.screenshot({ format: "png", region: `${x0},${y0},${x1},${y1}` });
      return [{ type: "image", source: { type: "base64", media_type: "image/png", data: s.data } }];
    }
    case "cursor_position": {
      const c = await sandbox.desktop.cursor();
      return [{ type: "text", text: `X=${c.x}, Y=${c.y}` }];
    }
    default: {
      const r = await sandbox.desktop.input({ actions: [{ action: block.name, ...input }] });
      const res = r.results[0];
      if (res.status !== "ok") throw new Error(res.error ?? `${block.name} failed`);
      return [{ type: "text", text: "OK" }];
    }
  }
}

const messages: any[] = [
  { role: "user", content: "Open Firefox, go to news.ycombinator.com and tell me the top story title." },
];

try {
  while (true) {
    const response = await anthropic.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 16000,
      tools: [{ type: "computer_toolset_20260801" } as any],
      messages,
    });
    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "refusal") {
      console.error("Model declined the request:", response.stop_details);
      break;
    }
    const calls = (response.content as Block[]).filter((b) => b.type === "tool_use");
    if (calls.length === 0) {
      for (const b of response.content) if (b.type === "text") console.log(b.text);
      break;
    }

    const results: any[] = [];
    let failed = false;
    for (const call of calls) {
      const base = { type: "tool_result", tool_use_id: call.id, toolset_name: "computer" };
      if (failed) {
        results.push({ ...base, is_error: true, content: "Not executed: an earlier computer action in this turn failed." });
        continue;
      }
      try {
        results.push({ ...base, content: await runAction(call) });
      } catch (err) {
        failed = true;
        results.push({ ...base, is_error: true, content: String(err) });
      }
    }
    messages.push({ role: "user", content: results });
  }
} finally {
  await sandbox.pause(); // $0 compute while paused; the desktop session is kept
}
```

### Python

```python
import anthropic
from taskcloud import Client

claude = anthropic.Anthropic()
client = Client()

sandbox = client.sandboxes.create(template="desktop", size="default")
print("Watch live:", sandbox.desktop.stream(read_only=True, ttl_seconds=3600).url)

SKIPPED = "Not executed: an earlier computer action in this turn failed."


def image(data: str) -> list:
    return [{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": data}}]


def run_action(block) -> list:
    name, inp = block.name, dict(block.input or {})
    if name == "screenshot":
        return image(sandbox.desktop.screenshot(format="png").data)
    if name == "zoom":
        x0, y0, x1, y1 = inp["region"]
        return image(sandbox.desktop.screenshot(format="png", region=f"{x0},{y0},{x1},{y1}").data)
    if name == "cursor_position":
        c = sandbox.desktop.cursor()
        return [{"type": "text", "text": f"X={c.x}, Y={c.y}"}]
    result = sandbox.desktop.input(actions=[{"action": name, **inp}]).results[0]
    if result.status != "ok":
        raise RuntimeError(result.error or f"{name} failed")
    return [{"type": "text", "text": "OK"}]


messages = [{"role": "user", "content": "Open Firefox, go to news.ycombinator.com and tell me the top story title."}]

try:
    while True:
        response = claude.messages.create(
            model="claude-opus-5-5",
            max_tokens=16000,
            tools=[{"type": "computer_toolset_20260801"}],
            messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "refusal":
            print("Model declined the request:", response.stop_details)
            break
        calls = [b for b in response.content if b.type == "tool_use"]
        if not calls:
            print("".join(b.text for b in response.content if b.type == "text"))
            break

        results, failed = [], False
        for call in calls:
            base = {"type": "tool_result", "tool_use_id": call.id, "toolset_name": "computer"}
            if failed:
                results.append({**base, "is_error": True, "content": SKIPPED})
                continue
            try:
                results.append({**base, "content": run_action(call)})
            except Exception as err:
                failed = True
                results.append({**base, "is_error": True, "content": str(err)})
        messages.append({"role": "user", "content": results})
finally:
    sandbox.pause()  # $0 compute while paused; the desktop session is kept
```

### Tips

- **Batch the non-visual actions** into one `input` call when you control the sequence, and set `return_screenshot: true`. That saves a round trip.
- **Give a person a link to watch the agent.** Use a `read_only` stream URL with a short TTL.
- **Fork a prepared desktop to parallelize work.** For example, log in once and then fork with memory. Each fork has its own browser session. See [Snapshots and fork](https://task.cloud/docs/concepts/snapshots-and-fork.md).

## Security

- **Use a sandbox for untrusted browsing.** Each sandbox is a separate microVM with its own kernel. Don't put long-lived credentials on a desktop that an agent drives through untrusted websites.
- **Prompt injection is a risk.** Web pages can contain text that tries to redirect the agent. Restrict what the agent may do: use an API key limited to that sandbox (`restrict.sandbox_ids` or `restrict.labels`), keep a human in the loop for sensitive actions, and review the agent's actions in a recorded or read-only stream.
- **Hand out viewer links carefully.** Use `read_only: true`, a short `ttl_seconds` and `single_use: true` for links you give to end users, and revoke them when you're done. The VNC port is never exposed without a signed token.

See [Security](https://task.cloud/docs/security.md) and [Limits](https://task.cloud/docs/limits.md).

## Roadmap

- WebRTC streaming at 60 fps, audio, clipboard sync and file upload into the desktop are on the roadmap. They are not part of the MVP.
- No GPU instances are planned for the MVP.


---

<!-- source: https://task.cloud/docs/guides/webhooks.md -->

# Webhooks

Webhooks notify your backend when a sandbox changes state or your usage crosses a threshold, so you don't have to poll. Every delivery is signed with HMAC-SHA256.

## Events

| Event | Sent when |
| --- | --- |
| `sandbox.ready` | A new sandbox (created or forked) becomes `running` |
| `sandbox.paused` | A sandbox reaches `paused`, whether through the API, auto-pause or the spend limit |
| `sandbox.resumed` | A paused sandbox is `running` again, through the API or wake on request |
| `sandbox.error` | A sandbox enters `error` |
| `sandbox.deleted` | A sandbox reaches `deleted`, through the API or when `ttl_seconds` expires |
| `usage.threshold` | Usage crosses a threshold: a spend-limit alert (`alert_thresholds`, default 50%, 80%, 100% of `monthly_limit_usd`), 80% or 100% of the plan credit for the period, or 80% or 100% of the Free plan's 20 hours. Sent once per threshold and period |
| `webhook.test` | You call `POST /webhooks/{webhook_id}/test` |
| `sandbox.restored_from_checkpoint` | A sandbox runs again from an older saved state: its host failed while it was running, or restoring its memory on a new host could not finish. Work after `checkpoint.taken_at` is lost. See [Checkpoints and host failures](https://task.cloud/docs/concepts/lifecycle.md#checkpoints-and-host-failures) |

## Payload

```json
{
  "id": "evt_2af7cd3ka7zq",
  "type": "sandbox.paused",
  "created_at": "2026-11-09T12:00:00Z",
  "data": {
    "sandbox": { "id": "sbx_2fqxnt4bkq7m", "name": "user-42", "state": "paused", "size": "default", "labels": { "customer": "acme" } },
    "previous_state": "pausing",
    "state": "paused",
    "reason": "auto_pause"
  }
}
```

- `data.sandbox` is the full [Sandbox object](https://task.cloud/docs/api-reference.md). The example above is abbreviated.
- `data.reason` explains the transition. Possible values:
  - `api`
  - `auto_pause`
  - `wake_on_request`
  - `spend_limit`
  - `ttl_expired`
  - `host_maintenance`
  - `host_lost`: the host failed; the sandbox is restored from its newest checkpoint
  - an error code, for `sandbox.error`

### `sandbox.restored_from_checkpoint` payload

```json
{
  "id": "evt_9d2c4f7a1b3e",
  "type": "sandbox.restored_from_checkpoint",
  "created_at": "2026-11-09T12:00:05Z",
  "data": {
    "sandbox": { "id": "sbx_2fqxnt4bkq7m", "state": "running", "size": "default" },
    "reason": "host_lost",
    "ram_lost": true,
    "checkpoint": { "generation": 14, "kind": "disk", "taken_at": "2026-11-09T11:42:00Z" },
    "data_loss_window_seconds": 1085
  }
}
```

- `reason`: `host_lost` (the host failed while the sandbox ran), `restore_interrupted` (memory of a paused sandbox could not be fully restored on its new host, so it was restored again from the same saved state) or `resume` (a resume had only a disk checkpoint to use).
- `ram_lost: true`: the sandbox was restored from a disk checkpoint and booted. Files are as of `taken_at`; processes, `/dev/shm` and other in-memory state restarted. Re-run your agent's setup or resume from its own on-disk progress.
- `ram_lost: false`: restored from a pause snapshot (`kind: memory`): memory, processes and files are as of `taken_at`.

### `usage.threshold` payload

```json
{
  "id": "evt_7c1d0e5b2a90",
  "type": "usage.threshold",
  "created_at": "2026-11-20T14:02:11Z",
  "data": {
    "kind": "spend_limit",
    "percent": 100,
    "threshold_usd": 50,
    "amount_usd": 50.02,
    "limit_usd": 50,
    "action": "paused_running",
    "period_start": "2026-11-09T00:00:00Z",
    "period_end": "2026-12-09T00:00:00Z"
  }
}
```

- `kind`: `spend_limit` (amount due vs `monthly_limit_usd`), `credit` (usage vs the plan credit of the period) or `free_allowance` (usage vs the Free plan's 20 hours).
- `action`: what TaskCloud did. `paused_running`: running sandboxes are being paused, and each one also sends `sandbox.paused` with `reason: "spend_limit"`. `blocked_new`: new starts get `402`. `none`: an alert only.

## Headers

| Header | Value |
| --- | --- |
| `Webhook-Id` | Event ID (`evt_...`). Stays the same across retries, so use it to de-duplicate. |
| `Webhook-Timestamp` | Unix time in seconds when this attempt was signed |
| `Webhook-Signature` | `v1=<hex>`. During secret rotation it holds two space-separated values, e.g. `v1=abc... v1=def...` |
| `Webhook-Event` | The event type, e.g. `sandbox.paused` |
| `Webhook-Attempt` | Attempt number, starting at `1` |

## Creating an endpoint

```bash
curl -X POST https://api.task.cloud/v1/webhooks \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/taskcloud", "events": ["sandbox.ready", "sandbox.paused", "sandbox.resumed", "sandbox.error", "sandbox.deleted"], "description": "prod"}'
```

```ts
const webhook = await client.webhooks.create({
  url: "https://example.com/hooks/taskcloud",
  events: ["sandbox.ready", "sandbox.paused", "sandbox.error"],
  description: "prod",
});
console.log(webhook.secret); // whsec_..., shown only once
```

```python
webhook = client.webhooks.create(
    url="https://example.com/hooks/taskcloud",
    events=["sandbox.ready", "sandbox.paused", "sandbox.error"],
    description="prod",
)
print(webhook.secret)  # shown only once
```

```bash
taskcloud webhook create --url https://example.com/hooks/taskcloud --event sandbox.ready --event sandbox.paused
taskcloud webhook ls
taskcloud webhook test whk_5mz2qk7hbd4x
```

Requirements and limits:

- Up to **10 endpoints** per account. This requires the `webhooks:manage` scope.
- Endpoints must use **HTTPS on port 443** and resolve to a public IP. Redirects are not followed.
- The `secret` (`whsec_...`) is returned **only once**, in the create or rotate response.

## Verifying signatures

Compute the signature as follows:

```
signed_payload = Webhook-Id + "." + Webhook-Timestamp + "." + raw_request_body
signature      = hex( HMAC-SHA256( key = secret, message = signed_payload ) )
```

The key is the **whole secret string, including the `whsec_` prefix**, encoded as UTF-8.

1. Read the **raw** request body. Don't re-serialize parsed JSON.
2. Reject the request if `Webhook-Timestamp` is more than **300 seconds** from your clock.
3. Compute the expected signature and compare it in **constant time** with each `v1=` value in `Webhook-Signature`. Accept the request if any value matches.
4. De-duplicate on `Webhook-Id`.
5. Respond with `2xx` quickly. Do slow work asynchronously.

### TypeScript (Express, Node `crypto`)

```ts
import express from "express";
import crypto from "node:crypto";

const SECRET = process.env.WEBHOOK_SECRET!; // "whsec_..."
const app = express();

function verify(rawBody: Buffer, headers: express.Request["headers"]): boolean {
  const id = headers["webhook-id"] as string | undefined;
  const ts = headers["webhook-timestamp"] as string | undefined;
  const sigHeader = headers["webhook-signature"] as string | undefined;
  if (!id || !ts || !sigHeader) return false;

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(ts));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${id}.${ts}.`)
    .update(rawBody)
    .digest();

  return sigHeader.split(" ").some((part) => {
    const [version, hex] = part.split("=", 2);
    if (version !== "v1" || !hex) return false;
    const given = Buffer.from(hex, "hex");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

app.post("/hooks/taskcloud", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.headers)) return res.status(400).send("invalid signature");
  const event = JSON.parse(req.body.toString("utf8"));
  // TODO: skip if event.id was already processed
  console.log(event.type, event.data.sandbox.id, event.data.reason);
  res.sendStatus(204);
});

app.listen(3000);
```

### Python (Flask)

```python
import hashlib, hmac, json, os, time
from flask import Flask, request, abort

SECRET = os.environ["WEBHOOK_SECRET"].encode()  # b"whsec_..."
app = Flask(__name__)


def verify(raw_body: bytes, headers) -> bool:
    msg_id = headers.get("Webhook-Id")
    ts = headers.get("Webhook-Timestamp")
    sig_header = headers.get("Webhook-Signature")
    if not (msg_id and ts and sig_header):
        return False
    try:
        if abs(time.time() - int(ts)) > 300:
            return False
    except ValueError:
        return False
    expected = hmac.new(SECRET, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(
        part.startswith("v1=") and hmac.compare_digest(part[3:], expected)
        for part in sig_header.split(" ")
    )


@app.post("/hooks/taskcloud")
def hook():
    raw = request.get_data()  # raw bytes, before JSON parsing
    if not verify(raw, request.headers):
        abort(400)
    event = json.loads(raw)
    # TODO: skip if event["id"] was already processed
    print(event["type"], event["data"]["sandbox"]["id"], event["data"].get("reason"))
    return "", 204
```

With FastAPI, read `await request.body()` and pass the bytes to the same `verify` function.

### Using the SDK helpers

```ts
import { verifyWebhook } from "@taskcloud/sdk/webhooks";

app.post("/hooks/taskcloud", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = verifyWebhook({ payload: req.body, headers: req.headers, secret: process.env.WEBHOOK_SECRET! });
    // event is the parsed, typed WebhookEvent
    res.sendStatus(204);
  } catch {
    res.status(400).send("invalid signature");
  }
});
```

```python
from taskcloud.webhooks import verify_webhook

event = verify_webhook(payload=request.get_data(), headers=request.headers, secret=os.environ["WEBHOOK_SECRET"])
# raises an exception if the signature or timestamp is invalid
```

## Delivery and retries

- **Concurrent.** Each endpoint gets at most 2 deliveries at a time, and a slow endpoint does not delay other endpoints.
- **At-least-once, unordered.** The same event can arrive more than once, and `sandbox.resumed` can arrive before `sandbox.paused`. Use `Webhook-Id` to de-duplicate, and compare `created_at` (or call `GET /sandboxes/{sandbox_id}`) for the current state.
- **Success** is any `2xx` response within **10 seconds**. Anything else, including a timeout, is retried with exponential backoff, for up to **8 attempts** over **24 hours**.
- **Delivery history** for the last 30 days: `GET /webhooks/{webhook_id}/deliveries`.
- **Pause an endpoint** with `PATCH /webhooks/{webhook_id}` and `{"enabled": false}`.

## Rotating the secret

`POST /webhooks/{webhook_id}/rotate-secret` returns a new `secret`. For the next **24 hours**, every delivery is signed with both the old and the new secret (two `v1=` values in `Webhook-Signature`).

1. Deploy the new secret.
2. Confirm that verification still passes.
3. Let the old secret lapse.

```ts
const { secret } = await client.webhooks.rotateSecret("whk_5mz2qk7hbd4x");
```

```python
secret = client.webhooks.rotate_secret("whk_5mz2qk7hbd4x").secret
```

```bash
taskcloud webhook rotate whk_5mz2qk7hbd4x
```

## Testing

`POST /webhooks/{webhook_id}/test` sends a signed `webhook.test` event and returns the delivery result: `status`, `response_status` and `duration_ms`. To test against a local server, expose it through a public HTTPS tunnel, or run the receiver inside a sandbox and expose its port (see [Networking](https://task.cloud/docs/guides/networking.md)).


---

<!-- source: https://task.cloud/docs/guides/migrate-from-e2b.md -->

# Migrate from E2B

`TaskCloud` covers the same core workflow as E2B: create a sandbox from a template, run commands, read and write files, expose ports, pause and resume. Most migrations are a mechanical rename. This page maps the concepts and lists the differences in behavior.

> **E2B compatibility adapter: Coming soon.** We plan an adapter that lets existing E2B SDK code run against `TaskCloud` after you change the import and the API key. Until it ships, use the mapping below.
>
> E2B's SDKs change over time. The E2B names below describe its public SDK in general terms; check E2B's current documentation for exact signatures.

## What changes conceptually

| | E2B | TaskCloud |
| --- | --- | --- |
| Isolation | Firecracker microVM | Firecracker microVM with its own kernel, Ubuntu 24.04, root, systemd and Docker inside |
| Lifetime | Session with a timeout. The sandbox is killed or paused when the timeout runs out. | **Persistent computer.** No time limit by default. Idle sandboxes auto-pause (default after 5 min) and wake on the next request. |
| Disk | Ephemeral unless paused | Persistent disk (50 GB included with `default`) |
| Billing while idle | Depends on plan and pause usage | **$0 compute while paused**, billed per second while running |
| Fork | — | Fork a running VM **with memory** (target < 2 s) |
| Region | Check E2B | EU only |

## API and SDK mapping

| E2B (general) | TaskCloud TypeScript | TaskCloud REST |
| --- | --- | --- |
| `Sandbox.create(template)` | `client.sandboxes.create({ template })` | `POST /sandboxes` |
| Connect to an existing sandbox by ID | `client.sandboxes.get(id)` | `GET /sandboxes/{sandbox_id}` |
| `sandbox.commands.run(cmd)` | `sandbox.exec({ command })` | `POST /sandboxes/{sandbox_id}/exec` |
| Run in the background | `sandbox.exec({ command, background: true })` | same endpoint, `background: true` |
| Stream output callbacks | `sandbox.exec({ command, stream: true })` | same endpoint, `stream: true` (SSE) |
| Interactive terminal (PTY) | PTY session over WebSocket | `POST /sandboxes/{sandbox_id}/pty` |
| `files.read(path)` / `files.write(path, data)` | `sandbox.files.read(path)` / `sandbox.files.write(path, data)` | `GET` / `PUT /sandboxes/{sandbox_id}/files/content` |
| `files.list(dir)` | `sandbox.files.list(dir)` | `GET /sandboxes/{sandbox_id}/files` |
| `files.watchDir(dir)` | `sandbox.files.watch(dir)` | `GET /sandboxes/{sandbox_id}/files/watch` (SSE) |
| `getHost(port)` | `sandbox.ports.expose({ port, visibility })` returns `url` | `POST /sandboxes/{sandbox_id}/ports` → `https://<short_id>-<port>.taskhost.cloud` |
| Sandbox timeout / `setTimeout` | `auto_pause.idle_timeout_seconds` (pause when idle) or `ttl_seconds` (delete after N s) | `PATCH /sandboxes/{sandbox_id}` |
| Pause / resume | `sandbox.pause()` / `sandbox.resume()`, plus automatic pause and wake on request | `POST .../pause`, `POST .../resume` |
| `kill()` | `sandbox.delete()` | `DELETE /sandboxes/{sandbox_id}` |
| Custom template (Dockerfile-based) | Template from an OCI image | `POST /templates` with `image` |
| Desktop SDK | `template: "desktop"` + `sandbox.desktop.*` | `/desktop`, `/screenshot`, `/input` |
| API key header | `Authorization: Bearer taskcloud_sk_...` | — |

### Before and after

```ts
// E2B (illustrative)
// const sbx = await Sandbox.create("my-template");
// const r = await sbx.commands.run("python app.py");
// const url = `https://${sbx.getHost(3000)}`;

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

const client = new Client(); // reads TASKCLOUD_API_KEY
const sandbox = await client.sandboxes.create({ template: "my-template" });
const r = await sandbox.exec({ command: "python app.py", timeout_seconds: 120 });
console.log(r.exit_code, r.stdout);

await sandbox.exec({ command: "python -m http.server 3000", background: true });
const { url } = await sandbox.ports.expose({ port: 3000, visibility: "public" });
```

```python
from taskcloud import Client

client = Client()
sandbox = client.sandboxes.create(template="my-template")
r = sandbox.exec(command="python app.py", timeout_seconds=120)
print(r.exit_code, r.stdout)
```

## Templates

E2B templates are typically built from a Dockerfile. On `TaskCloud`:

1. Build and push the image to any OCI registry: `docker build -t ghcr.io/acme/env:1 . && docker push ...`.
2. `POST /templates` with `{"name": "my-template", "image": {"ref": "ghcr.io/acme/env:1"}}`. Add `start_command` and `ready_check` if something must be running before the snapshot is taken.
3. Create sandboxes with `template: "my-template"`. The template is a RAM snapshot, so a new sandbox starts with your processes already running (target p95 < 500 ms).

A second option: set up one sandbox by hand, take a snapshot and turn it into a template (`snapshot_id`). See [Templates](https://task.cloud/docs/concepts/templates.md).

## Timeouts: think "idle" instead of "max lifetime"

An E2B sandbox usually lives for a fixed time window. A `TaskCloud` sandbox is meant to persist, and the controls are:

- **`auto_pause.idle_timeout_seconds`** (default 300): pause after this much idle time. Paused sandboxes cost $0 for compute, and the next exec, file, port, SSH or desktop request wakes them (target p95 < 800 ms).
- **`ttl_seconds`**: delete the sandbox automatically after N seconds. Use it for one-off jobs.
- **`always_on: true`**: never pause (fixed monthly price, `default` size only).

So a typical "give every user their own VM" setup is: create one sandbox per user, keep it forever, and let auto-pause handle cost. See [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md).

## Cost comparison

Hourly price for 4 vCPU / 8 GB, according to battleships.dev as of 2026-10: E2B **$0.331** per hour; `TaskCloud` `default` **$0.030** per active hour.

Example: 1000 VMs, each active 10% of the time (73 h/month):

| | Monthly |
| --- | --- |
| E2B (73 h × $0.331) | ~$24,163 |
| TaskCloud (73 h × $0.030, $0 while paused) | ~$2,190 |

Your numbers depend on your plan and usage. Check current pricing on both sides. See [Billing](https://task.cloud/docs/billing.md).

## Checklist

- [ ] Create a `TaskCloud` API key with the `full-sandbox` preset (`POST /api-keys`)
- [ ] Rebuild custom templates from your image (`POST /templates`)
- [ ] Replace SDK calls using the table above (snake_case fields, e.g. `timeout_seconds`, `background`)
- [ ] Replace per-session timeouts with `auto_pause` and/or `ttl_seconds`
- [ ] Update preview URLs to `https://<short_id>-<port>.taskhost.cloud`
- [ ] Subscribe to [webhooks](https://task.cloud/docs/guides/webhooks.md) (`sandbox.ready`, `sandbox.paused`, `sandbox.error`, ...)
- [ ] Handle errors by `error.code` and `error.retryable` (see [API reference](https://task.cloud/docs/api-reference.md))


---

<!-- source: https://task.cloud/docs/guides/migrate-from-boat.md -->

# Migrate from boat.dev

The `TaskCloud` REST API follows the resource model of boat.dev's API (sandboxes, commands, files, hosted ports, snapshots, webhooks), so most code ports directly. The main differences:

- Field names are `snake_case`.
- "Stop" becomes **pause**, and pause keeps RAM.
- Idle sandboxes pause automatically (default after 5 min) and wake on request, so you pay for active seconds, not for the time until an auto-stop timer fires.

> **boat.dev compatibility adapter: Coming soon.** Until it ships, use the mapping below. The boat.dev details here come from its public documentation as of 2026-11; check boat.dev's current docs for exact behavior.

## Key differences

| | boat.dev | TaskCloud |
| --- | --- | --- |
| Base URL | `https://boat.dev/api/v1` | `https://api.task.cloud/v1` |
| JSON style | camelCase, `{"ok": true, "type": ...}` envelope | snake_case, plain resource objects |
| Errors | `{"ok": false, "code", "message", "error": {...}, "requestId"}` | `{"error": {"code", "message", "retryable", "status", "request_id", "details"}}` |
| Stop / resume | Stop saves a disk snapshot; resume boots again | **Pause** snapshots RAM and disk; resume restores the running state (target p95 < 800 ms) |
| Auto-stop | TTL-based auto-stop | **Auto-pause when idle** (default 5 min) plus **wake on request** (HTTP, SSH, API) |
| Fork | From the last disk snapshot | From the live VM **including memory** (target < 2 s) |
| Billing | Per second while the VM runs (until you stop it or its auto-stop timer fires) | Per second while running; **$0 compute while paused** |
| Delete | Requires the `X-Ascii-Confirm-Delete` header | Plain `DELETE` (no confirmation header) |
| Idempotency | `idempotencyKey` field | `Idempotency-Key` header |
| Rate-limit headers | `RateLimit-Policy` / `RateLimit` | Same headers (IETF draft), with policies `default` and `starts` |

## Endpoint mapping

| boat.dev | TaskCloud | Notes |
| --- | --- | --- |
| `POST /sandboxes` (`type`, `ttlSeconds`, `from`, `hostedPorts`) | `POST /sandboxes` (`size`, `ttl_seconds`, `template` or `snapshot_id`, `ports`) | `small` / `default` / `large` map directly. `xlarge` has no equivalent yet. |
| `GET /sandboxes`, `GET /sandboxes/{id}` | same paths | Filters: `state`, `label=key=value`, `name_prefix` |
| `PATCH /sandboxes/{id}` (extend) | `PATCH /sandboxes/{sandbox_id}` | `ttl_seconds`, `auto_pause`, `always_on` |
| `POST /sandboxes/{id}/stop` | `POST /sandboxes/{sandbox_id}/pause` | RAM is kept |
| `POST /sandboxes/{id}/resume` | `POST /sandboxes/{sandbox_id}/resume` | Usually not needed: requests wake the sandbox automatically. The size can't change on resume. |
| `POST /sandboxes/{id}/fork` | `POST /sandboxes/{sandbox_id}/fork` | Includes memory. Same size as the source. Bulk fork: `count` up to 50 per call, all or nothing. |
| `DELETE /sandboxes/{id}` | `DELETE /sandboxes/{sandbox_id}` | Returns `202` |
| `POST /sandboxes/{id}/commands` (`command`, `timeoutSeconds`, `detached`, `stream`) | `POST /sandboxes/{sandbox_id}/exec` (`command`, `timeout_seconds`, `background`, `stream`) | Sync max 600 s. Background has no limit. Stream is SSE. |
| `GET /sandboxes/{id}/commands/{processId}` and `.../stream` | `GET .../commands/{command_id}` and `.../stream` | Kill: `POST .../commands/{command_id}/kill` |
| `GET` / `PUT` / `DELETE /sandboxes/{id}/files` | `GET` / `PUT /sandboxes/{sandbox_id}/files/content`, `DELETE /sandboxes/{sandbox_id}/files` | Read limit 1 GiB per request (boat.dev: 5 MiB) |
| `GET .../files/list`, `.../files/info` | `GET .../files`, `GET .../files/stat` | |
| `POST .../files/folder`, `.../files/move` | `POST .../files/mkdir`, `.../files/move` | |
| `POST .../files/upload-url`, `.../download-url` | same paths | Up to 10 GiB; URLs valid 15 min by default, 1 h max |
| `POST /sandboxes/{id}/host` (`port`, `public`) | `POST /sandboxes/{sandbox_id}/ports` (`port`, `visibility`) | URL `https://<short_id>-<port>.taskhost.cloud` |
| `POST /sandboxes/{id}/desktop` | `POST /sandboxes/{sandbox_id}/desktop` | KasmVNC signed URL with `ttl_seconds`, `read_only`. Screenshot and input endpoints are also available. |
| `POST /sandboxes/{id}/sshkey` | `POST /sandboxes/{sandbox_id}/ssh` or account-wide `POST /ssh-keys` | Gateway `ssh.taskhost.cloud` |
| `GET` / `POST /saved-snapshots` | `POST /sandboxes/{sandbox_id}/snapshots`, `GET /snapshots` | Turn a snapshot into a reusable template with `POST /templates` |
| `GET /sandboxes/{id}/usage` | `GET /sandboxes/{sandbox_id}/usage` | Also account-wide: `GET /usage?group_by=sandbox` |
| `GET /limits` | `GET /limits` | |
| `GET` / `POST /api-keys`, `POST /api-keys/scoped` | `GET` / `POST /api-keys` | Presets `read-only`, `full-sandbox`, `ci`, `admin` are kept; restrict a key with `restrict.sandbox_ids` / `restrict.labels` |
| `GET` / `POST /webhooks`, `POST /webhooks/{id}/rotate` | `GET` / `POST /webhooks`, `POST /webhooks/{webhook_id}/rotate-secret` | See below |

## Webhooks

| boat.dev event | TaskCloud event |
| --- | --- |
| `sandbox.ready` | `sandbox.ready` (new sandbox) and `sandbox.resumed` (after pause) |
| `sandbox.error` | `sandbox.error` |
| `sandbox.archived` (stopped) | `sandbox.paused` |
| — | `sandbox.deleted` |
| `sandbox.hydrated`, `sandbox.degraded`, `sandbox.recovered` | No equivalent. Resume restores memory and disk together, so there is no separate hydration step. |

The signature scheme is the same shape: hex `HMAC-SHA256(secret, id + "." + timestamp + "." + raw_body)`, prefixed `v1=`, with a 300 s window. Only the header names change:

| boat.dev | TaskCloud |
| --- | --- |
| `X-Ascii-Delivery` | `Webhook-Id` |
| `X-Ascii-Timestamp` | `Webhook-Timestamp` |
| `X-Ascii-Signature` | `Webhook-Signature` |
| `X-Ascii-Event` | `Webhook-Event` |
| `X-Ascii-Attempt` | `Webhook-Attempt` |

The payload uses `created_at`, `previous_state` and `state` (instead of camelCase), and adds `reason`. See [Webhooks](https://task.cloud/docs/guides/webhooks.md).

## CLI mapping

| boat | taskcloud |
| --- | --- |
| `boat login` | `taskcloud login` |
| `boat new --type default` | `taskcloud create --size default` |
| `boat new --from <snapshot>` | `taskcloud create --snapshot <snapshot_id>` or `--template <name>` |
| `boat list` / `boat info <id>` | `taskcloud list` / `taskcloud get <id>` |
| `boat exec <id> -- npm test` | `taskcloud exec <id> -- npm test` |
| `boat ssh <id>` | `taskcloud ssh <id>` |
| `boat stop <id>` | `taskcloud pause <id>` |
| `boat resume <id>` | `taskcloud resume <id>` |
| `boat fork <id>` | `taskcloud fork <id>` |
| `boat host <id> 3000 --public` | `taskcloud port expose <id> 3000 --public` |
| `boat desktop <id>` | `taskcloud desktop <id> --open` |
| `boat delete <id>` | `taskcloud delete <id>` |

See [CLI](https://task.cloud/docs/cli.md) for the full reference.

## Example: create, run, stop → create, run, (auto-)pause

```bash
# boat.dev
curl -X POST https://boat.dev/api/v1/sandboxes -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" -d '{"ttlSeconds":3600}'

# TaskCloud
curl -X POST https://api.task.cloud/v1/sandboxes -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"base","size":"default","auto_pause":{"enabled":true,"idle_timeout_seconds":300}}'

curl -X POST https://api.task.cloud/v1/sandboxes/$SANDBOX_ID/exec -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" -d '{"command":"echo hello","timeout_seconds":30}'
# No explicit stop needed: after 5 idle minutes the sandbox pauses; the next request wakes it.
```

## Not available (yet)

| boat.dev feature | Status on TaskCloud |
| --- | --- |
| Built-in agent harnesses (`boat prompt`, conversations, steer/interrupt) | Not planned. We are infrastructure: run Claude Code, Codex or your own agent inside the sandbox. |
| AI credential profiles and AI key proxy | Roadmap |
| Environments with repositories, setup scripts and secrets | Use [templates](https://task.cloud/docs/concepts/templates.md) (from an image or snapshot) plus `env` at creation |
| Nested virtualization (`/dev/kvm`) | Roadmap (separate class on Cloud Hypervisor) |
| OpenTelemetry export | Not in the MVP. Use webhooks and the usage API. |
| `xlarge` size | Not available. The largest size is `large` (8 vCPU / 16 GB). |

## Cost comparison

Hourly price for 4 vCPU / 8 GB, according to battleships.dev as of 2026-10: boat.dev **$0.036** per running hour. `TaskCloud` `default` is **$0.030** per active hour, and $0 compute while paused.

The list prices are close, so the difference comes from how long a VM stays billed after the work stops:

- boat.dev stops a VM on a timer you set (default 1 h). Until the timer fires, the VM is running and billed, and resuming it boots the machine again.
- `TaskCloud` pauses an idle VM after 5 minutes by default, keeps its RAM, and resumes it on the next request.

How much that saves depends on your session pattern and auto-stop setting. Paste a usage export into the [bill calculator](https://task.cloud/bill-calculator.html) to see both bills side by side.

See [Billing](https://task.cloud/docs/billing.md) for how active time is measured.


---

<!-- source: https://task.cloud/docs/api-reference.md -->

# API reference

The full, machine-readable reference is the **OpenAPI 3.1 spec**:

- Hosted: `https://api.task.cloud/v1/openapi.yaml`
- On this site: [`openapi.yaml`](https://task.cloud/docs/openapi.yaml) (a copy of `api/openapi.yaml` from the repository, published with every docs build)

Generate a client in any language from it (for example with `openapi-generator`), or import it into Postman or Insomnia. The official [TypeScript](https://task.cloud/docs/sdk/typescript.md) and [Python](https://task.cloud/docs/sdk/python.md) SDKs are hand-written from the same file and tested against it.

## Basics

| Topic | Rule |
| --- | --- |
| Base URL | `https://api.task.cloud/v1` |
| Auth | `Authorization: Bearer taskcloud_sk_...` (scheme name case-insensitive); each endpoint needs the scope listed below ([Security](https://task.cloud/docs/security.md)) |
| Format | JSON with `snake_case` fields; file content is raw bytes; streams are Server-Sent Events; PTY is a WebSocket |
| IDs | `sbx_` sandbox, `cmd_` command, `pty_` PTY, `dsk_` desktop stream, `snap_` snapshot, `tpl_` template, `whk_` webhook, `evt_` event, `key_` API key |
| Timestamps | RFC 3339, UTC |
| Pagination | `?limit=` (1–100, default 20) and `?cursor=`; responses `{"data": [...], "has_more": true, "next_cursor": "..."}` |
| Idempotency | `Idempotency-Key` header on `POST /sandboxes`, `/fork`, `/snapshots`, `/templates` (kept 24 h) |
| Rate limits | `RateLimit-Policy` and `RateLimit` headers on every response, including `401` and unknown routes; `429` with `Retry-After` ([Limits](https://task.cloud/docs/limits.md)) |
| Request ID | `X-Request-Id` on every response |
| Wake on request | Calls that need a running VM wake a paused sandbox; add `?auto_resume=false` to get `409 sandbox_paused` instead |

## Errors

Every error has the same shape:

```json
{
  "error": {
    "code": "concurrency_limit_reached",
    "message": "Your plan allows 10 concurrent sandboxes.",
    "retryable": false,
    "status": 409,
    "request_id": "req_01HF3X",
    "details": { "limit": 10, "used": 10 }
  }
}
```

Branch on `code`, never on `message`. Retry only when `retryable` is `true`, after `Retry-After` if present.

| Status | Codes |
| --- | --- |
| 400 | `invalid_request`, `invalid_path`, `invalid_template`, `invalid_image` |
| 401 | `unauthorized` |
| 402 | `payment_required`, `spend_limit_reached`, `free_hours_exhausted` |
| 403 | `forbidden`, `insufficient_scope` |
| 404 | `not_found` |
| 408 | `exec_timeout` |
| 409 | `invalid_state`, `sandbox_paused`, `sandbox_busy` (retryable, `Retry-After`), `concurrency_limit_reached`, `idempotency_conflict`, `already_exists`, `desktop_not_available`, `snapshot_in_use` |
| 412 | `precondition_failed` |
| 413 | `payload_too_large` |
| 416 | `invalid_request`: a `Range` on `GET .../files/content` starts past the end of the file (`details.size`) |
| 429 | `rate_limited` (retryable); `details.reason = "too_many_operations"`: too many concurrent operations on one sandbox |
| 500 | `internal_error` (retryable) |
| 502 | `sandbox_unreachable` (see `retryable`) |
| 503 | `capacity_unavailable` (retryable; `details.reason = "incompatible_host"` when a paused sandbox's snapshot needs a compatible host, see `pause_reason`), `service_unavailable` (retryable) |
| 507 | `insufficient_storage`: the sandbox disk is full (not retryable) |

## Endpoints

### Sandboxes

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/sandboxes` | List sandboxes | `sandboxes:read` |
| `POST` | `/sandboxes` | Create a sandbox | `sandboxes:write` |
| `GET` | `/sandboxes/{sandbox_id}` | Get a sandbox | `sandboxes:read` |
| `PATCH` | `/sandboxes/{sandbox_id}` | Update a sandbox | `sandboxes:write` |
| `DELETE` | `/sandboxes/{sandbox_id}` | Delete a sandbox | `sandboxes:write` |
| `POST` | `/sandboxes/{sandbox_id}/pause` | Pause a sandbox | `sandboxes:write` |
| `POST` | `/sandboxes/{sandbox_id}/resume` | Resume a sandbox | `sandboxes:write` |
| `POST` | `/sandboxes/{sandbox_id}/fork` | Fork a sandbox | `sandboxes:write` |

### Exec

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `POST` | `/sandboxes/{sandbox_id}/exec` | Run a command | `exec` |
| `GET` | `/sandboxes/{sandbox_id}/commands` | List commands | `exec` |
| `GET` | `/sandboxes/{sandbox_id}/commands/{command_id}` | Get a command | `exec` |
| `GET` | `/sandboxes/{sandbox_id}/commands/{command_id}/stream` | Attach to a command's output (SSE) | `exec` |
| `POST` | `/sandboxes/{sandbox_id}/commands/{command_id}/stdin` | Write to a command's stdin | `exec` |
| `POST` | `/sandboxes/{sandbox_id}/commands/{command_id}/kill` | Send a signal to a command | `exec` |
| `POST` | `/sandboxes/{sandbox_id}/pty` | Create an interactive PTY session | `exec` |
| `GET` | `/sandboxes/{sandbox_id}/pty/{pty_id}` | Get a PTY session (and a fresh connect URL) | `exec` |
| `DELETE` | `/sandboxes/{sandbox_id}/pty/{pty_id}` | Close a PTY session | `exec` |
| `GET` | `/sandboxes/{sandbox_id}/pty/{pty_id}/connect` | PTY WebSocket endpoint | signed token |

### Files

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/sandboxes/{sandbox_id}/files` | List a directory | `files:read` |
| `DELETE` | `/sandboxes/{sandbox_id}/files` | Delete a file or directory | `files:write` |
| `GET` | `/sandboxes/{sandbox_id}/files/content` | Read a file | `files:read` |
| `PUT` | `/sandboxes/{sandbox_id}/files/content` | Write a file | `files:write` |
| `GET` | `/sandboxes/{sandbox_id}/files/stat` | Get file metadata | `files:read` |
| `POST` | `/sandboxes/{sandbox_id}/files/mkdir` | Create a directory | `files:write` |
| `POST` | `/sandboxes/{sandbox_id}/files/move` | Move or rename a file or directory | `files:write` |
| `POST` | `/sandboxes/{sandbox_id}/files/upload` | Upload files (multipart) | `files:write` |
| `GET` | `/sandboxes/{sandbox_id}/files/download` | Download a directory as an archive | `files:read` |
| `POST` | `/sandboxes/{sandbox_id}/files/upload-url` | Create a signed upload URL | `files:write` |
| `POST` | `/sandboxes/{sandbox_id}/files/download-url` | Create a signed download URL | `files:read` |
| `GET` | `/sandboxes/{sandbox_id}/files/watch` | Watch a path for changes (SSE) | `files:read` |

### Networking

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/sandboxes/{sandbox_id}/ports` | List exposed ports | `sandboxes:read` |
| `POST` | `/sandboxes/{sandbox_id}/ports` | Expose a port on a public HTTPS URL | `sandboxes:write` |
| `DELETE` | `/sandboxes/{sandbox_id}/ports/{port}` | Remove a public URL | `sandboxes:write` |
| `POST` | `/sandboxes/{sandbox_id}/access-tokens` | Create an access token for private ports | `sandboxes:write` |
| `POST` | `/sandboxes/{sandbox_id}/ssh` | Get SSH access | `ssh` |
| `GET` | `/ssh-keys` | List account SSH keys | `ssh` |
| `POST` | `/ssh-keys` | Add an account SSH key | `ssh` |
| `DELETE` | `/ssh-keys/{ssh_key_id}` | Remove an account SSH key | `ssh` |

### Desktop

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `POST` | `/sandboxes/{sandbox_id}/desktop` | Create a desktop stream URL | `desktop` |
| `GET` | `/sandboxes/{sandbox_id}/desktop` | List active desktop stream URLs | `desktop` |
| `DELETE` | `/sandboxes/{sandbox_id}/desktop/{stream_id}` | Revoke a desktop stream URL | `desktop` |
| `GET` | `/sandboxes/{sandbox_id}/screenshot` | Take a screenshot | `desktop` |
| `POST` | `/sandboxes/{sandbox_id}/input` | Send mouse and keyboard input | `desktop` |
| `GET` | `/sandboxes/{sandbox_id}/cursor` | Get the cursor position | `desktop` |

### Snapshots

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `POST` | `/sandboxes/{sandbox_id}/snapshots` | Create a named snapshot | `snapshots:write` |
| `GET` | `/snapshots` | List snapshots | `snapshots:read` |
| `GET` | `/snapshots/{snapshot_id}` | Get a snapshot | `snapshots:read` |
| `DELETE` | `/snapshots/{snapshot_id}` | Delete a snapshot | `snapshots:write` |

### Templates

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/templates` | List templates | `templates:read` |
| `POST` | `/templates` | Create a template | `templates:write` |
| `GET` | `/templates/{template_id}` | Get a template | `templates:read` |
| `DELETE` | `/templates/{template_id}` | Delete a template | `templates:write` |
| `GET` | `/templates/{template_id}/logs` | Get template build logs | `templates:read` |

### Webhooks

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/webhooks` | List webhook endpoints | `webhooks:manage` |
| `POST` | `/webhooks` | Create a webhook endpoint | `webhooks:manage` |
| `GET` | `/webhooks/{webhook_id}` | Get a webhook endpoint | `webhooks:manage` |
| `PATCH` | `/webhooks/{webhook_id}` | Update a webhook endpoint | `webhooks:manage` |
| `DELETE` | `/webhooks/{webhook_id}` | Delete a webhook endpoint | `webhooks:manage` |
| `POST` | `/webhooks/{webhook_id}/rotate-secret` | Rotate the signing secret | `webhooks:manage` |
| `POST` | `/webhooks/{webhook_id}/test` | Send a test event | `webhooks:manage` |
| `GET` | `/webhooks/{webhook_id}/deliveries` | List recent deliveries | `webhooks:manage` |

### Usage

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/usage` | Get usage and cost | `usage:read` |
| `GET` | `/sandboxes/{sandbox_id}/usage` | Get usage for one sandbox | `usage:read` |
| `GET` | `/limits` | Get account limits and current consumption | `usage:read` |

### API keys

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/api-keys` | List API keys | `api_keys:manage` |
| `POST` | `/api-keys` | Create an API key | `api_keys:manage` |
| `GET` | `/api-keys/{api_key_id}` | Get an API key | `api_keys:manage` |
| `DELETE` | `/api-keys/{api_key_id}` | Revoke an API key | `api_keys:manage` |
| `POST` | `/api-keys/{api_key_id}/rotate` | Rotate an API key | `api_keys:manage` |

### Account

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/account` | Get the account | `account:read` |
| `PUT` | `/account/spend-limit` | Set the monthly spend limit | `account:manage` |

### Members and billing

Used by the web console with a session, or with an API key ([Teams and roles](https://task.cloud/docs/teams.md)).

| Method | Path | Summary | Scope |
| --- | --- | --- | --- |
| `GET` | `/members` | List organization members | `account:read` |
| `PATCH` | `/members/{user_id}` | Change a member's role | `account:manage` |
| `DELETE` | `/members/{user_id}` | Remove a member (or leave) | `account:manage` |
| `GET` | `/invitations` | List invitations | `account:read` |
| `POST` | `/invitations` | Invite someone to the organization | `account:manage` |
| `DELETE` | `/invitations/{invitation_id}` | Revoke a pending invitation | `account:manage` |
| `GET` | `/billing` | Get the billing overview | `account:read` |
| `POST` | `/billing/checkout` | Upgrade to a paid plan | `account:manage` |
| `POST` | `/billing/portal` | Open the billing portal | `account:manage` |

### Console sign-in and sessions

Cookie-based endpoints of the web console (`app.task.cloud`); API keys get `403` on the session-only ones.

| Method | Path | Summary | Auth |
| --- | --- | --- | --- |
| `POST` | `/auth/magic-link` | E-mail a sign-in link | none |
| `POST` | `/auth/magic-link/verify` | Sign in with a magic-link token | none |
| `GET` | `/auth/github/start` | Start GitHub sign-in | none |
| `GET` | `/auth/github/callback` | GitHub sign-in callback | none |
| `POST` | `/auth/logout` | Sign out | session |
| `GET` | `/me` | Get the signed-in user | session |
| `PATCH` | `/me` | Update the profile | session |
| `POST` | `/me/switch-org` | Switch the session's organization | session |
| `GET` | `/me/sessions` | List my active sessions | session |
| `DELETE` | `/me/sessions/{session_id}` | Revoke one of my sessions | session |
| `POST` | `/organizations` | Create a team organization | session |
| `POST` | `/invitations/accept` | Accept an invitation | session |

## Outgoing webhooks

Events `sandbox.ready`, `sandbox.paused`, `sandbox.resumed`, `sandbox.error`, `sandbox.deleted`, `usage.threshold` (and `webhook.test`) are `POST`ed to your endpoints, signed with HMAC-SHA256 in `Webhook-Signature`. Defined under `webhooks` in the spec; see [Webhooks](https://task.cloud/docs/guides/webhooks.md).


---

<!-- source: https://task.cloud/docs/sdk/typescript.md -->

# TypeScript SDK

`@taskcloud/sdk` is written by hand against the [OpenAPI spec](https://task.cloud/docs/api-reference.md): request and response types mirror the spec's schemas, with a thin layer on top for sandbox handles, streaming, retries and webhook verification. It has no runtime dependencies and runs on Node.js 20+, Bun, Deno and edge runtimes with `fetch`.

**Runtime notes:**

- `files.upload(...)` with `File` objects needs a global `File` (Node.js 20+, Bun, Deno, browsers).
- `pty.connect()` needs a global `WebSocket` (Node.js 22+, Bun, Deno, browsers). On Node.js 20, install [`ws`](https://www.npmjs.com/package/ws) and pass it in (see [PTY](#pty)).
- `verifyWebhook` uses `node:crypto` (Node.js, Bun, Deno). On edge runtimes use the async `verifyWebhookAsync` (Web Crypto).

```bash
npm install @taskcloud/sdk
```

## Client

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

const client = new Client({
  apiKey: process.env.TASKCLOUD_API_KEY, // default: this env var
  baseUrl: "https://api.task.cloud/v1",       // default
  maxRetries: 2,                               // retries errors with retryable: true
  timeoutMs: 120_000,
});
```

**Naming:** methods are camelCase; request and response fields are **snake_case, exactly as in the API** (`auto_pause`, `timeout_seconds`, `exit_code`).

## Sandboxes

```ts
const sandbox = await client.sandboxes.create({
  template: "base",                 // or snapshot_id, or image: { ref: "ghcr.io/acme/env:1" }
  size: "default",                  // small | default | large
  name: "user-42",
  labels: { user: "42" },
  env: { NODE_ENV: "production" },
  auto_pause: { enabled: true, idle_timeout_seconds: 300 },
  always_on: false,
  priority: "standard",             // or "batch" (−50%, may queue)
  ttl_seconds: null,
  ports: [{ port: 3000, visibility: "private" }],
  wait: true,
}, { idempotencyKey: "user-42-create" });

sandbox.id;      // "sbx_..."
sandbox.state;   // "running"

const same = await client.sandboxes.get(sandbox.id);
for await (const s of client.sandboxes.list({ state: ["running"], label: ["user=42"] })) {
  console.log(s.id, s.state);
}

await sandbox.update({ auto_pause: { enabled: true, idle_timeout_seconds: 900 } });
await sandbox.update({ always_on: true });
await sandbox.pause();                 // waits until "paused"
await sandbox.resume();                // usually unnecessary: calls wake it
const fork = await sandbox.fork({ name: "user-42-try-2" });
const forks = await sandbox.fork({ count: 10 });   // Sandbox[]: 10 copies in one call
await sandbox.refresh();               // re-read state
await sandbox.waitFor("running", { timeoutMs: 30_000 });
await sandbox.delete();
```

| Method | Endpoint |
| --- | --- |
| `client.sandboxes.create(params, opts?)` | `POST /sandboxes` |
| `client.sandboxes.get(id)` | `GET /sandboxes/{id}` |
| `client.sandboxes.list(params?)` | `GET /sandboxes` (auto-paginates) |
| `sandbox.update(params)` | `PATCH /sandboxes/{id}` |
| `sandbox.pause()` / `sandbox.resume()` | `POST /sandboxes/{id}/pause` / `resume` |
| `sandbox.fork(params?)` | `POST /sandboxes/{id}/fork` |
| `sandbox.forkMany(count, params?)` | `POST /sandboxes/{id}/fork` with `count`, always returns `Sandbox[]` |
| `sandbox.delete()` | `DELETE /sandboxes/{id}` |

### Bulk fork

`fork({ count })` creates up to 50 copies of a sandbox (memory included) in one call. `fork()` and `fork({ count: 1 })` return one `Sandbox`, as before; with `count > 1` the API returns `{ "data": [...] }` and the SDK returns `Sandbox[]`. With a literal `count` (for example `{ count: 10 }`) the return type is `Sandbox[]`; when `count` is a `number` variable it is `Sandbox | Sandbox[]`, so use `forkMany(count)` to always get an array.

Admission is all-or-nothing: if the source host cannot fit every fork, nothing is created and the call throws `ApiError` with `capacity_unavailable` (or `concurrency_limit_reached` if the plan's limit would be exceeded). With `priority: "batch"` the forks are queued instead and come back in state `queued`.

```ts
const rollouts = await sandbox.forkMany(32, { labels: { run: "eval-7" } });
const results = await Promise.all(rollouts.map((s) => s.exec({ command: "python3 rollout.py" })));

const queued = await sandbox.forkMany(50, { priority: "batch", wait: false }); // -50%, may queue
```

## Exec

```ts
// Sync
const r = await sandbox.exec({ command: "npm test", cwd: "/home/user/app", timeout_seconds: 300 });
console.log(r.exit_code, r.stdout, r.stderr, r.truncated);

// Without a shell
await sandbox.exec({ args: ["python3", "-c", "print(42)"] });

// Stream (SSE)
for await (const ev of sandbox.execStream({ command: "pip install -r requirements.txt" })) {
  if (ev.type === "stdout" || ev.type === "stderr") process.stdout.write(ev.data);
  if (ev.type === "exit") console.log("exit", ev.exit_code);
}

// Background
const cmd = await sandbox.exec({ command: "npm run dev", background: true });
for await (const ev of cmd.stream()) { /* attach, replays earlier output */ }
await cmd.writeStdin("q\n", { eof: true });
await cmd.kill({ signal: "SIGTERM" });
const done = await cmd.wait();        // Command with exit_code

await sandbox.commands.list();
await sandbox.commands.get(cmd.id);
```

### PTY

```ts
const term = await sandbox.pty.connect({
  cols: 120, rows: 40,
  onData: (bytes) => process.stdout.write(bytes),
  onExit: (code) => console.log("exit", code),
});
term.write("ls -la\n");
term.resize(160, 48);
term.close();
```

On Node.js 20, pass a WebSocket implementation: `import WebSocket from "ws"` and add `WebSocket` to the `pty.connect({ ... })` options.

`sandbox.pty.create()` returns the raw `{ id, websocket_url, expires_at }` if you want to connect from a browser (for example with xterm.js). Protocol: see [Exec and files](https://task.cloud/docs/guides/exec-and-files.md).

## Files

```ts
await sandbox.files.write("/home/user/app/.env", "PORT=3000\n", { mode: "0600" });
const text = await sandbox.files.readText("/home/user/app/package.json");
const bytes = await sandbox.files.read("/home/user/out.png");     // Uint8Array
const entries = await sandbox.files.list("/home/user/app", { recursive: false });
const info = await sandbox.files.stat("/home/user/app");
await sandbox.files.mkdir("/home/user/data");
await sandbox.files.move("/home/user/a.txt", "/home/user/b.txt");
await sandbox.files.remove("/home/user/tmp", { recursive: true });
await sandbox.files.upload("/home/user/app", [new File(["hi"], "src/hello.txt")]);
const tgz = await sandbox.files.downloadArchive("/home/user/app", { format: "tar.gz" });
const { url } = await sandbox.files.downloadUrl({ path: "/home/user/big.bin" });
const up = await sandbox.files.uploadUrl({ path: "/home/user/dataset.parquet", expires_in_seconds: 900 });

for await (const ev of sandbox.files.watch("/home/user/app/src", { recursive: true })) {
  console.log(ev.type, ev.path);
}
```

## Networking

```ts
const port = await sandbox.ports.expose({ port: 3000, visibility: "private" });
port.url; // https://<short_id>-3000.taskhost.cloud
const { token } = await sandbox.accessTokens.create({ ttl_seconds: 3600, ports: [3000] });
await sandbox.ports.list();
await sandbox.ports.remove(3000);

const ssh = await sandbox.ssh({ public_key: "ssh-ed25519 AAAA...", ttl_seconds: 3600 });
ssh.command; // ssh sbx_...@ssh.taskhost.cloud
```

## Desktop

```ts
const stream = await sandbox.desktop.stream({ ttl_seconds: 600, read_only: true });
stream.url;                                   // embed in an <iframe>
await sandbox.desktop.revoke(stream.id);

const shot = await sandbox.desktop.screenshot({ format: "png" }); // { data (base64), media_type, width, height, ... }
await sandbox.desktop.input({
  actions: [
    { action: "left_click", coordinate: [640, 412] },
    { action: "type", text: "hello" },
    { action: "key", text: "Return" },
  ],
  return_screenshot: true,
});
const { x, y } = await sandbox.desktop.cursor();
```

See [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md) for a full agent loop.

## Snapshots and templates

```ts
const snap = await sandbox.snapshots.create({ name: "after-npm-install" });
const copy = await client.sandboxes.create({ snapshot_id: snap.id });
await client.snapshots.list({ sandbox_id: sandbox.id });
await client.snapshots.delete(snap.id);

const tpl = await client.templates.create({
  name: "agent-env",
  image: { ref: "ghcr.io/acme/agent-env:1.4" },
  ready_check: { command: "curl -sf localhost:8080/health", timeout_seconds: 120 },
});
await client.templates.logs(tpl.id);
await client.sandboxes.create({ template: "agent-env" });
```

## Webhooks, usage, keys, account

```ts
const hook = await client.webhooks.create({
  url: "https://example.com/hooks/taskcloud",
  events: ["sandbox.ready", "sandbox.paused", "sandbox.resumed", "sandbox.error", "sandbox.deleted"],
});
hook.secret; // whsec_... (shown once)

import { verifyWebhook, verifyWebhookAsync } from "@taskcloud/sdk/webhooks";
const event = verifyWebhook({ payload: rawBody, headers: req.headers, secret: process.env.WEBHOOK_SECRET! });
// Edge runtimes (Cloudflare Workers, Vercel Edge): Web Crypto is async-only
const edgeEvent = await verifyWebhookAsync({ payload: rawBody, headers: req.headers, secret: env.WEBHOOK_SECRET });

const usage = await client.usage.get({ group_by: "sandbox" });
const limits = await client.limits.get();
const key = await client.apiKeys.create({ name: "user-42", preset: "full-sandbox", restrict: { labels: { user: "42" } } });
await client.account.setSpendLimit({ monthly_limit_usd: 500, on_limit: "pause_running" });
```

## Errors

Every API error becomes an `ApiError`:

```ts
import { ApiError } from "@taskcloud/sdk";

try {
  await client.sandboxes.create({ size: "large" });
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.status, err.code, err.retryable, err.requestId, err.details);
    if (err.code === "concurrency_limit_reached") { /* pause something first */ }
  } else throw err;
}
```

Errors with `retryable: true` (`rate_limited`, `capacity_unavailable`, `sandbox_busy`, ...) are retried automatically up to `maxRetries`, honouring `Retry-After`.


---

<!-- source: https://task.cloud/docs/sdk/python.md -->

# Python SDK

The `taskcloud` package is written by hand against the [OpenAPI spec](https://task.cloud/docs/api-reference.md) (fields and paths follow the spec exactly), with sandbox handles, streaming, retries and webhook verification on top. Python 3.9+, one dependency (`httpx`). Sync (`Client`) and async (`AsyncClient`) clients share the same methods.

```bash
pip install taskcloud            # core
pip install "taskcloud[pty]"     # adds websockets for sandbox.pty.connect()
```

## Client

```python
import os
from taskcloud import Client

client = Client(
    api_key=os.environ["TASKCLOUD_API_KEY"],  # default: this env var
    base_url="https://api.task.cloud/v1",          # default
    max_retries=2,                                 # retries errors with retryable=True
    timeout=120.0,                                 # seconds
)
```

Fields use the API's **snake_case names** (`auto_pause`, `timeout_seconds`, `exit_code`). Responses are typed objects with attributes (`result.exit_code`) and `.to_dict()`.

## Sandboxes

```python
sandbox = client.sandboxes.create(
    template="base",                      # or snapshot_id=..., or image={"ref": "ghcr.io/acme/env:1"}
    size="default",                       # small | default | large
    name="user-42",
    labels={"user": "42"},
    env={"NODE_ENV": "production"},
    auto_pause={"enabled": True, "idle_timeout_seconds": 300},
    always_on=False,
    priority="standard",                  # or "batch" (−50%, may queue)
    ports=[{"port": 3000, "visibility": "private"}],
    wait=True,
    idempotency_key="user-42-create",
)
print(sandbox.id, sandbox.state)

same = client.sandboxes.get(sandbox.id)
for s in client.sandboxes.list(state=["running"], label=["user=42"]):   # auto-paginates
    print(s.id, s.state)

sandbox.update(auto_pause={"enabled": True, "idle_timeout_seconds": 900})
sandbox.update(always_on=True)
sandbox.pause()
sandbox.resume()                      # usually unnecessary: calls wake it
fork = sandbox.fork(name="user-42-try-2")
forks = sandbox.fork(count=10)        # list of 10 Sandbox objects
sandbox.refresh()
sandbox.wait_for("running", timeout=30)
sandbox.delete()
```

### Bulk fork

`fork(count=N)` creates up to 50 copies of a sandbox (memory included) in one call. Without `count`, or with `count=1`, it returns one `Sandbox`, as before. With `count > 1` the API returns `{"data": [...]}` and the SDK returns a `list` of `Sandbox`. `fork_many(count, ...)` always returns a list. `AsyncClient` has the same methods (`await sandbox.fork(count=N)`).

Admission is all-or-nothing: if the source host cannot fit every fork, nothing is created and the call raises `ApiError` with `capacity_unavailable` (or `concurrency_limit_reached` if the plan's limit would be exceeded). With `priority="batch"` the forks are queued instead and come back in state `queued`.

```python
rollouts = sandbox.fork_many(32, labels={"run": "eval-7"})
results = [s.exec(command="python3 rollout.py") for s in rollouts]

queued = sandbox.fork(count=50, priority="batch", wait=False)   # -50%, may queue
```

## Exec

```python
r = sandbox.exec(command="pytest -q", cwd="/home/user/app", timeout_seconds=300)
print(r.exit_code, r.stdout, r.stderr, r.truncated)

sandbox.exec(args=["python3", "-c", "print(42)"])     # no shell

for ev in sandbox.exec_stream(command="pip install -r requirements.txt"):
    if ev.type in ("stdout", "stderr"):
        print(ev.data, end="")
    elif ev.type == "exit":
        print("exit", ev.exit_code)

cmd = sandbox.exec(command="python3 -m http.server 8080", background=True)
for ev in cmd.stream():          # attach; replays earlier output
    ...
cmd.write_stdin("q\n", eof=True)
cmd.kill(signal="SIGTERM")
done = cmd.wait()

sandbox.commands.list()
sandbox.commands.get(cmd.id)
```

### PTY

`pty.connect()` needs the `pty` extra (`pip install "taskcloud[pty]"`) and is available on the sync `Client` only. `AsyncClient` supports `pty.create()`, which returns the `websocket_url` for your own WebSocket client.

```python
with sandbox.pty.connect(cols=120, rows=40) as term:
    term.write(b"ls -la\n")
    print(term.read(timeout=1.0).decode())
    term.resize(160, 48)
```

## Files

```python
sandbox.files.write("/home/user/app/.env", "PORT=3000\n", mode="0600")
text = sandbox.files.read_text("/home/user/app/package.json")
data = sandbox.files.read("/home/user/out.png")            # bytes
entries = sandbox.files.list("/home/user/app", recursive=False)
info = sandbox.files.stat("/home/user/app")
sandbox.files.mkdir("/home/user/data")
sandbox.files.move("/home/user/a.txt", "/home/user/b.txt")
sandbox.files.remove("/home/user/tmp", recursive=True)
sandbox.files.upload("/home/user/app", {"src/hello.txt": b"hi"})
archive = sandbox.files.download_archive("/home/user/app", format="tar.gz")
url = sandbox.files.download_url(path="/home/user/big.bin").url
up = sandbox.files.upload_url(path="/home/user/dataset.parquet", expires_in_seconds=900)

for ev in sandbox.files.watch("/home/user/app/src", recursive=True):
    print(ev.type, ev.path)
```

## Networking

```python
port = sandbox.ports.expose(port=3000, visibility="private")
print(port.url)                         # https://<short_id>-3000.taskhost.cloud
token = sandbox.access_tokens.create(ttl_seconds=3600, ports=[3000]).token
sandbox.ports.list()
sandbox.ports.remove(3000)

ssh = sandbox.ssh(public_key="ssh-ed25519 AAAA...", ttl_seconds=3600)
print(ssh.command)
```

## Desktop

```python
stream = sandbox.desktop.stream(ttl_seconds=600, read_only=True)
print(stream.url)
sandbox.desktop.revoke(stream.id)

shot = sandbox.desktop.screenshot(format="png")    # .data (base64), .media_type, .width, .height
sandbox.desktop.input(
    actions=[
        {"action": "left_click", "coordinate": [640, 412]},
        {"action": "type", "text": "hello"},
        {"action": "key", "text": "Return"},
    ],
    return_screenshot=True,
)
pos = sandbox.desktop.cursor()   # .x, .y
```

Full agent loop: [Desktop and computer use](https://task.cloud/docs/guides/desktop-and-computer-use.md).

## Snapshots and templates

```python
snap = sandbox.snapshots.create(name="after-pip-install")
copy = client.sandboxes.create(snapshot_id=snap.id)
client.snapshots.list(sandbox_id=sandbox.id)
client.snapshots.delete(snap.id)

tpl = client.templates.create(
    name="agent-env",
    image={"ref": "ghcr.io/acme/agent-env:1.4"},
    ready_check={"command": "curl -sf localhost:8080/health", "timeout_seconds": 120},
)
print(client.templates.logs(tpl.id))
client.sandboxes.create(template="agent-env")
```

## Webhooks, usage, keys, account

```python
hook = client.webhooks.create(
    url="https://example.com/hooks/taskcloud",
    events=["sandbox.ready", "sandbox.paused", "sandbox.resumed", "sandbox.error", "sandbox.deleted"],
)
print(hook.secret)   # whsec_... (shown once)

from taskcloud.webhooks import verify_webhook
event = verify_webhook(payload=raw_body, headers=request.headers, secret=os.environ["WEBHOOK_SECRET"])

usage = client.usage.get(group_by="sandbox", from_="2026-11-01T00:00:00Z")   # `from` is a Python keyword: use from_=
limits = client.limits.get()
key = client.api_keys.create(name="user-42", preset="full-sandbox", restrict={"labels": {"user": "42"}})
client.account.set_spend_limit(monthly_limit_usd=500, on_limit="pause_running")
```

## Async

```python
import asyncio
from taskcloud import AsyncClient

async def main():
    client = AsyncClient()
    sandboxes = await asyncio.gather(*[client.sandboxes.create(template="base", priority="batch") for _ in range(20)])
    results = await asyncio.gather(*[s.exec(command="python3 eval.py") for s in sandboxes])
    await asyncio.gather(*[s.delete() for s in sandboxes])

asyncio.run(main())
```

Batch sandboxes may wait in `queued`; `create` with `priority="batch"` returns immediately, and `exec` waits for the sandbox to start.

## Errors

```python
from taskcloud import ApiError

try:
    client.sandboxes.create(size="large")
except ApiError as e:
    print(e.status, e.code, e.retryable, e.request_id, e.details)
```

Errors with `retryable=True` are retried automatically up to `max_retries`, honouring `Retry-After`.


---

<!-- source: https://task.cloud/docs/cli.md -->

# CLI

The `taskcloud` CLI is a thin layer over the [REST API](https://task.cloud/docs/api-reference.md). Everything it does, you can do with the API.

## Install and log in

### Install script

Available once the first CLI release is tagged. The script installs a prebuilt binary for Linux or macOS (amd64 or arm64); run `curl -fsSL https://task.cloud/install.sh | sh` in a terminal.

It detects your OS and architecture, downloads the matching archive from the project's GitHub Releases, verifies its SHA-256 against the release's `checksums.txt` and installs `taskcloud` to `~/.local/bin` (or `/usr/local/bin` when run as root). Optional environment variables:

| Variable | Effect |
| --- | --- |
| `TASKCLOUD_VERSION` | Install a specific version, e.g. `TASKCLOUD_VERSION=0.2.0`. Default: the latest stable release. |
| `TASKCLOUD_INSTALL_DIR` | Install somewhere else, e.g. `TASKCLOUD_INSTALL_DIR=$HOME/bin`. |

Each release also ships a signed checksum file and SBOMs; the release notes list the `cosign` and `gh attestation verify` commands.

### Build from source

Until the first release, and during the private beta, the CLI is built from source (Go 1.27.3+, standard library only); beta participants get access to the source repository:

```bash
cd cli && go build -o taskcloud . && sudo mv taskcloud /usr/local/bin/
```

### Log in

```bash
taskcloud login                              # prompts for an API key (opens the dashboard to create one)
taskcloud login --key-stdin < key.txt        # non-interactive (CI)
taskcloud whoami
```

**Coming soon:** an npm wrapper (`npm install -g @taskcloud/cli`) and browser-based login. Until then, `taskcloud login` asks you to paste a key created in the dashboard.

Credentials are stored in `~/.config/taskcloud/config.json`. The `TASKCLOUD_API_KEY` environment variable takes precedence.

**Global flags:** `--json` (machine-readable output; on automatically when stdout is not a TTY), `--api-key <key>`, `--api-url <url>`, `--quiet`.

## Cheat sheet

```bash
taskcloud create --template base --size default --name dev   # prints the sandbox ID
taskcloud list                                               # your sandboxes (deleted ones hidden)
taskcloud exec <id> -- npm test                              # exit code = command's exit code
taskcloud shell <id>                                         # PTY session: prints its WebSocket URL
taskcloud ssh <id>                                           # SSH through the gateway
taskcloud cp ./app <id>:/home/user/app -r                    # upload a directory
taskcloud port expose <id> 3000 --public                     # https://<short_id>-3000.taskhost.cloud
taskcloud pause <id>                                         # $0 compute while paused
taskcloud fork <id> --name dev-copy                          # copy with memory
taskcloud fork <id> --count 5 -q                             # 5 copies, all or nothing; prints 5 IDs
taskcloud desktop <id> --ttl 10m --read-only --open          # open the desktop in a browser
taskcloud screenshot <id> -o screen.png
taskcloud input <id> '[{"action":"left_click","coordinate":[640,412]}]' -o after.png
taskcloud delete <id> --yes
```

## Commands

### Sandboxes

| Command | Description | API |
| --- | --- | --- |
| `create [flags]` | Create a sandbox. Flags: `--template <name>`, `--snapshot <snap_id>`, `--image <ref>`, `--size small\|default\|large`, `--name`, `--label k=v` (repeatable), `--env K=V` (repeatable), `--idle-timeout 5m`, `--no-auto-pause`, `--always-on`, `--batch`, `--region auto\|eu-de\|eu-fi`, `--ttl 2h`, `--disk 100`, `--port 3000[:public]` (repeatable), `--no-wait` | `POST /sandboxes` |
| `list [--state s] [--label k=v] [--all]` | List sandboxes. Sandboxes in state `deleted` are hidden unless you pass `--all` or `--state deleted`; `--all` shows them only if the API still returns them. A guaranteed "recently deleted" view is coming soon. | `GET /sandboxes` |
| `get <id>` | Show a sandbox | `GET /sandboxes/{id}` |
| `update <id> [flags]` | `--name`, `--label k=v`, `--idle-timeout 15m`, `--no-auto-pause`, `--always-on`, `--no-always-on`, `--ttl` | `PATCH /sandboxes/{id}` |
| `pause <id>` | Pause (RAM + disk snapshot) | `POST /sandboxes/{id}/pause` |
| `resume <id>` | Resume | `POST /sandboxes/{id}/resume` |
| `fork <id> [--count N] [--name] [--label]` | Fork with memory. `--count` (`-n`) 1–50 creates N forks in one call, all or nothing; prints a table (`-q`: one ID per line, `--json`: array of sandboxes) | `POST /sandboxes/{id}/fork` |
| `delete <id> [--yes]` | Delete permanently | `DELETE /sandboxes/{id}` |

### Exec and terminals

| Command | Description | API |
| --- | --- | --- |
| `exec <id> [--cwd] [--env K=V] [--user] [--timeout 300] [--background] -- <cmd...>` | Run a command; streams output; exits with its exit code. `--background` prints the command ID. | `POST /sandboxes/{id}/exec` |
| `commands list <id>` | Recent commands | `GET /sandboxes/{id}/commands` |
| `commands logs <id> <cmd_id> [--follow]` | Output of a command: replays earlier output, then follows until the command exits (the API has one replay-and-follow stream, so `--follow` currently changes nothing). Alias: `taskcloud logs`. | `GET .../commands/{cmd_id}/stream` |
| `commands kill <id> <cmd_id> [--signal SIGKILL]` | Signal a command | `POST .../commands/{cmd_id}/kill` |
| `shell <id> [--user] [--cwd]` | Creates a PTY session and prints its `websocket_url` (valid 60 s until first connect). A built-in interactive terminal is coming soon; use `taskcloud ssh` meanwhile. | `POST /sandboxes/{id}/pty` |
| `ssh <id> [--key file.pub] [--ttl 1h] [--user u] [--print] [-- ssh args]` | SSH via `ssh.taskhost.cloud`. Sends your local public key (default `~/.ssh/id_ed25519.pub`, `id_ecdsa.pub` or `id_rsa.pub`) as a temporary key for this sandbox; nothing is stored on your account. `--print` only prints the command. | `POST /sandboxes/{id}/ssh` |

### Files

| Command | Description | API |
| --- | --- | --- |
| `cp <src> <dst> [-r]` | Copy local ↔ sandbox. Sandbox paths are `<id>:/path`. | `/files/upload`, `/files/content`, `/files/download` |
| `files ls <id> <path> [-R]` | List | `GET /sandboxes/{id}/files` |
| `files cat <id> <path>` | Print a file | `GET .../files/content` |
| `files rm <id> <path> [-r]` | Delete | `DELETE /sandboxes/{id}/files` |
| `files watch <id> <path>` | Print change events | `GET .../files/watch` |

### Networking and desktop

| Command | Description | API |
| --- | --- | --- |
| `port expose <id> <port> [--public]` | Public HTTPS URL | `POST /sandboxes/{id}/ports` |
| `port ls <id>` / `port rm <id> <port>` | List / remove | `GET`, `DELETE .../ports` |
| `token create <id> [--ttl 1h] [--port 3000]` | Access token for private ports | `POST .../access-tokens` |
| `ssh-key add <file.pub>` / `ssh-key ls` / `ssh-key rm <id>` | Account SSH keys | `/ssh-keys` |
| `desktop <id> [--ttl 10m] [--read-only] [--single-use] [--open]` | Desktop stream URL | `POST /sandboxes/{id}/desktop` |
| `screenshot <id> [-o shot.png] [--scale 0.5] [--format png\|jpeg] [--region x0,y0,x1,y1]` | Save a screenshot | `GET .../screenshot` |
| `input <id> '<actions JSON>' [-o after.png] [--coordinate-scale 0.5]` | Send mouse and keyboard actions: a JSON array of [input actions](https://task.cloud/docs/guides/desktop-and-computer-use.md) (a single object also works; `-` reads stdin). `-o` saves a screenshot taken after the last action. | `POST .../input` |

### Snapshots and templates

| Command | Description | API |
| --- | --- | --- |
| `snapshot create <id> [--name] [--no-memory]` | Named snapshot | `POST /sandboxes/{id}/snapshots` |
| `snapshot ls [--sandbox <id>]` / `snapshot rm <snap_id>` | List / delete | `/snapshots` |
| `template create --name <n> (--image <ref> \| --snapshot <snap_id>) [--start-command] [--ready-check <cmd>] [--desktop]` | Create a template | `POST /templates` |
| `template ls` / `template logs <name> [--follow]` / `template rm <name>` | Manage templates | `/templates` |

### Account

| Command | Description | API |
| --- | --- | --- |
| `key create --name <n> (--preset ci \| --scope exec ...) [--label k=v] [--sandbox <id>] [--expires 30d]` | Create an API key | `POST /api-keys` |
| `key ls` / `key rotate <id>` / `key revoke <id>` | Manage keys | `/api-keys` |
| `webhook create --url <url> --event sandbox.ready [--event ...]` | Create a webhook | `POST /webhooks` |
| `webhook ls` / `rm` / `rotate` / `test` | Manage webhooks | `/webhooks` |
| `usage [--group-by none\|sandbox\|day\|size\|label\|template] [--label-key customer] [--from] [--to]` | Usage and cost | `GET /usage` |
| `limits` | Plan, concurrency, rate limits | `GET /limits` |
| `spend-limit set <usd> [--on-limit pause_running\|block_new]` / `spend-limit clear` | Spend limit | `PUT /account/spend-limit` |
| `mcp [--read-only] [--tools a,b]` | Run the local MCP server on stdio (starts `npx -y @taskcloud/mcp`; needs Node.js and the published `@taskcloud/mcp` package, coming soon to npm) | see [MCP](https://task.cloud/docs/mcp.md) |

## CI example

```bash
taskcloud login --key-stdin <<< "$SANDBOX_API_KEY"
id=$(taskcloud create --template base --size large --batch --ttl 1h --json | jq -r .id)
trap 'taskcloud delete "$id" --yes' EXIT
taskcloud cp . "$id":/home/user/repo -r
taskcloud exec "$id" --cwd /home/user/repo --timeout 600 -- npm ci '&&' npm test
```

`--batch` halves the compute price; the sandbox may wait briefly in `queued`, and `exec` waits for it to start.


---

<!-- source: https://task.cloud/docs/mcp.md -->

# MCP server

`TaskCloud` provides a [Model Context Protocol](https://modelcontextprotocol.io) server. With it, an agent such as Claude Code, Claude Desktop, Cursor or Codex can create sandboxes, run commands, edit files, expose ports and drive a desktop, with no glue code.

| Mode | How | Auth |
| --- | --- | --- |
| **Local** (stdio) | `npx -y @taskcloud/mcp` or `taskcloud mcp` | env `TASKCLOUD_API_KEY` (optional `TASKCLOUD_API_URL`) |
| **Self-hosted** (Streamable HTTP) | `npx -y @taskcloud/mcp --http --port 8787`, or the Docker image | `Authorization: Bearer <api key>` on every request |
| **Hosted** (Streamable HTTP), *beta, coming soon* | `https://mcp.task.cloud/mcp` | `Authorization: Bearer <api key>` on every request |

Every mode calls the public [REST API](https://task.cloud/docs/api-reference.md), so each tool call is subject to the scopes of the API key you use. The hosted endpoint runs the same server as the self-hosted HTTP mode; it is not live yet. During the private beta `@taskcloud/mcp` is shared with beta participants directly; publication on npm is coming soon.

## Use a restricted key

Don't give an agent your admin key. Create a key limited to sandbox work and, optionally, to sandboxes with a given label:

```bash
curl -X POST https://api.task.cloud/v1/api-keys \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mcp-agent", "preset": "full-sandbox", "restrict": {"labels": {"owner": "mcp"}}, "expires_in_days": 30}'
```

Sandboxes created with this key automatically receive the label `owner=mcp`, and the key can only see and act on sandboxes with that label.

## Setup

### Claude Code

Local (stdio):

```bash
claude mcp add taskcloud --env TASKCLOUD_API_KEY=$TASKCLOUD_API_KEY -- npx -y @taskcloud/mcp
```

Remote (Streamable HTTP), against your own server or, once it is live, the hosted endpoint:

```bash
claude mcp add --transport http taskcloud http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $TASKCLOUD_API_KEY"

# hosted (beta, coming soon)
claude mcp add --transport http taskcloud https://mcp.task.cloud/mcp \
  --header "Authorization: Bearer $TASKCLOUD_API_KEY"
```

### Claude Desktop / Cursor

Add the local server to the client's MCP configuration (`claude_desktop_config.json`, or `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "taskcloud": {
      "command": "npx",
      "args": ["-y", "@taskcloud/mcp"],
      "env": { "TASKCLOUD_API_KEY": "taskcloud_sk_..." }
    }
  }
}
```

Cursor can also connect to an HTTP server with a static header:

```json
{
  "mcpServers": {
    "taskcloud": {
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer taskcloud_sk_..." }
    }
  }
}
```

Claude Desktop's remote connectors sign in with OAuth, which the HTTP mode does not support yet (see [Authentication](#authentication)). Use the local server there for now.

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "taskcloud": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer ${input:taskcloud-key}" }
    }
  },
  "inputs": [{ "id": "taskcloud-key", "type": "promptString", "description": "TaskCloud API key", "password": true }]
}
```

### Codex and other clients

Codex (`~/.codex/config.toml`) reads the key from an environment variable:

```toml
[mcp_servers.taskcloud]
url = "http://127.0.0.1:8787/mcp"
bearer_token_env_var = "TASKCLOUD_API_KEY"
```

Any other MCP client works if it supports either stdio (run `npx -y @taskcloud/mcp` with `TASKCLOUD_API_KEY` in its environment) or Streamable HTTP with a custom `Authorization` header.

## Self-hosting the HTTP server

```bash
npx -y @taskcloud/mcp --http --port 8787                       # listens on 127.0.0.1:8787, endpoint /mcp
npx -y @taskcloud/mcp --http --host 0.0.0.0 --read-only        # all interfaces, read-only tools
```

The server has no API key of its own. Each MCP request must send `Authorization: Bearer <api key>`, and the tools of that request call the API with that key only. `TASKCLOUD_API_KEY` in the server's environment is ignored in this mode, so two users of one server never share a key. The server only checks that the header is present. The API decides whether the key is valid, so a revoked key gets tool results with `isError: true` and `401 unauthorized`.

### Docker

The image is built from the SDK sources (build context `sdks/`):

```bash
docker build -f sdks/mcp/Dockerfile -t taskcloud-mcp sdks
docker run --rm -p 8787:8787 taskcloud-mcp                     # add flags after the image name, e.g. --read-only
```

The container listens on `0.0.0.0:8787`, runs as a non-root user and has a `HEALTHCHECK` on `/healthz`. Because it binds to all interfaces, the `Host` check is off unless you pass `--allowed-hosts` (or `TASKCLOUD_MCP_ALLOWED_HOSTS`) with the host name clients use. Put it behind a reverse proxy that terminates TLS, because API keys travel in a header.

### Configuration

| Flag | Environment | Default | Meaning |
| --- | --- | --- | --- |
| `--http` | | off (stdio) | Serve MCP over Streamable HTTP |
| `--port N` | `PORT` | `8787` | Listen port (`0` picks a free port) |
| `--host H` | `HOST` | `127.0.0.1` (`0.0.0.0` in Docker) | Bind address |
| `--read-only` | | off | Only the 5 read-only tools |
| `--tools a,b` | | all 15 | Tool allowlist |
| `--max-body-bytes N` | | `1048576` | Larger request bodies get `413` |
| `--request-timeout S` | | `660` | Deadline for one MCP request, in seconds; a request over it gets `504` (`exec` waits up to 600 s) |
| `--allowed-origins a,b` | `TASKCLOUD_MCP_ALLOWED_ORIGINS` | none | Browser origins that may call `/mcp`; a request with any other `Origin` header gets `403` |
| `--allowed-hosts a,b` | `TASKCLOUD_MCP_ALLOWED_HOSTS` | `localhost`, `127.0.0.1`, `[::1]` when bound to loopback; no check otherwise | `Host` header values the server answers (DNS rebinding protection); any other `Host` gets `403`. Set it to your public host name when you bind to `0.0.0.0` (Docker) |
| | `TASKCLOUD_API_URL` | `https://api.task.cloud/v1` | API base URL |

### Endpoints and behavior

- `POST /mcp`: MCP messages (Streamable HTTP, protocol versions up to the current spec). The server is **stateless**: it issues no `Mcp-Session-Id`, every request is handled independently, and replicas behind a load balancer need no sticky sessions. Responses are plain JSON, not SSE streams.
- `GET /mcp` and `DELETE /mcp` return `405`, because a stateless server has no server-initiated stream and no session to end. Clients handle this per the spec.
- `GET /healthz`: `{"status":"ok", ...}` for liveness and readiness probes.
- Per-request narrowing: `/mcp?read_only=1` and `/mcp?tools=exec,read_file` shrink the tool list for that connection. They never widen what the server-wide `--read-only` or `--tools` allows.
- Timeouts: 15 s to receive headers, 30 s to receive the whole request, then the per-request deadline above.
- Logs: one JSON object per line on stderr, with `request_id` (taken from `X-Request-Id` or generated, and echoed in the response), status, duration, JSON-RPC methods, tool names and `key_fp`, the first 12 hex characters of the key's SHA-256. API keys, tool arguments and tool output are never logged.

### Authentication

Today the only credential is a TaskCloud API key in the `Authorization` header. MCP's OAuth 2.1 flow (protected resource metadata, browser sign-in, audience-bound tokens) is planned for the hosted endpoint. It needs an authorization server on the TaskCloud side, which does not exist yet. Until then, clients that only support OAuth for remote servers should use the local stdio server.

## Tools

| Tool | Key parameters | API endpoint |
| --- | --- | --- |
| `create_sandbox` | `template`, `size`, `name`, `labels`, `auto_pause`, `always_on`, `priority` | `POST /sandboxes` |
| `list_sandboxes` | `state`, `label`, `limit`, `cursor` | `GET /sandboxes` |
| `get_sandbox` | `sandbox_id` | `GET /sandboxes/{sandbox_id}` |
| `pause_sandbox` | `sandbox_id` | `POST /sandboxes/{sandbox_id}/pause` |
| `resume_sandbox` | `sandbox_id` | `POST /sandboxes/{sandbox_id}/resume` |
| `fork_sandbox` | `sandbox_id`, `name`, `labels`, `count` (1–50, all-or-nothing; >1 returns `{"data": [...]}`), `priority` | `POST /sandboxes/{sandbox_id}/fork` |
| `delete_sandbox` | `sandbox_id` | `DELETE /sandboxes/{sandbox_id}` |
| `exec` | `sandbox_id`, `command`, `cwd`, `timeout_seconds`, `background` | `POST /sandboxes/{sandbox_id}/exec` |
| `read_file` | `sandbox_id`, `path` | `GET /sandboxes/{sandbox_id}/files/content` |
| `write_file` | `sandbox_id`, `path`, `content` | `PUT /sandboxes/{sandbox_id}/files/content` |
| `list_files` | `sandbox_id`, `path`, `recursive` | `GET /sandboxes/{sandbox_id}/files` |
| `expose_port` | `sandbox_id`, `port`, `visibility` | `POST /sandboxes/{sandbox_id}/ports` |
| `desktop_stream_url` | `sandbox_id`, `ttl_seconds`, `read_only` | `POST /sandboxes/{sandbox_id}/desktop` |
| `screenshot` | `sandbox_id`, `scale`, `region` | `GET /sandboxes/{sandbox_id}/screenshot` (returned as an MCP image) |
| `computer_input` | `sandbox_id`, `actions` (same shape as [input actions](https://task.cloud/docs/guides/desktop-and-computer-use.md#input)) | `POST /sandboxes/{sandbox_id}/input` |

Behavior notes:

- **Truncated output.** `exec` in sync mode returns `exit_code`, `stdout` and `stderr`. Output larger than what fits in a tool result is truncated, and the tool says where the full log can be read (`GET .../commands/{command_id}/stream`).
- **Text files only.** `read_file` and `write_file` handle text. For binary files, use the REST API or signed URLs.
- **Wake on request.** Tools that need a running VM wake a paused sandbox automatically.

## Limiting what the agent can do

The server accepts flags that remove tools from the list the agent sees:

```bash
npx -y @taskcloud/mcp --read-only                      # only list_sandboxes, get_sandbox, read_file, list_files, screenshot
npx -y @taskcloud/mcp --tools create_sandbox,exec,read_file,write_file,list_files,expose_port
```

For example, `--tools` without `delete_sandbox` stops the agent from deleting sandboxes. `--read-only` and `--tools` can be combined. API key scopes still apply.

The same flags work with `--http`. Over HTTP a client can also narrow its own tool list with `?read_only=1` or `?tools=a,b` in the endpoint URL, for example `https://mcp.task.cloud/mcp?tools=exec,read_file` once the hosted endpoint is live.

## Docs for agents

- A concise index of this documentation for LLMs: [`https://task.cloud/docs/llms.txt`](https://task.cloud/docs/llms.txt)
- The OpenAPI spec for generating clients: see [API reference](https://task.cloud/docs/api-reference.md)


---

<!-- source: https://task.cloud/docs/billing.md -->

# Billing and pricing

You pay per second for the time a sandbox's VM is actually running. A paused sandbox costs **$0 for compute**.

> Prices in USD, excluding VAT. Private beta pricing; we will announce any change at least 30 days in advance.

## Compute

| Size | vCPU | RAM | Disk included | Price per active hour | Per second |
| --- | --- | --- | --- | --- | --- |
| `small` | 2 | 4 GB | 20 GB | **$0.015** | $0.0000042 |
| `default` | 4 | 8 GB | 50 GB | **$0.030** | $0.0000083 |
| `large` | 8 | 16 GB | 100 GB | **$0.060** | $0.0000167 |

- Billed **per second** of VM run time, with no minimum.
- **Paused = $0 compute.** You pay only for snapshot storage (below), which is free for the first 30 days.
- The size is set by `size` on `POST /sandboxes`. A fork has the same size as its source.

### Billing per state

| State | Compute billed? | Notes |
| --- | --- | --- |
| `queued` | No | `priority: "batch"` only, waiting for capacity. |
| `creating` | No | |
| `running` | **Yes**, per second | Includes time spent in `resuming` and `pausing`. |
| `pausing`, `resuming` | Yes | Typically under a second. |
| `paused` | **No** | Snapshot storage only (free for 30 days). |
| `deleting`, `deleted` | No | Disk and pause snapshot are removed. |
| `error` | No | |

See [Lifecycle](https://task.cloud/docs/concepts/lifecycle.md) for how auto-pause and wake on request move sandboxes between states.

## Batch and off-peak: −50%

Compute is billed at **half price** when either:

- the sandbox was created (or forked) with `priority: "batch"`. Batch sandboxes may wait in the `queued` state until capacity is free, so use them for jobs that can start later (evals, CI, data processing); or
- the seconds fall into the EU night window, **22:00–07:00 CET**, for any sandbox. This applies automatically.

| Size | Batch / off-peak per hour |
| --- | --- |
| `small` | $0.0075 |
| `default` | $0.015 |
| `large` | $0.030 |

## Always-on

**$19.90 per month** for a `default` sandbox that never pauses (`always_on: true`). This flat price replaces the hourly price for that sandbox. It is prorated by day when you turn it on or off mid-period. Use it for agents that must stay running 24/7. A `default` sandbox running all month at the hourly rate would cost about $21.90 (730 h × $0.030).

```ts
await sandbox.update({ always_on: true });
```

## Storage

| Item | Price |
| --- | --- |
| Pause snapshot (RAM + disk state of a paused sandbox) | **Free for 30 days** from the snapshot, then **$0.03 per GB-month** |
| Named snapshots and templates | Same: free for 30 days, then $0.03 per GB-month |
| Disk beyond the size's included disk (`disk_gb`) | **$0.05 per GB-month** |

Stored sizes are measured after compression and deduplication (`storage_bytes` on snapshots and templates).

## Plans

| Plan | Price | Includes |
| --- | --- | --- |
| **Free** | $0 | One-time **20 hours** of `default` (no renewal), **2** concurrent sandboxes, no card required. |
| **Starter** | **$19 / month** | **$19 of usage credit every month** (about 630 hours of `default`). Usage above the credit is billed at the standard rates. **10** concurrent sandboxes. |
| **Team** | **$199 / month** | **$199 of usage credit every month**. After the credit is used, all rates are **15% lower**. **1,000+** concurrent sandboxes. Slack support. 99.9% uptime target; the SLA applies once the second location is live. |
| **Enterprise** | Custom | Annual contract, support, bring your own cloud (BYOC). |

### Monthly credit expires

**Starter and Team credit expires at the end of each monthly billing period. Unused credit does not roll over and is not refunded.** On the first day of the next period you receive a fresh credit of $19 (Starter) or $199 (Team). We email a reminder before the period ends. `GET /usage` shows `totals.credit_remaining_usd` for the current period.

### How credit and discounts combine

1. Each charge is priced first: per-second compute at the size rate, with **batch/off-peak at 50%** of that rate; Always-on at $19.90 per VM per month (prorated per day); storage after the free period.
2. **Plan credit is used first** for every charge type: compute, batch, Always-on and storage.
3. When the credit is used up, the rest is billed as overage. **Team** pays overage **15% below** the rates above, and batch gets both discounts (`rate × 0.5 × 0.85`). Starter pays overage at standard rates.
4. Seconds in `pausing` and `resuming` are billed like `running`. `queued`, `creating`, `paused` and `error` are not billed for compute.
5. Overage is charged to your card when it reaches $20, $100 and then every $500, and at the end of the period.

## Worked examples

**One coding agent, active about 2.4 hours a day** (10% of the month), `default` size, auto-pause on:

73 active hours × $0.030 = **$2.19 / month** in compute. The paused time costs nothing for 30 days of snapshot storage.

**1,000 end users, each with their own `default` sandbox, each active 10% of the time:**

1,000 × 73 h × $0.030 = **about $2,190 / month**.

**Eval run:** 500 `small` sandboxes for 1 hour with `priority: "batch"`:

500 × 1 h × $0.0075 = **$3.75**.

## Controlling spend

- **Spend limit:** `PUT /account/spend-limit` with `monthly_limit_usd`. When reached, new sandboxes are rejected with `402 spend_limit_reached`, and running sandboxes are paused (`on_limit: "pause_running"`, default) or left running (`on_limit: "block_new"`). Email alerts fire at `alert_thresholds` (default 50%, 80%, 100%), and each one also sends a `usage.threshold` webhook. Plan credit (and the Free plan's 20 hours) sends `usage.threshold` at 80% and 100% too, and an email 3 days before unused credit expires.
- **Auto-pause:** keep it on (default 300 s idle). Lower `auto_pause.idle_timeout_seconds` for bursty agents.
- **TTL:** set `ttl_seconds` to delete short-lived sandboxes automatically.
- **Per-customer cost:** label sandboxes (`labels: { customer: "acme" }`) and call `GET /usage?group_by=label&label_key=customer` to re-bill your own users.

```bash
curl -sS "https://api.task.cloud/v1/usage?group_by=label&label_key=customer" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY"
```

## FAQ

**Do I pay while a sandbox is paused?** Not for compute. The pause snapshot is stored free for 30 days, then $0.03 per GB-month.

**Does unused Starter or Team credit carry over?** No. It expires at the end of each monthly period.

**What happens when the Free plan's 20 hours run out?** New sandboxes are rejected with `402 free_hours_exhausted` and running ones are paused. Upgrade to continue. Your sandboxes and snapshots are kept.

**Is there a charge for creating or deleting sandboxes?** No. Only run time and storage are billed.

**Is network traffic billed?** Not separately during the beta. Abuse (for example mass outbound traffic) is not allowed; see [Security](https://task.cloud/docs/security.md).


---

<!-- source: https://task.cloud/docs/teams.md -->

# Teams and roles

Every TaskCloud account is an **organization**. Sandboxes, API keys, webhooks, usage and billing belong to the organization, not to a person. People sign in to the web console and act inside one organization at a time; programs use [API keys](https://task.cloud/docs/security.md).

## Sign-in

- **E-mail link:** enter your address in the console and open the link we send. It works once and expires in 15 minutes.
- **GitHub:** sign in with GitHub; we use your verified primary e-mail address, so the same person ends up in the same account either way.

Your first sign-in creates your account and a personal organization on the **Free** plan (20 h of `default` usage, once per person, 2 concurrent sandboxes, no card). Organizations you create later start on Free without the 20 h; upgrade them to Starter or Team from the console billing page.

The 20 h belong to a person, not to an address: aliases of one mailbox (for example `jane.doe+test@gmail.com` and `janedoe@gmail.com`) count once. If you sign up with a disposable e-mail domain, or many accounts were created from your network on the same day, the 20 h are **on hold** until you verify the account by adding a card (upgrading) or by signing in with a GitHub account that is more than 90 days old. New unverified accounts also have [stricter limits](https://task.cloud/docs/limits.md) for their first 7 days.

Console sessions last 30 days from your last activity and at most 90 days from sign-in; then you sign in again. You can see and sign out your other sessions in the console.

## Two-factor authentication

Turn it on in **Settings → Security**: scan the QR code with an authenticator app (any app that supports TOTP: 1Password, Google Authenticator, Authy and others), enter a code, and save the 10 **recovery codes** we show once. Each recovery code works once if you lose your phone. From then on, signing in asks for a code after the e-mail link or GitHub. Turning 2FA off, creating new recovery codes and deleting your account also need a code. We e-mail you whenever 2FA is turned on or off or new recovery codes are created.

An owner who uses 2FA can **require two-factor authentication** for the whole organization (Settings → Organization). Members without 2FA can then still sign in and open Settings to turn it on, but cannot use the organization (`403`, `details.reason = "two_factor_required"`) until they do. API keys are not affected.

## Roles

| Action | Owner | Admin | Member |
| --- | :---: | :---: | :---: |
| Create, use and delete sandboxes, snapshots, templates; exec, files, SSH, desktop | ✓ | ✓ | ✓ |
| View usage, limits, members and the billing overview | ✓ | ✓ | ✓ |
| Create API keys (never with more access than your role) | ✓ | ✓ | ✓ |
| See, rotate and revoke **other people's** API keys | ✓ | ✓ | – |
| Manage webhooks and the spend limit | ✓ | ✓ | – |
| Invite people, revoke invitations, change roles, remove members | ✓ | ✓ (not owners) | – |
| Upgrade the plan, change the card (billing portal) | ✓ | ✓ | – |
| Rename the organization | ✓ | ✓ | – |
| Grant or take away the owner role, remove an owner | ✓ | – | – |
| Delete the organization | ✓ | – | – |
| Leave the organization | ✓ (not the last owner) | ✓ | ✓ |

An organization always keeps at least one owner. A member sees only the API keys they created. A request your role does not allow returns `403` with `"code": "forbidden"` and `details.reason = "insufficient_role"`.

## Invitations

Owners and admins invite people by e-mail from the console. The link is valid for 7 days and must be accepted while signed in with the invited address. Only an owner can invite another owner.

## Automating with API keys

An API key acts with its scopes in its organization. Keys with `account:read` can list members and invitations and read the billing overview; keys with `account:manage` can invite, change roles of admins and members, remove them and start a checkout. Keys cannot grant or remove the owner role.

```bash
curl -s https://api.task.cloud/v1/members -H "Authorization: Bearer $TASKCLOUD_API_KEY"

curl -s -X POST https://api.task.cloud/v1/invitations \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"email": "grace@example.com", "role": "member"}'
```

Removing someone revokes their access to the organization at once, **including the API keys they created** (sandboxes they created stay with the organization). A person's API key never has more access than the person: if an admin becomes a member, their keys lose admin-only scopes at once, and a member's key, like the member, sees only that member's keys. Keys created by another API key are not tied to a person.

Invitation e-mails are limited to 20 per organization per hour and 3 per address per organization per day. Organization names cannot contain links or e-mail addresses.

## Deleting an organization

An owner can delete an organization in the console (Settings → Danger zone) once it has no sandboxes left, paused ones included, and no paid subscription (cancel it in the billing portal first). You cannot delete your only organization. Deleting revokes the organization's API keys and open invitations and removes it for every member. We never delete sandboxes for you as part of this step, because deleting a disk cannot be undone.

30 days after the deletion we purge the rest: named snapshots, custom templates, member and invitation data. The organization's encryption keys for stored snapshots are destroyed, so snapshot data still in storage can no longer be read. Usage records and invoices are kept for accounting.

## Your personal data and deleting your account

**Settings → Danger zone → Export my data** downloads a JSON file with your profile, organizations and roles, sessions (with IP addresses), two-factor status, invitations you sent, API keys you created (never their secrets) and the audit records about you (`GET /v1/me/export`).

**Delete account** erases your user: profile, sessions, memberships and two-factor settings. Type your e-mail address to confirm (and a 2FA code if you use it). Organizations where you are the only member are deleted with your account. You cannot delete your account while you are the only owner of an organization that has sandboxes, a paid subscription or other members: delete the sandboxes, cancel the subscription or make someone else owner first. Audit records we must keep stay, but your user ID in them is replaced by a pseudonym and their details (such as IP addresses) are removed. You can sign up again with the same address later; it will be a new, empty account.


---

<!-- source: https://task.cloud/docs/limits.md -->

# Limits

Default limits during the private beta. Contact support to raise account-level limits. Values marked *target* are service objectives, not guarantees.

## Account

| Limit | Free | Starter | Team | Enterprise |
| --- | --- | --- | --- | --- |
| Concurrent sandboxes (not `paused` or `deleted`) | 2 | 10 | 1,000+ | Custom |
| Bulk fork (`count` per call) | 2 | 10 | 50 | 100 |
| Included usage | 20 h `default`, one-time | $19 credit / month (expires) | $199 credit / month (expires) | Contract |

Paused sandboxes do not count toward the concurrency limit. Exceeding it returns `409 concurrency_limit_reached`. Check `GET /limits` (`concurrent_sandboxes.used`, `bulk_fork.max_count`, `can_create`) before large batches.

Admission is atomic: parallel requests of one account cannot together go over the limit, and a bulk fork either creates all `count` sandboxes or none.

**New accounts.** A Free account that is not verified yet (no card, no GitHub verification) gets stricter defaults for its first 7 days: no bulk fork (`count` 1) and 30 starts per minute. `GET /limits` shows `new_account.active` and `new_account.until`.

**Account restrictions.** If an account breaks the [acceptable use policy](/acceptable-use.html), its sandboxes can be throttled or have outbound ports blocked; new sandboxes and forks of that account get the same restrictions from the start. A suspended account gets `403` with `details.reason = "account_suspended"` (and `details.suspended_at`, `details.contact`) on every call except reads; its sandboxes are paused and the data is kept.

## API rate limits

| Policy | Limit | Applies to |
| --- | --- | --- |
| `default` | 6,000 requests / 60 s per API key (requests without a valid key: per client IP) | All endpoints |
| `starts` | 300 / 60 s per account (30 for new unverified Free accounts) | `POST /sandboxes`, `POST /sandboxes/{id}/resume`, `POST /sandboxes/{id}/fork` |

Every response carries the current state in IETF draft headers:

```http
RateLimit-Policy: "default";q=6000;w=60, "starts";q=300;w=60
RateLimit: "default";r=5987;t=42
```

When you exceed a limit you get `429` with `"code": "rate_limited"`, `"retryable": true` and a `Retry-After` header (seconds). An open SSE stream or WebSocket counts as one request. Implicit resumes caused by wake on request do not count toward `starts`.

## Sandboxes

| Resource | Limit |
| --- | --- |
| Sizes | `small` 2 vCPU / 4 GB / 20 GB, `default` 4 vCPU / 8 GB / 50 GB, `large` 8 vCPU / 16 GB / 100 GB |
| `disk_gb` | 20–1,000 GB (above the included disk is billed) |
| `auto_pause.idle_timeout_seconds` | 60–86,400 s, default 300 |
| `ttl_seconds` | ≥ 60 s, or `null` (no expiry, default) |
| Labels | 32 per sandbox; key up to 63 chars, value up to 255 |
| `env` at create | 100 variables, 64 KiB total |
| `metadata` | 16 KiB |
| Name | 120 characters |
| Create from template, p95 | < 500 ms (*target*) |
| Resume from pause, p95 | < 800 ms (*target*) |
| Fork with memory, p95 | < 2 s (*target*) |
| Bulk fork (`count` per call) | up to the account's limit (Free 2, Starter 10, Team 50, Enterprise 100; up to 500 on request), all or nothing; above it `403` with `details.reason = "fork_count_limit"` |
| Nested virtualization (`/dev/kvm`), GPU | Not available (roadmap) |

## Exec

| Resource | Limit |
| --- | --- |
| Concurrent commands per sandbox | at least 10 |
| Sync `timeout_seconds` | default 60, max 600 |
| Background commands | no time limit |
| Captured output in a sync response | 8 MiB per stream (`truncated: true` beyond) |
| SSE stream output | unlimited |
| Replay when attaching to a command | last 8 MiB per stream |
| Command history | 7 days |
| PTY idle timeout | default 1,800 s, max 86,400 s |
| PTY connect URL validity | 60 s until first connect |

## Files

| Resource | Limit |
| --- | --- |
| Read / write through the API (`/files/content`) | 1 GiB per request |
| Multipart upload | 1 GiB per request |
| Signed upload / download URLs | 10 GiB per file; valid 60–3,600 s (default 900) |
| Directory listing page size | 100 entries per page |

## Networking

| Resource | Limit |
| --- | --- |
| Exposed ports per sandbox | 20 |
| Protocols | HTTP/1.1, HTTP/2, WebSocket over HTTPS. Raw TCP/UDP: Coming soon |
| Access token TTL (private ports) | 60–86,400 s, default 3,600 |
| SSH access TTL | 60 s – 7 days, default 3,600 s |
| Egress allowlist | Coming soon |
| Region | EU only (`eu-de`, `eu-fi`) |

## Desktop

| Resource | Limit |
| --- | --- |
| Templates | `desktop` or a template built with `desktop: true` |
| Minimum size | `default` |
| Resolution | 1920x1080 |
| Stream URL TTL | 60–86,400 s, default 600 |
| Screenshot latency, p95 | < 300 ms (*target*) |
| Input actions per request | 100 |
| GPU / WebRTC 60 fps | Not available (roadmap) |

## Snapshots, templates, webhooks, keys

| Resource | Limit |
| --- | --- |
| Free snapshot storage | 30 days per snapshot |
| Webhook endpoints | 10 per account, HTTPS on port 443 |
| Webhook delivery | respond within 10 s; up to 8 attempts over 24 h |
| Webhook delivery history | 30 days |
| API key lifetime | default 90 days, max 365 days, or no expiry |
| Idempotency keys | 255 characters, kept 24 h |


---

<!-- source: https://task.cloud/docs/security.md -->

# Security

How `TaskCloud` isolates sandboxes, protects access, and handles your data. Report vulnerabilities to `security@task.cloud`.

> We do **not** hold SOC 2 or other certifications today. SOC 2 is planned for year 2. This page describes how the platform is built, not an audited attestation.

## Isolation model

Every sandbox is a separate **Firecracker microVM** with its own Linux kernel. The security boundary is the VM, not a container.

- **Firecracker jailer:** each VMM process runs chrooted, unprivileged, with a seccomp filter.
- **cgroups:** CPU, memory and I/O are limited per VM.
- **Network namespace per VM:** each sandbox has its own tap device and namespace. Sandboxes cannot reach each other, the host, or our internal APIs.
- **Forks** get their own IP, network namespace and copy-on-write disk. A change in a fork never affects the source.
- Inside the sandbox you have root (`user` has passwordless sudo). Treat everything inside one sandbox as one trust domain. **Give each end user their own sandbox.**

## API keys and scopes

Authenticate with `Authorization: Bearer taskcloud_sk_...`. Keys are shown once, stored hashed, expire after 90 days by default (max 365 days or never), and can be rotated with a grace period (`POST /api-keys/{id}/rotate`).

| Scope | Allows |
| --- | --- |
| `sandboxes:read` / `sandboxes:write` | Read / create, update, pause, resume, fork, delete sandboxes; manage ports |
| `exec` | Commands and PTY sessions |
| `files:read` / `files:write` | File access |
| `ssh` | SSH access and account SSH keys |
| `desktop` | Desktop stream URLs, screenshots, input |
| `snapshots:read` / `snapshots:write` | Snapshots |
| `templates:read` / `templates:write` | Templates |
| `webhooks:manage` | Webhook endpoints |
| `usage:read` | Usage and limits |
| `account:read` / `account:manage` | Account and spend limit |
| `api_keys:manage` | Create, rotate, revoke keys |

Presets: `read-only`, `full-sandbox`, `ci`, `admin`. A key can never create a key with more scopes than it has. A missing scope returns `403 insufficient_scope` with `details.required_scopes`.

### Least privilege for platforms

If your product hands sandboxes to end users or to an agent, never ship an `admin` key. Create a key restricted to that user's sandboxes:

```bash
curl -sS -X POST https://api.task.cloud/v1/api-keys \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"user-42","preset":"full-sandbox","restrict":{"labels":{"user":"42"}},"expires_in_days":30}'
```

Sandboxes created with that key automatically get the label `user=42`, and the key cannot see any other sandbox.

## Access to sandbox endpoints

| Surface | Protection |
| --- | --- |
| Domain separation | Sandbox URLs (ports, desktop, SSH) use `taskhost.cloud`, a separate domain from `task.cloud` (website and API), submitted to the Public Suffix List. A sandbox app is never same-site with the API and cannot set cookies for `task.cloud`. |
| Port URLs `https://<short_id>-<port>.taskhost.cloud` | `private` (default): requires an access token (`X-Sandbox-Token` header or `sandbox_token` query) or an API key. `public`: open to anyone with the URL. |
| Desktop stream | Signed URL with TTL (default 10 minutes), optional `read_only` and `single_use`, revocable. The VNC port is never exposed without a token. |
| PTY WebSocket | Signed URL valid 60 s until first connect. |
| Signed file URLs | Single file, 60–3,600 s. |
| SSH | Gateway `ssh.taskhost.cloud`, public-key auth (account keys or per-request keys with TTL) or a one-time password. |

Give browsers short-lived **access tokens** (`POST /sandboxes/{id}/access-tokens`) instead of API keys.

## Network

- **Inbound:** blocked except through our edge (exposed ports, desktop, SSH gateway). All edge traffic uses TLS.
- **Outbound:** open by default. A per-sandbox **egress allowlist** is **Coming soon**.
- Mining, spam, scanning and other abuse are prohibited and detected automatically; offending sandboxes are paused and the account may be suspended.

## Data

- **Location:** EU only. Sandboxes, disks and snapshots run and are stored on dedicated servers in the EU (machines we operate ourselves and machines rented from an EU hosting provider).
- **Encryption:** TLS in transit. Snapshots and disks are stored on our dedicated servers; encryption at rest details will be published before general availability.
- **Snapshots contain memory.** A pause snapshot or named snapshot includes everything in RAM: environment variables, tokens, decrypted secrets. Keep that in mind before turning a snapshot into a template you share or fork for other users.
- `env` and `registry_auth` values are write-only and never returned by the API.
- **Deletion:** `DELETE /sandboxes/{id}` removes the disk and the pause snapshot. Named snapshots and templates are deleted separately. Snapshots kept in object storage are encrypted with a per-organization key; when an organization is deleted, its data is purged after 30 days and that key is destroyed.

## Console accounts

- **Sign-in:** single-use e-mail links (15 minutes) or GitHub. Optional **two-factor authentication** with an authenticator app (TOTP) and single-use recovery codes; organizations can require it for members. See [Teams and roles](https://task.cloud/docs/teams.md#two-factor-authentication).
- **Sessions:** HttpOnly, Secure, SameSite cookies; every state-changing request needs a CSRF token and the console's origin. Sessions slide for 30 days and end at most 90 days after sign-in.
- **Client IP:** rate limits and the IP addresses in sessions and audit records use the real client address; `X-Forwarded-For` is trusted only from our own proxies.
- **API keys of people** never outlive the person's membership and never exceed their current role.
- **Your data:** export it or delete your account in Settings → Danger zone (details in [Teams and roles](https://task.cloud/docs/teams.md#your-personal-data-and-deleting-your-account)).
- **E-mails** from us never contain images or remote content and never ask for a code or password.

## Webhooks

Every webhook is signed with HMAC-SHA256 and carries a timestamp. Verify the signature and reject events older than 300 s. See [Webhooks](https://task.cloud/docs/guides/webhooks.md).

## Agents and computer use

- Content an agent reads (web pages, files, screenshots) can contain prompt injection. Keep credentials the agent does not need out of the sandbox.
- Use `read_only` desktop links for people who only watch.
- Use restricted keys for MCP servers and agent tools (see [MCP](https://task.cloud/docs/mcp.md)).

## Not available yet

SSO, passkeys, customer-facing audit logs, customer-managed keys, private networking, and self-hosting are on the roadmap.