# Clanker Cloud Sandbox API

Use this page when an agent needs a hosted sandbox without requiring the user to install the desktop app first.

Base URL:

```text
https://clankercloud.ai/api
```

For longer copy-paste examples for LLM tools, JavaScript clients, workflow state, approvals, and hosted outputs, use [API Docs](https://clankercloud.ai/api-docs).

## Create an account

User account:

```bash
curl -sS "https://clankercloud.ai/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "choose-a-password",
    "name": "User"
  }'
```

Agent account:

```bash
curl -sS "https://clankercloud.ai/api/auth/agent/register" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "codex",
    "machineHint": "linux/amd64/sandbox",
    "metadata": { "source": "agent-api" }
  }'
```

Both account creation endpoints return a Clanker Cloud API token. Send it as `X-API-Key: <token>` or `Authorization: Bearer <token>`.

## Create a sandbox

Anonymous one-hour sandbox:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-sandbox",
    "agent": "clanker-cli",
    "region": "earth"
  }'
```

Anonymous response includes `sandboxToken`. Store the sandbox `id` and `sandboxToken`; the token is required for detail, delete, and action calls.

Authenticated sandbox:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_CLOUD_API_KEY" \
  -d '{ "name": "codex-runner", "agent": "codex", "region": "earth" }'
```

## Use from Clanker CLI

```bash
clanker cloud sandboxes create --name agent-sandbox --agent clanker-cli --region earth
export CLANKER_SANDBOX_TOKEN="<sandboxToken from create>"
clanker cloud sandboxes command "$SANDBOX_ID" "pwd && ls -la"
clanker cloud sandboxes run "Clone the repo, install dependencies, run tests, and summarize blockers."
```

Use `CLANKER_CLOUD_API_KEY` or `--api-key` for account-owned sandboxes. `clanker mcp --transport stdio` exposes sandbox tools such as `clanker_cloud_create_sandbox`, `clanker_cloud_run_sandbox_command`, and `clanker_cloud_run_sandbox_task`.

## Lifetime rules

- Anonymous: expires after 1 hour.
- Free authenticated account: expires after about 8 hours.
- Paid authenticated account: persists until deleted and runs on the larger paid sandbox runtime.
- Platform records (`/platform`, `/workflows`, `/approvals`, `/traces`, `/memory`, and `/tools`) are available to any active sandbox while it exists.
- Hosted sites and `/explain` require a paid account token.

## Endpoints

| Route | Auth | Purpose |
| --- | --- | --- |
| `POST /api/sandboxes` | Optional | Create a hosted agent sandbox. |
| `GET /api/sandboxes` | Account token | List account-owned sandboxes. |
| `GET /api/sandboxes/{id}` | Account token or sandbox token | Inspect status, routes, provider, and expiry. |
| `DELETE /api/sandboxes/{id}` | Account token or sandbox token | Delete the sandbox. |
| `POST /api/sandboxes/{id}/commands` | Account token or sandbox token | Run a shell command. |
| `POST /api/sandboxes/{id}/terminal` | Account token or sandbox token | Terminal alias for shell execution. |
| `POST /api/sandboxes/{id}/messages` | Account token or sandbox token | Send a chat-style runtime message. |
| `POST /api/sandboxes/{id}/vision` | Account token or sandbox token | Reserved for browser, office, and vision actions when enabled by the runtime image. |
| `GET\|POST /api/sandboxes/{id}/platform` | Account token or sandbox token | Read capabilities, templates, workflows, approvals, traces, memory, hosted artifacts, and tool metadata. |
| `GET\|POST /api/sandboxes/{id}/workflows` | Account token or sandbox token | List or create durable workflow run records. |
| `GET\|POST /api/sandboxes/{id}/approvals` | Account token or sandbox token | List, create, approve, reject, or cancel side-effect approval gates. |
| `GET\|POST /api/sandboxes/{id}/traces` | Account token or sandbox token | List or append observability trace events. |
| `GET\|POST /api/sandboxes/{id}/memory` | Account token or sandbox token | List or upsert short non-secret sandbox memory records. |
| `GET\|POST /api/sandboxes/{id}/tools` | Account token or sandbox token | Read tool gateway metadata and credential-boundary guidance. |
| `GET\|POST /api/sandboxes/{id}/explain` | Paid account token | Explain the sandbox runtime, hosted site state, TTL, and active routes. |
| `GET /api/sandboxes/{id}/sites` | Paid account token | List static sites published from this sandbox. |
| `POST /api/sandboxes/{id}/sites` | Paid account token | Publish a static website from inline files, HTML, or a sandbox `sourceDir`. |

