Local API Reference

Control Coding Sandbox programmatically via the REST API running locally on your machine.

Overview

Coding Sandbox exposes a local REST API that lets you manage sandboxes, tunnels, and snapshots programmatically. The API runs on your machine and communicates directly with your local Docker environment — no internet connection required for core operations.

Base URL (default):

http://localhost:8090/api

Local only

This API runs entirely on your local machine. It is not the same as the cloud API at api.coding-sandbox.dev which handles account and billing. The local API controls your Docker sandboxes directly.

Enabling the API

The local API is disabled by default. To enable it:

Open Coding Sandbox
Go to Settings
Under Local API, toggle Enable API server
Optionally change the port (default: 8090)

You can also enable it via the CLI:

bash

csb config set api.enabled true

Authentication

By default, the local API does not require authentication since it only listens on localhost. You can optionally enable API key authentication in Settings:

bash

# With authentication enabled
curl -H "Authorization: Bearer csb_local_your_key" \
  http://localhost:8090/api/sandboxes

Security

If you expose the API to your local network, we recommend enabling authentication. The API key can be generated and rotated in Settings > Local API.

Health & Status

Health Check

bash

GET /api/health

Response

{
  "status": "ok",
  "docker": "connected",
  "uptime": 3600
}

Version

bash

GET /api/version

Response

{
  "version": "1.2.0",
  "api_version": "v1",
  "platform": "darwin-arm64"
}

Resource Usage

Returns aggregate resource usage across all running sandboxes.

bash

GET /api/resources

Response

{
  "cpu_percent": 12.5,
  "memory_mb": 1024,
  "memory_limit_mb": 8192,
  "disk_mb": 4500,
  "running_containers": 3
}

Sandboxes

List Sandboxes

bash

GET /api/sandboxes

Returns all sandboxes with their current status.

Response

{
  "data": [
    {
      "id": "sbx_abc123",
      "name": "my-claude-project",
      "agent": "claude",
      "status": "running",
      "cpu_percent": 4.2,
      "memory_mb": 256,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Create Sandbox

bash

POST /api/sandboxes

Request body

{
  "name": "my-project",
  "agent": "claude",
  "tunnel": false,
  "ports": ["3000:3000", "8080:8080"],
  "env": {
    "ANTHROPIC_API_KEY": "sk-..."
  }
}

Parameters:

name (required) — Unique sandbox name
agent (required) — Agent type: claude, codex, copilot, gemini, kiro, opencode, cagent
tunnel — Enable tunnel on creation (default: false)
ports — Port mappings in host:container format
env — Environment variables to inject

Get Sandbox

bash

GET /api/sandboxes/:id

Returns detailed information about a specific sandbox including resource usage and tunnel status.

Start Sandbox

bash

POST /api/sandboxes/:id/start

Starts a stopped sandbox.

Stop Sandbox

bash

POST /api/sandboxes/:id/stop

Gracefully stops a running sandbox. Use ?force=true to force kill.

Delete Sandbox

bash

DELETE /api/sandboxes/:id

This permanently deletes the sandbox and all its data. This action cannot be undone.

Tunnels

Enable Tunnel

bash

POST /api/sandboxes/:id/tunnel

Creates a secure Cloudflare tunnel for the sandbox. Returns the tunnel URL.

Response

{
  "tunnel_url": "https://abc123.trycloudflare.com",
  "status": "active",
  "expires_at": "2026-03-14T16:30:00Z"
}

Disable Tunnel

bash

DELETE /api/sandboxes/:id/tunnel

Disconnects the tunnel. The sandbox continues running locally.

Get Tunnel Info

bash

GET /api/sandboxes/:id/tunnel

Returns the current tunnel status and URL for a sandbox.

Snapshots

List Snapshots

bash

GET /api/sandboxes/:id/snapshots

Response

{
  "data": [
    {
      "id": "snap_xyz789",
      "name": "before-refactor",
      "size_mb": 128,
      "created_at": "2026-03-14T10:00:00Z"
    }
  ]
}

Create Snapshot

bash

POST /api/sandboxes/:id/snapshots

Request body

{
  "name": "before-refactor"
}

Restore Snapshot

bash

POST /api/sandboxes/:id/snapshots/:snapshot_id/restore

Restoring a snapshot replaces the current sandbox state. The sandbox will be restarted.

Delete Snapshot

bash

DELETE /api/sandboxes/:id/snapshots/:snapshot_id

Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body:

Error response

{
  "error": {
    "code": "sandbox_not_found",
    "message": "No sandbox found with the given ID."
  }
}

Common status codes:

200 — Success
201 — Created
400 — Bad request (invalid parameters)
401 — Unauthorized (if authentication is enabled)
404 — Resource not found
409 — Conflict (e.g., sandbox name already exists)
500 — Internal server error
503 — Docker not available

Settings

CLI Reference