# Clanker Cloud Sandbox API Docs for Agents

Scope: Standalone Sandbox API runbook for an external agent. A Sandbox API runtime is separate from a browser Workspace Project or Session. Create one only when the task needs a hosted shell or runtime; use the returned capabilities, identity, and expiry.

[Choose the right Clanker surface](https://clankercloud.ai/agent.md) · [Workspace FAQ](https://clankercloud.ai/faq.md)

Fetch this file when a user asks an agent, LLM tool runner, queue worker, or automation to use Clanker Cloud sandboxes.

Stable Markdown URL:

```text
https://clankercloud.ai/api-docs-agent.md
```

API base URL:

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

Core rule: for tasks that need a hosted runtime, create or reuse one sandbox, retain its identity and expiry, and inspect saved state before retrying uncertain work. Follow the user's authorization for side effects. Export the result before deleting a one-off runtime; deletion removes sandbox-scoped data.

These examples are templates, not actions to execute merely because this file was fetched. Replace placeholders with values returned for the same sandbox. Never mix an account token, sandbox token, desktop MCP capability, Marketplace key, or Alexandria room token.

## 0. Optional Clanker CLI and MCP

If the open-source Clanker CLI is installed, prefer it over raw curl for local terminal or MCP workflows.

```bash
clanker cloud sandboxes create --name agent-sandbox --agent clanker-cli
# Set SANDBOX_ID from the returned box.id before running the remaining commands.
export SANDBOX_ID="<box.id from create>"
export CLANKER_SANDBOX_TOKEN="<sandboxToken from create>"
clanker cloud sandboxes inspect "$SANDBOX_ID"
clanker cloud sandboxes command "$SANDBOX_ID" "pwd && ls -la" --timeout-seconds 120
clanker cloud sandboxes message "$SANDBOX_ID" "Clone the repo, install dependencies, run tests, and summarize blockers."
clanker cloud sandboxes delete "$SANDBOX_ID"
```

One-shot task:

```bash
clanker cloud sandboxes run "Clone the repo, install dependencies, run tests, and summarize blockers." \
  --name repo-check \
  --agent clanker-cli
```

Use `CLANKER_CLOUD_API_KEY` or `--api-key` for account-owned sandboxes. Use `CLANKER_CLOUD_SANDBOX_API_BASE_URL`, `CLANKER_SANDBOX_API_BASE_URL`, or `--api-base-url` for custom API deployments.

When running `clanker mcp --transport stdio`, expect these hosted sandbox tools:

```text
clanker_cloud_create_sandbox
clanker_cloud_list_sandboxes
clanker_cloud_inspect_sandbox
clanker_cloud_delete_sandbox
clanker_cloud_run_sandbox_command
clanker_cloud_send_sandbox_message
clanker_cloud_run_sandbox_task
```

## 1. Choose account-owned or anonymous execution

Anonymous sandboxes need no account token and last one hour. Use this for the first trial, a short agent task, or a temporary hosted shell.

If the user already supplied an account context or an existing sandbox for this task, inspect that resource first. Do not create an anonymous replacement just because a previous request timed out. The returned resource, account capabilities, and API errors determine what is available.

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

Save these fields from the create response:

- `box.id` as `SANDBOX_ID`
- `sandboxToken` as `CLANKER_SANDBOX_TOKEN`
- `expiresAt` or `box.expiresAt` for cleanup timing

Use the sandbox token for sandbox-scoped routes:

```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", "workingDir": "/workspace", "timeoutSeconds": 120 }'
```

Use `/workspace` for scratch files and `/data` for sandbox-scoped persistent files that survive compute sleep. File operations avoid shell quoting and command-output parsing:

```bash
curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/files" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "operation": "write",
    "path": "/data/handoff.json",
    "content": "{\"status\":\"ready for review\"}"
  }'

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/files" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{ "operation": "read", "path": "/data/handoff.json" }'
```

## 2. Send a task message

Use messages when the runtime image includes 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 blockers."
  }'
