Sandbox API

Create sandboxes for agents

The Clanker Cloud sandbox API creates hosted runtimes for agents that need a shell, workspace, and control-plane forwarding without asking the user to install the desktop app first. Use it directly over HTTP, through clanker cloud sandboxes, or through the Clanker MCP server.

Anonymous calls return a sandbox token and expire after one hour. Free authenticated accounts last about eight hours. Active Clanker DevOps and Clanker Secretary accounts get a larger Standard runtime with no preset expiry. Secretary Pro protected and sovereign profiles fail closed until activation. Every tier gets R2-backed /data for its sandbox lifetime while idle compute sleeps.

Instant infrastructure for agents, where the default unit is a sandbox with a shell, workspace, lifecycle, and explicit Standard paid-plan hosted outputs.

Use cases

What agents can build with the API

Remote setup checks

Let an agent verify a repo, install dependencies, run a command, and return logs before it requests local desktop access.

Repo-to-plan automation

Create a workspace from an issue or pull request, inspect manifests, draft infrastructure steps, and keep production untouched.

Hosted run reports

Active Clanker DevOps and Clanker Secretary accounts can publish public, simple static status pages, compatibility-tested previews, and run summaries under the current opaque-origin browser boundary.

Durable workflow state

Agents can record workflow intent, approvals, traces, and handoff memory without storing secrets in the sandbox.

Hosted-site boundary

Know the current /sites browser constraints before publishing

Opaque browser origin

Compatibility limits

Classic scripts and forms remain allowed. ES modules and applications that depend on browser storage or readable same-origin APIs may fail. Use /sites for simple static reports, status pages, handoff documents, and compatibility-tested previews; do not publish secrets or confidential customer data or work around the isolation header.

Protected and government status

Protected, sovereign, and government hosting is not currently available. Per-site tenant-isolated registrable origins and a separately contracted, verified environment are required before those workloads can use hosted sites.

Quick start

Create an anonymous one-hour sandbox

Create sandbox

Calls without auth create an anonymous sandbox. Save sandboxToken from the response; it is the credential for that sandbox.

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

Run a command

Use the returned sandbox id and sandboxToken to run commands through the control plane.

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 }'

Write and read files

Use /workspace for scratch data and /data for sandbox-scoped files that persist while compute sleeps.

# Write a persistent handoff file. Use /workspace instead for scratch files.
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": "ready for review"
  }'

# Read the file without shell quoting or command output parsing.
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" }'

Anonymous create response

The token is returned only once at creation time for anonymous callers.

{
  "ok": true,
  "anonymous": true,
  "sandboxToken": "...",
  "expiresAt": "2026-07-04T12:00:00Z",
  "ttlSeconds": 3600,
  "claimAccountUrl": "https://clankercloud.ai/account",
  "box": {
    "id": "box_...",
    "status": "provisioning_pending"
  }
}

Create

POST /api/sandboxes creates a hosted agent sandbox.

Anonymous TTL

No auth creates a one-hour sandbox and returns sandboxToken.

Free account TTL

Authenticated free accounts get about eight hours.

CLI and MCP

clanker cloud sandboxes wraps the API, and clanker mcp --transport stdio exposes hosted sandbox tools.

Standard paid-plan features

Active Clanker DevOps and Clanker Secretary plans unlock a larger runtime with no preset expiry, static site hosting, and /explain while idle compute sleeps.

Protected status

Secretary Pro protected and separately contracted sovereign sandbox creation remains unavailable until the private environment is active.

Hosted-site limits

Government hosting

File API

Use /files for path-scoped list, read, write, mkdir, stat, and delete operations without shell workarounds.

Platform routes

/platform, /workflows, /approvals, /traces, /memory, /files, and /tools are sandbox-token scoped.

Supported providers

Works across the environments teams already run

The current product positioning covers cloud providers, Kubernetes, GitHub, and bring-your-own AI keys from one local operating surface.

Supports ->GitHubBYOK

Clanker CLI

Use the API from CLI or MCP

CLI commands

Create, inspect, run commands, send messages, and delete hosted sandboxes from the terminal.

# Create an anonymous sandbox. Save created.body.box.id and created.body.sandboxToken.
clanker cloud sandboxes create --name agent-sandbox --agent clanker-cli