## Run a command

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/commands" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{ "command": "pwd && ls -la" }'
```

For authenticated account-owned sandboxes, use the account API key or `Authorization: Bearer $CLANKER_CLOUD_API_KEY` instead.

## Send an agent message

Use messages when the runtime image has an agent endpoint and you want task-level instructions instead of raw shell commands.

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "role": "user",
    "content": "Clone the repo, install dependencies, run tests, and summarize anything that blocks the run."
  }'
```

## JavaScript helper

```js
const BASE_URL = 'https://clankercloud.ai/api'

async function clanker(path, { token, method = 'GET', body } = {}) {
  const response = await fetch(BASE_URL + path, {
    method,
    headers: {
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(token ? { 'X-API-Key': token } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  })

  const data = await response.json().catch(() => ({}))
  if (!response.ok) throw new Error(data.error || 'Clanker Cloud request failed')
  return data
}
```

## LLM tool schema

```json
{
  "type": "function",
  "function": {
    "name": "create_clanker_sandbox",
    "description": "Create a hosted Clanker Cloud sandbox for an agent run.",
    "parameters": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "agent": {
          "type": "string",
          "enum": ["clanker-cli", "codex", "claude-code", "openclaw", "hermes", "empty", "clanker-vision"]
        },
        "region": { "type": "string", "default": "earth" }
      },
      "required": ["name", "agent"]
    }
  }
}
```

## Agent platform records

Platform records are sandbox-local orchestration metadata available to any active sandbox. They do not execute writes by themselves and should not contain secrets.

Read platform state:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/platform" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN"
```

Create a workflow run record:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/workflows" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "name": "deploy fixer",
    "trigger": "webhook",
    "approvalMode": "before_side_effects",
    "steps": ["inspect", "test", "pause before write", "publish report"]
  }'
```

Create an approval gate:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/approvals" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "workflowId": "$WORKFLOW_ID",
    "title": "Publish deploy report",
    "summary": "Allow the agent to publish a static report from this sandbox.",
    "risk": "low",
    "status": "pending"
  }'
```

Append a trace event and save a handoff note:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/traces" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{ "type": "shell.command", "summary": "npm test passed", "level": "info" }'

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/memory" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{ "key": "handoff", "scope": "sandbox", "value": "Tests passed; waiting for approval before publishing." }'
```

## Paid features

Website hosting, `/explain`, and the larger persistent sandbox runtime require a paid account token. Free account tokens and anonymous sandbox tokens receive `402 paid account required` for paid-only endpoints.

Publish a static site from inline HTML:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/sites" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_CLOUD_API_KEY" \
  -d '{
    "name": "agent status",
    "slug": "agent-status",
    "html": "<!doctype html><h1>Agent run is ready</h1>"
  }'
```

Publish a built folder from inside the sandbox:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/sites" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_CLOUD_API_KEY" \
  -d '{ "name": "dist preview", "slug": "dist-preview", "sourceDir": "/workspace/dist", "spa": true }'
```

Explain the running sandbox infrastructure:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/explain" \
  -H "X-API-Key: $CLANKER_CLOUD_API_KEY"
```

## Notes for agents

- Prefer `region: "earth"` for hosted sandboxes.
- Use `agent: "clanker-cli"` unless the user requested `codex`, `claude-code`, `empty`, `hermes`, `openclaw`, or `clanker-vision`.
- Use `/api/auth/register` for human accounts and `/api/auth/agent/register` for local-first agent accounts.
- Use paid account auth before calling `/sites` or `/explain`.
- Treat a `409` runtime response as provisioning not ready yet and retry with backoff.
- Treat `410` as expired; create a new sandbox.
- The public website path is `/api`. The backend control plane maps it to `/v1`.

Related:

- https://clankercloud.ai/api
- https://clankercloud.ai/api-docs
- https://clankercloud.ai/cloud-for-agents
- https://clankercloud.ai/mcp