Need help with infra for agents?

Quick start

Create an anonymous sandbox first

No account is required for the first run. Create a one-hour sandbox, save the returned box.id and sandboxToken, then use that token for commands or task messages.

Create anonymous sandbox

Call POST /api/sandboxes without auth. Save box.id as SANDBOX_ID and sandboxToken as CLANKER_SANDBOX_TOKEN.

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

Run the first command

Use the sandboxToken returned from create. This keeps the runtime scoped to the one task.

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

Manage workspace files

Use /workspace for scratch files or /data for low-cost persistent state that survives compute sleep.

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

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.

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

Clanker CLI

Use sandboxes from CLI or MCP

The open-source Clanker CLI now wraps the hosted sandbox API for terminal users and exposes the same operations as MCP tools for Codex, Claude Code, GitHub Copilot, OpenClaw, Hermes, and other clients.

CLI quickstart

Create, inspect, command, message, and delete hosted sandboxes from the terminal. Account-owned calls use CLANKER_CLOUD_API_KEY or --api-key.

# 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

Launch the CLI as an MCP server when an agent should create sandboxes, run commands, or send sandbox task messages through tool calls.

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

Markdown for agents

Fetch the agent-readable API docs

Agents can query a stable Markdown file before calling sandbox routes. Use it as retrieval context for tool runners, LLM orchestration, queue workers, and internal automations.

Fetch the Markdown file

Use this URL when an agent needs the full sandbox API contract without browsing the rendered page: https://clankercloud.ai/api-docs-agent.md

curl -fsS "https://clankercloud.ai/api-docs-agent.md"

Agent instruction

Paste this into your runner or system prompt before enabling sandbox API calls.

Before using the Clanker Cloud sandbox API, fetch https://clankercloud.ai/api-docs-agent.md. Start with an anonymous sandbox unless the task needs an active DevOps/Secretary paid feature. Treat /sites as public simple-static output with opaque-origin compatibility limits; protected and government hosting is unavailable. Save box.id and sandboxToken, keep workflow state with the sandbox, ask before side effects, and delete one-off runtimes when finished.

Agent handoff

Copy docs for your agent

Paste this into Codex, Claude Code, OpenClaw, Hermes, your own runner, or any LLM tool orchestrator that needs the sandbox API contract, account creation paths, token rules, workflow records, approvals, traces, memory, paid outputs, and cleanup behavior.

# Clanker Cloud sandbox API runbook for agents

Base URL: https://clankercloud.ai/api

Use Clanker Cloud sandboxes when a task needs a real hosted shell, files, command execution, workflow state, approval records, traces, memory, or a hosted output.

Agent-readable Markdown docs:

...

Use cases

Useful jobs to run in a sandbox

Repo triage from an issue

Clone a repo, install dependencies, run tests, inspect failures, and leave handoff memory before opening a PR.

CI smoke checks

Run build and test commands in a clean hosted runtime before a deployment, migration, or agent-authored change.

Approval-gated publishing

Generate a public simple-static report or compatibility-tested preview, create an approval record, then publish only after the user accepts the step.

Scheduled reports

Use workflow metadata to track weekly ops, cost, security, or account-review jobs with clear owners and steps.

Human handoffs

Store traces and short non-secret memory so a teammate or follow-up agent can resume without rereading the whole run.

LLM tool orchestration

Expose sandbox creation as a tool, keep sandbox tokens in orchestration state, and let the model call safe task operations.

Base URL

Use https://clankercloud.ai/api for public sandbox API calls.

Authentication

Use X-API-Key or Authorization: Bearer with either an account token or the returned sandbox token.

CLI and MCP

Use clanker cloud sandboxes for terminal workflows, or clanker mcp --transport stdio for agent tools.

Tiers

Anonymous sandboxes last one hour. Free Standard sandboxes last about eight hours. Active Clanker DevOps and Clanker Secretary plans get larger compute with no preset expiry.

Agent state

Use files, workflows, approvals, traces, memory, and tools routes to make runs inspectable and resumable.

Hosted-site 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.

Lifecycle

List, inspect, wait, and clean up sandboxes

Agents should treat sandboxes like task runtimes: create one, wait until it is ready, keep the id and token, then delete it when the job is done.

List account sandboxes

Use an account API key to show sandboxes owned by the account. Anonymous sandboxes are only addressable by id and sandbox token.

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

Inspect one sandbox

Use this before resuming a task, showing status in a dashboard, or deciding whether to recreate an expired runtime.

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

Wait for ready

Use a small backoff loop before running commands when a create response says the runtime is still starting.