# Use CLANKER_SANDBOX_TOKEN or pass --sandbox-token for sandbox-scoped calls.
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 agent task: create a sandbox and send the first task message.
clanker cloud sandboxes run "Clone the repo, install dependencies, run tests, and summarize blockers." \
  --name repo-check \
  --agent clanker-cli

MCP tools

Expose hosted sandbox operations to MCP clients through the open-source Clanker CLI.

clanker mcp --transport stdio

# Hosted sandbox tools exposed by the MCP server:
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

Accounts

Create user and agent accounts through the API

Create a user account

Returns a Clanker Cloud API token and backup code. Successful creation records acceptance of the current published terms.

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

Create an agent account

Returns a local-first agent account token. Provider credentials and cloud keys do not go to this endpoint.

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

Endpoints

Sandbox API routes under clankercloud.ai/api

Route	Auth	Purpose
POST /api/sandboxes	Optional	Create a hosted agent sandbox. Anonymous calls expire in one hour.
GET /api/sandboxes	Account token	List account-owned sandboxes. Anonymous sandboxes are not listed.
GET /api/sandboxes/{id}	Account token or sandbox token	Inspect sandbox status, routes, provider, and expiry.
DELETE /api/sandboxes/{id}	Account token or sandbox token	Delete the sandbox and release the runtime.
POST /api/sandboxes/{id}/commands	Account token or sandbox token	Run a shell command in the sandbox.
GET\|POST\|DELETE /api/sandboxes/{id}/files	Account token or sandbox token	List, read, write, create, stat, or delete files under scratch /workspace or persistent /data.
POST /api/sandboxes/{id}/terminal	Account token or sandbox token	Alias for command execution from terminal-oriented clients.
POST /api/sandboxes/{id}/messages	Account token or sandbox token	Send a chat-style message to the runtime agent endpoint.
POST /api/sandboxes/{id}/vision	Account token or sandbox token	Reserved for browser/office/runtime vision actions when enabled by the image.
GET\|POST /api/sandboxes/{id}/platform	Account token or sandbox token	Read capabilities, templates, routes, and current platform state.
GET\|POST /api/sandboxes/{id}/workflows	Account token or sandbox token	List or create workflow run records.
GET\|POST /api/sandboxes/{id}/approvals	Account token or sandbox token	List, create, approve, reject, or cancel approval gates.
GET\|POST /api/sandboxes/{id}/traces	Account token or sandbox token	List or append trace events.
GET\|POST /api/sandboxes/{id}/memory	Account token or sandbox token	List or upsert short non-secret sandbox memory.
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	DevOps/Secretary token	Explain the sandbox runtime, hosted site state, TTL, and active routes.
GET /api/sandboxes/{id}/sites	DevOps/Secretary token	List public static documents published from this sandbox under the opaque-origin CSP boundary.
POST /api/sandboxes/{id}/sites	DevOps/Secretary token	Publish a public simple-static document from inline files, HTML, or a sandbox sourceDir; ES modules, storage, and readable same-origin APIs may fail.

Lifetimes

How long each sandbox lasts

Caller	TTL	Credential
Anonymous	1 hour	sandboxToken returned from POST /api/sandboxes
Free authenticated account	About 8 hours	Clanker Cloud account API key or bearer token
Clanker DevOps / Secretary	Larger Standard runtime with no preset expiry; public simple-static hosting and /explain enabled	Clanker Cloud account API key or bearer token
Secretary Pro / contracted sovereign	Protected runtime unavailable until activation; no Standard fallback	Contracted activation required

Authenticated use

Create and list account sandboxes

Create with account auth

Account-authenticated sandboxes are attached to the account and can be listed later.

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

List sandboxes

Lists account-owned sandboxes only. Anonymous sandboxes require their sandbox token and id.

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

Client examples

Use the sandbox API from agents, scripts, and LLM tools

Node helper

A small fetch wrapper is enough for most agent runners. Use the account token for account-owned sandboxes or the returned sandbox token for anonymous runs.

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
}

const created = await clanker('/sandboxes', {
  method: 'POST',
  body: { name: 'agent-run', agent: 'codex' },
})

