Remote setup checks
Let an agent verify a repo, install dependencies, run a command, and return logs before it requests local desktop access.
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. Paid authenticated accounts run on the larger paid sandbox runtime, persist until deleted, and unlock hosted sites plus /explain. Platform routes add workflow, approval, trace, memory, and tool metadata.
Instant infrastructure for agents, where the default unit is a sandbox with a shell, workspace, lifecycle, and paid hosted outputs.
Use cases
What agents can build with the API
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
Paid accounts can publish generated status pages, static previews, and run summaries from inside the sandbox.
Durable workflow state
Agents can record workflow intent, approvals, traces, and handoff memory without storing secrets in the sandbox.
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",
"region": "earth"
}'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" }'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.
Paid features
Paid accounts unlock larger persistent sandboxes, static site hosting, and /explain.
Platform routes
/platform, /workflows, /approvals, /traces, /memory, 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 --region earth
# 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 \
--region earthMCP 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_taskAccounts
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. |
| 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 | 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. |
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 |
| Paid authenticated account | Larger runtime, persistent until deleted; hosting and /explain enabled | Clanker Cloud account API key or bearer token |
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", "region": "earth" }'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', region: 'earth' },
})
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"]
},
"region": { "type": "string", "default": "earth" }
},
"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.
- 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." }'Paid features
Publish sites and explain running infrastructure
Publish inline HTML
Paid account tokens can publish static websites from inline HTML, explicit files, or a sandbox sourceDir. The response returns a live /sites/{slug}/ URL.
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
Paid account 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 account?
The larger persistent sandbox runtime, website hosting through /api/sandboxes/{id}/sites, and infrastructure summaries through /api/sandboxes/{id}/explain require a paid account token.
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.