for attempt in 1 2 3 4 5; do
  STATUS=$(curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID" \
    -H "X-API-Key: $CLANKER_SANDBOX_TOKEN")

  echo "$STATUS"
  echo "$STATUS" | grep -q '"status":"ready"' && break
  sleep $((attempt * 2))
done

Delete when finished

Clean up one-off runtimes after publishing the result or saving the handoff state somewhere durable.

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

Routes

Core sandbox routes

Route	Method	Use it for
/api/sandboxes	POST	Create an anonymous, free Standard, or active DevOps/Secretary Standard sandbox. Secretary Pro 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 /workspace or /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 DevOps/Secretary route for public simple-static outputs under the opaque-origin CSP boundary.
/api/sandboxes/{id}/explain	GET or POST	Active DevOps/Secretary route for sandbox infrastructure summaries.

Accounts

Create accounts for humans and agents

Human account

Creates a Clanker Cloud account and returns an API token plus backup code.

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

Creates a local-first agent account token for programmatic sandbox calls.

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

Authenticated sandbox

Account-owned sandboxes inherit the server-enforced account region and can be listed later with the account session.

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

LLM integration

Teach an LLM when and how to use sandboxes

Tool schema

Register sandbox creation as a tool. Your orchestration layer should call the HTTP API and store returned credentials outside the model transcript when possible.

{
  "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"]
    }
  }
}

Tool dispatcher

A minimal dispatcher for the tool call. Keep sandboxToken in your runner or session store instead of echoing it back to the model.

async function dispatchSandboxTool(call) {
  if (call.name !== 'create_clanker_sandbox') {
    throw new Error('Unknown tool: ' + call.name)
  }

  const args = call.arguments
  const created = await clanker('/sandboxes', {
    method: 'POST',
    body: {
      name: args.name,
      agent: args.agent || 'empty',
    },
  })

  // Store these in your orchestration layer, not in the visible model transcript.
  return {
    sandboxId: created.box.id,
    sandboxToken: created.sandboxToken,
    expiresAt: created.box.expiresAt,
  }
}

System prompt

Give this to an LLM or agent before allowing sandbox tool calls.

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.

JavaScript helper

A minimal fetch helper for Node, Workers, serverless functions, or agent runners.

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

Agent runners

End-to-end runner examples

These examples are meant for small agent runners, queue workers, test automation, and internal tools that need a hosted runtime but still want an approval trail.

End-to-end JavaScript run

Create a sandbox, create a workflow, run a repo command, append a trace, and store handoff memory.

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

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

const workflow = await clanker('/sandboxes/' + sandboxId + '/workflows', {
  method: 'POST',
  token: sandboxToken,
  body: {
    name: 'repo check',
    trigger: 'api',
    approvalMode: 'before_side_effects',
    steps: ['clone', 'install', 'test', 'report'],
  },
})

await clanker('/sandboxes/' + sandboxId + '/commands', {
  method: 'POST',
  token: sandboxToken,
  body: { command: 'git clone "$REPO_URL" repo && cd repo && npm test' },
})

await clanker('/sandboxes/' + sandboxId + '/traces', {
  method: 'POST',
  token: sandboxToken,
  body: { type: 'workflow.step', summary: 'Test command finished', level: 'info' },
})

await clanker('/sandboxes/' + sandboxId + '/memory', {
  method: 'POST',
  token: sandboxToken,
  body: {
    key: 'handoff',
    scope: 'sandbox',
    value: 'Repo check finished. Review traces before publishing or changing anything.',
  },
})

return { sandboxId, workflowId: workflow.id || workflow.workflowId }

Python helper

Use the same API from a Python automation process or backend job.

import os
import requests

BASE_URL = "https://clankercloud.ai/api"

def clanker(path, token=None, method="GET", body=None):
    headers = {}
    if token:
        headers["X-API-Key"] = token
    if body is not None:
        headers["Content-Type"] = "application/json"

    response = requests.request(
        method,
        BASE_URL + path,
        headers=headers,
        json=body,
        timeout=60,
    )
    response.raise_for_status()
    return response.json() if response.content else {}

created = clanker(
    "/sandboxes",
    method="POST",
    body={"name": "python-agent-run", "agent": "empty"},
)

sandbox_id = created["box"]["id"]
sandbox_token = created["sandboxToken"]

command = clanker(
    f"/sandboxes/{sandbox_id}/commands",
    token=sandbox_token,
    method="POST",
    body={"command": "python --version && pwd"},
)

print(command)

Webhook-style trigger

Create a workflow record tied to a webhook or queue event, then let the sandbox hold the run state.

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/workflows" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "name": "daily account review",
    "trigger": "webhook:account-review",
    "approvalMode": "before_side_effects",
    "metadata": { "source": "internal-queue", "runId": "run_123" },
    "steps": ["collect evidence", "draft report", "ask for approval", "publish"]
  }'

Recipes

Practical sandbox recipes

Use these as starting points for real workflows. They keep work inside one sandbox, record state as the job moves forward, and pause before side effects.

Repo triage from an issue

Create a sandbox for one issue, run the repo checks, and save a handoff for the next human or agent.

const repoUrl = 'https://github.com/acme/app'

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

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

