How to Use Clanker Cloud Sandboxes for AI Agents

Clanker Cloud sandboxes are hosted workspaces for agents. They give Codex, Claude Code, OpenClaw, Hermes, Clanker CLI, or a custom agent a real shell and workspace before the user installs the desktop app or connects production credentials.

The short version:

• Anonymous sandboxes are for quick trials and last one hour.
• Free authenticated sandboxes are for normal work sessions and last about eight hours.
• Standard Pro sandboxes persist until deleted.
• Standard Pro also unlocks public simple-static hosted sites and /explain.
• The desktop app and MCP path remain the right place for local cloud credentials, live provider context, and reviewed production actions.

Current /sites/{slug}/ documents are forced into a Content Security Policy sandbox without allow-same-origin, giving each page an opaque browser origin. This blocks shared cookies, localStorage, IndexedDB, Cache Storage, service workers, and readable same-origin API responses. Classic scripts and forms can work, but ES modules and storage- or API-dependent apps may fail. Protected, sovereign, and government hosting is not available until per-site tenant-isolated registrable origins and a separately contracted, verified environment exist.

That split is the point. Use a sandbox when an agent needs an isolated runtime. Use Clanker Cloud MCP when the agent needs the user's real infrastructure context.

When To Use An Agent Sandbox

Use a Clanker Cloud sandbox when the agent needs somewhere safe to:

• clone a repository and inspect files;
• run shell commands without touching the user's laptop;
• generate a deploy plan before asking for production access;
• test scripts, package installs, build commands, or small services;
• create a status page, static preview, or run summary;
• hand a user an environment that can be claimed or deleted cleanly.

Do not treat the sandbox as a replacement for the local-first Clanker Cloud app. The sandbox is intentionally separate from the machine that holds cloud provider credentials, kubeconfigs, local files, and approval authority.

For production infrastructure work, the clean flow is:

1. Start in a sandbox for setup, dependency checks, repo inspection, and draft planning.
2. Move to the Clanker Cloud desktop app and MCP for live AWS, Kubernetes, GCP, Azure, GitHub, cost, and topology context.
3. Keep high-impact infrastructure changes behind reviewed plans and explicit approval.

Pick The Right Auth Mode

Caller	Lifetime	Best use
Anonymous	1 hour	Fast trial, short agent setup, disposable command run.
Free authenticated account	About 8 hours	A normal work session attached to an account.
Standard Pro account	Persistent until deleted	Reusable agent workspaces, public simple-static hosted sites, /explain, team workflows.

Agents and users can both create accounts through the API. Human users call /api/auth/register. Agents call /api/auth/agent/register.

1. Start An Anonymous Sandbox

This creates a one-hour sandbox and returns a sandboxToken. Save both the sandbox id and token. Anonymous sandboxes are not listed later through account APIs.

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

The response includes a box.id, sandboxToken, expiry timestamp, and claim URL.

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

Set the returned values in the agent environment:

export SANDBOX_ID="box_..."
export CLANKER_SANDBOX_TOKEN="..."

2. Run Commands Inside The Sandbox

Use the sandbox token as the API key for anonymous command execution.

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

A practical first command is a small environment probe:

curl -sS "https://clankercloud.ai/api/sandboxes/$SANDBOX_ID/commands" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_SANDBOX_TOKEN" \
  -d '{ "command": "uname -a && node --version || true && python3 --version || true" }'

After that, the agent can clone a repo, install dependencies, run tests, generate a plan, or produce artifacts that the user can inspect.

3. Create A User Account Through The API

If a human user wants account-owned sandboxes, create an account with /api/auth/register.

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

Successful creation returns an account API token and records acceptance of the current published terms.

Use the returned token for account-owned sandbox calls:

export CLANKER_CLOUD_API_KEY="..."

4. Create An Agent Account Through The API

Agents can register their own account token without collecting cloud credentials or provider keys.

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

This is useful when a remote agent needs an account-owned sandbox lifecycle but should not ask the user to install the desktop app first.

5. Create And List Account Sandboxes

Account-authenticated sandboxes are attached to the account. Free accounts get about eight hours. Paid accounts get persistent sandboxes that remain until deleted.

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 account-owned sandboxes:

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

Inspect a sandbox:

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

Delete a sandbox when the run is complete:

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

6. Publish A Hosted Site From A Standard Pro Sandbox

Standard Pro accounts can publish public static documents from inline HTML, explicit files, or a sandbox source directory. This is useful for generated status pages, one-off reports, agent handoff pages, and previews that have been tested under the current isolation boundary.

The route is not full application hosting. Documents share a Worker hostname but are forced into an opaque-origin CSP sandbox without allow-same-origin. They cannot use shared cookies, localStorage, IndexedDB, Cache Storage, or service workers, or read same-origin API responses. Classic scripts and forms remain allowed; ES modules and storage- or API-dependent applications may break. Never publish secrets, confidential customer data, PHI, criminal-justice information, or other regulated records to this public route.

Protected or government hosted sites remain unavailable until tenant-isolated registrable origins and the separately contracted environment are delivered and verified.

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

This is the website-hosting path for agent outputs. The important distinction is that the site is a result of a sandboxed agent run, not the whole product. Clanker Cloud's default unit is still the agent workspace.

7. Ask /explain What Is Running

Paid account tokens can ask a sandbox to describe its runtime, hosted site state, TTL, and active routes.

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

Agents should call /explain before handoff. It gives the user a concise answer to:

• what sandbox is running;
• when it expires or whether it is persistent;
• which routes are active;
• which hosted sites were published;
• what the agent should delete, claim, or continue.

That matters for trust. A user should not need to reconstruct sandbox state from a chat transcript.

Recommended Agent Flow

For a coding or infrastructure agent, the full flow is:

1. Call POST /api/sandboxes anonymously for a quick workspace.
2. Run basic environment checks.
3. Clone or upload the project.
4. Run tests, build commands, or discovery scripts.
5. Create a user or agent account if the work needs more time.
6. Move to Standard Pro when the workflow needs persistence, public simple-static hosted output, or /explain.
7. Use the Clanker Cloud desktop app and MCP before touching real cloud infrastructure.
8. Delete the sandbox when the work is done.

The sandbox is where an agent gets organized. The local-first Clanker Cloud app is where real infrastructure context, credentials, and approvals live.

Related Clanker Cloud Pages

• Clanker Sandboxes
• Sandbox API
• Agentic-native cloud for agents
• For AI agents
• MCP setup