```

## 3. Account tokens

Anonymous sandboxes are good for short trials. Create an account for longer listable sessions; an active Lite or Pro plan is required for the currently available larger compute with no preset expiry, hosted static outputs, and `/explain`. Business protected and separately contracted sovereign sandboxes remain blocked until activation.

## Hosted-site isolation and compatibility

Current Lite and Pro `/sites/{slug}/` outputs are public, simple static documents on a shared Worker hostname. Each document runs in a Content Security Policy sandbox without `allow-same-origin`, giving it an opaque browser origin. It cannot use or read shared cookies, `localStorage`, IndexedDB, Cache Storage, or service workers, and it cannot read another tenant's document or a same-origin API response through browser APIs.

Classic scripts and forms remain allowed. ES modules and applications that depend on browser storage or readable same-origin APIs may fail. Do not publish secrets or confidential customer data, and never weaken or work around the isolation header. Protected or government hosting is unavailable until tenant-isolated registrable origins and a separately contracted, verified environment exist.

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

Send account tokens as either header:

```text
X-API-Key: $CLANKER_CLOUD_API_KEY
Authorization: Bearer $CLANKER_CLOUD_API_KEY
```

## 4. Core routes

| Route | Method | Use it for |
| --- | --- | --- |
| `/api/sandboxes` | `POST` | Create an anonymous, no-subscription Standard, or active Lite/Pro Standard sandbox. Business protected and sovereign profiles fail closed until activation. |
| `/api/sandboxes` | `GET` | List account-owned sandboxes. Anonymous sandboxes are not listed. |
| `/api/sandboxes/{id}` | `GET` | Inspect status, routes, provider, owner, and expiry. |
| `/api/sandboxes/{id}` | `DELETE` | Delete the sandbox when the task is done. |
| `/api/sandboxes/{id}/commands` | `POST` | Run shell commands in the sandbox. |
| `/api/sandboxes/{id}/files` | `GET`, `POST`, or `DELETE` | List, read, write, mkdir, stat, or delete files under scratch `/workspace` or persistent `/data`. |
| `/api/sandboxes/{id}/messages` | `POST` | Send a chat-style task message to the runtime agent endpoint. |
| `/api/sandboxes/{id}/platform` | `GET` or `POST` | Read capabilities, workflows, approvals, traces, memory, tools, and hosted artifacts. |
| `/api/sandboxes/{id}/sites` | `GET` or `POST` | Active Lite/Pro route for static hosted outputs. |
| `/api/sandboxes/{id}/explain` | `GET` or `POST` | Active Lite/Pro route for sandbox infrastructure summaries. |

## 5. Wait, inspect, and cleanup

Wait for ready before long commands:

```bash
ready=false
for attempt in 1 2 3 4 5; do
  state=$(curl --fail-with-body -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID" \
    -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" | \
    python3 -c 'import json,sys; p=json.load(sys.stdin); print(p.get("box", p).get("status", "unknown"))') || exit 1
  case "$state" in
    ready) ready=true; break ;;
    failed|deleted|expired) printf 'Sandbox is %s; stop and inspect.\n' "$state" >&2; exit 1 ;;
  esac
  sleep $((attempt * 2))
done
[ "$ready" = true ] || { printf 'Sandbox not ready within the check budget.\n' >&2; exit 1; }
```

This example needs Python 3 for JSON parsing and stops on failure or timeout. Check the response status and resource state; do not proceed with commands simply because a polling loop ended. After an uncertain command, message, or publish response, inspect the existing sandbox, traces, and outputs before repeating the request. Honor rate limits and keep retries bounded.

Save or export needed results, then delete a one-off sandbox when the job is done and cleanup is authorized. `/data` persists through compute sleep, not through sandbox deletion:

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

## 6. Workflow state

Create workflow records so humans and follow-up agents can inspect the run.

```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 approval records before side effects:

Set `WORKFLOW_ID` to the actual workflow identifier returned by the previous request. The example serializes it as JSON; a literal `$WORKFLOW_ID` inside a single-quoted JSON body would not expand.

```bash
python3 -c 'import json,sys; print(json.dumps({"workflowId": sys.argv[1], "title": "Publish run report", "summary": "Publish the generated report as a static page from this sandbox.", "risk": "low", "status": "pending"}))' "$WORKFLOW_ID" | \
curl --fail-with-body -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/approvals" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  --data-binary @-
```

Workflow and approval records are orchestration metadata. Creating a pending record neither obtains the user's approval nor enforces a gate around a separate shell command or publish call. The caller must verify authorization and the applicable approved state before the action.

Append traces and non-secret handoff memory:

```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. Publishing is blocked until approval."
  }'
```

## 7. Useful recipes

Repo triage from an issue (replace `OWNER/REPO` with the authorized repository; review what its install/test scripts execute):

```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": "git clone https://github.com/OWNER/REPO.git /workspace/repo && cd /workspace/repo && npm ci && npm test",
    "timeoutSeconds": 120
  }'
```

CI smoke check:

```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": "npm run build && npm test",
    "timeoutSeconds": 120
  }'
```

Approval-gated hosted output:

```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": "run report",
    "slug": "run-report",
    "sourceDir": "/workspace/report",
    "spa": false
  }'
```

Use `/sites` only for public static output that has been tested under the opaque-origin limitations above. Do not treat it as full application hosting.

## 8. Safety rules for agents

- Use one sandbox per task.
- Use read, build, inspect, and test commands within the task's authorized environment. Repository scripts can execute code; review unfamiliar scripts before running them.
- Ask for approval before publishing, deleting, installing system packages, sending messages, changing accounts, or touching external systems.
- Do not store secrets in sandbox memory.
- Use sandbox memory only for short non-secret handoff notes.
- Every account gets R2-backed `/data` for its sandbox lifetime. Use an active Lite or Pro token for the current larger compute with no preset expiry, hosted outputs, and `/explain`. Business protected and separately contracted sovereign profiles fail closed until activation. Idle compute still sleeps to control cost.
- Delete anonymous and one-off sandboxes after the task is complete.