await clanker('/sandboxes/' + sandboxId + '/workflows', {
  method: 'POST',
  token: sandboxToken,
  body: {
    name: 'issue triage',
    trigger: 'github:issue:482',
    approvalMode: 'before_side_effects',
    steps: ['clone repo', 'run tests', 'inspect failing files', 'write handoff'],
  },
})

await clanker('/sandboxes/' + sandboxId + '/commands', {
  method: 'POST',
  token: sandboxToken,
  body: {
    command: 'git clone "' + repoUrl + '" repo && cd repo && npm ci && npm test',
  },
})

await clanker('/sandboxes/' + sandboxId + '/memory', {
  method: 'POST',
  token: sandboxToken,
  body: {
    key: 'issue-482-handoff',
    scope: 'workflow',
    value: 'Repo test run finished. Summarize failing files and ask before opening a PR.',
  },
})

CI smoke check

Run a build and test pass, then append a trace event that a dashboard or follow-up agent can read.

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 $REPO_URL repo && cd repo && npm ci && npm run build && npm test",
    "timeoutSeconds": 120
  }'

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/traces" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "type": "ci.smoke",
    "summary": "Build and test command finished. Review command output before opening a PR.",
    "level": "info"
  }'

Approval-gated publish

Create an approval before publishing a public simple-static report or compatibility-tested preview. Use an active Clanker DevOps or Clanker Secretary account token for the hosted output.

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 run report",
    "summary": "Publish the generated report as a static page from this sandbox.",
    "risk": "low",
    "status": "pending"
  }'

# After approval, use an active Clanker DevOps or Clanker Secretary account token for the hosted output.
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
  }'

Scheduled ops report

Store the scheduled report intent and steps with the sandbox so recurring work has a durable run record.

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/workflows" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "name": "weekly ops report",
    "trigger": "schedule:weekly",
    "approvalMode": "before_publish",
    "metadata": {
      "owner": "ops",
      "sources": ["repo", "logs", "tickets", "cost-export"]
    },
    "steps": [
      "collect source files",
      "run checks",
      "write report",
      "ask for approval",
      "publish approved report"
    ]
  }'

Human or agent handoff

Append a final trace and short memory note so a teammate or follow-up agent can resume cleanly.

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/traces" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{
    "type": "handoff.ready",
    "summary": "Sandbox work is ready for a human or follow-up agent.",
    "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": "What changed: tests passed. What is blocked: publishing needs approval. Next step: review /platform and approve or reject the publish request."
  }'

Workflow state

Make agent runs inspectable

Read platform state

Call platform first when resuming a sandbox or showing status in a dashboard.

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

Create workflow record

Store the job name, trigger, steps, approval mode, and current status.

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 this before publishing, sending, deleting, installing, changing accounts, or touching external systems.

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 handoff memory

Traces are for event history. Memory is for short non-secret context the next agent needs.

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 outputs

Publish and explain sandbox outputs

Publish inline HTML

Active Clanker DevOps or Clanker Secretary tokens can publish public simple-static reports and status pages under the opaque-origin boundary.

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

Use sourceDir after a build step creates a static folder in the sandbox.

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 sandbox state

Active Clanker DevOps or Clanker Secretary tokens can ask for a current summary of runtime, TTL, routes, and hosted outputs.

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

Errors

Responses agents should handle

Status	Meaning	Agent behavior
401 or 403	Missing, expired, or wrong token.	Ask for the right account token or use the sandboxToken returned at create time.
402	Active paid Standard plan required for this feature.	Use a Clanker DevOps or Clanker Secretary token before calling /sites or /explain.
409	Runtime not ready, or protected environment not active.	Retry only for a provisioning runtime. For protected or sovereign profiles, complete contracted activation; do not fall back to Standard.
410	Sandbox expired.	Create a new sandbox and restart from saved external context.
429	Rate limited.	Back off and avoid parallel command floods.

Reference

Keep nearby

Sandbox API reference

The concise product API page with route tables and lifecycle rules.

Cloud for Agents

How sandboxes, workflow state, approvals, and hosted outputs fit together.

MCP setup

Use MCP when the agent needs local infrastructure context from the desktop app.

FAQ

Common questions

Which token should an agent use?

Use the returned sandboxToken for an anonymous sandbox. Use an account API key for account-owned sandboxes and listing. Current hosting and /explain require an active Clanker DevOps or Clanker Secretary plan; Secretary Pro protected and sovereign creation remains blocked until activation.

Can I put secrets in sandbox memory?

No. Memory is for short non-secret handoff notes. Put secrets in the normal account, customer, or local secret boundary.

Should every LLM call create a sandbox?

No. Create a sandbox when the task needs a shell, files, a hosted workspace, workflow state, or a published output. Simple chat should stay as chat.

Next step

Need the concise reference?

Use the Sandbox API page when you want route tables and lifecycle rules without the longer examples.

Open Sandbox API Read Cloud for Agents