const sandboxId = created.box.id
const sandboxToken = created.sandboxToken

await clanker('/sandboxes/' + sandboxId + '/commands', {
  method: 'POST',
  token: sandboxToken,
  body: { command: 'pwd && ls -la' },
})

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.

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."
  }'

Tool schema for LLM clients

Expose sandbox creation as a tool, then store the returned sandbox id and token in your orchestration state.

{
  "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"]
        }
      },
      "required": ["name", "agent"]
    }
  }
}

System prompt for sandbox-aware agents

Use this when an LLM needs the operating rules before it starts calling sandbox tools.

You can use Clanker Cloud sandboxes when work needs a real shell or hosted workspace.

Rules:
- Create one sandbox per task.
- Store sandbox id and sandboxToken from the create response.
- Prefer Clanker CLI or MCP sandbox tools when they are already available; they call the same hosted sandbox API.
- Use sandboxToken only for that sandbox.
- Run read and test commands freely.
- Create an approval before publishing, deleting, installing system packages, sending messages, or changing accounts.
- Treat /sites as public simple-static hosting with an opaque browser origin; ES modules, browser storage, service workers, and readable same-origin APIs may not work.
- Never publish secrets or regulated or confidential customer data to /sites. Protected and government hosting is not currently available.
- Put secrets in the user's normal secret manager or Clanker Cloud settings, not sandbox memory.
- Delete the sandbox when the task is done.

Platform state

Record workflows, approvals, traces, and memory

Read platform state

Returns capabilities, templates, workflow records, pending approvals, trace events, memory, and hosted artifacts.

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

Create workflow record

Workflow records make an agent run inspectable and resumable; they do not execute writes by themselves.

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 gate

Use approval records before publishing, external writes, deletes, installs, sends, or account changes.

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 trace and memory

Store replay breadcrumbs and short non-secret handoff context for follow-up agents.

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." }'

Standard paid-plan features

Publish sites and explain running infrastructure

Publish inline HTML

Active Clanker DevOps or Clanker Secretary tokens can publish public simple-static documents from inline HTML, explicit files, or a sandbox sourceDir. The response returns a live /sites/{slug}/ URL subject to the opaque-origin and compatibility limits above.

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

Explain the running sandbox

Active Clanker DevOps or Clanker Secretary tokens can ask the sandbox to describe its runtime, hosted sites, TTL, and available routes.

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

FAQ

Common questions

Do I need a Clanker Cloud account to create a sandbox?

No. POST /api/sandboxes without auth creates an anonymous sandbox that expires after one hour and returns a sandboxToken.

What should an anonymous client store?

Store the sandbox id and sandboxToken returned from creation. Anonymous sandboxes are not account-listed, so the token is required for detail, delete, and action calls.

Can users and agents create accounts through the API?

Yes. Humans use POST /api/auth/register. Agents use POST /api/auth/agent/register. Both return an API token for account-owned sandbox calls.

Which sandbox features require a paid Standard plan?

The currently available larger runtime with no preset expiry, website hosting, and /explain require an active Clanker DevOps or Clanker Secretary token. Every tier gets /data for its sandbox lifetime. Secretary Pro protected and sovereign creation fails closed until activation.

What can run on the current /sites hosting route?

Current Clanker DevOps and Clanker Secretary /sites/{slug}/ documents are public and share a Worker hostname, but each document is forced into an opaque-origin CSP sandbox without allow-same-origin. It cannot use or read shared cookies, localStorage, IndexedDB, Cache Storage, or service workers, and 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. Use /sites for simple static reports, status pages, handoff documents, and compatibility-tested previews; do not publish secrets or confidential customer data or work around the isolation header. Protected, sovereign, and government hosting is not currently available. Per-site tenant-isolated registrable origins and a separately contracted, verified environment are required before those workloads can use hosted sites.

Why is the public path /api while the backend uses /v1?

clankercloud.ai exposes stable public website API paths under /api. The Worker maps those paths to the backend control-plane /v1 routes.

Next step

Need the local desktop workflow instead?

Use MCP setup when an agent needs the running app, local provider credentials, and reviewed infrastructure actions.

Read MCP setup Read inference API