SandboxDrop Docs

Deploy to a live URL with a single API request. Pay with USDC. No account required.

Quick Start

Deploy a static site

One curl command — no signup, no config:

Terminal
$ curl -X POST https://api.sandboxdrop.dev/v1/deploy \
    -H "Content-Type: application/json" \
    -d '{
      "files": {
        "index.html": "<!DOCTYPE html><html><body><h1>Hello!</h1></body></html>"
      },
      "runtime": "static"
    }'

Response • 201 Created
{
  "sandbox_id": "sb_a8f3k2x9",
  "url": "https://sb-a8f3k2x9.sandboxdrop.dev",
  "access_token": "ak_7hm2p9...",
  "status": "running",
  "cost_usdc": 0.25,
  "expires_at": "2026-02-25T14:30:00.000Z"
}

Deploy a Node.js app

Terminal
$ curl -X POST https://api.sandboxdrop.dev/v1/deploy \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sdt_live_abc123..." \
    -d '{
      "files": {
        "index.js": "Bun.serve({ port: process.env.PORT, fetch: () => new Response(\"Hello!\") })"
      },
      "runtime": "bun",
      "ttl_hours": 12,
      "resources": { "tier": "small" }
    }'

Authentication

SandboxDrop uses payment-as-auth — no API keys, no accounts. There are two ways to authenticate:

Option A: x402 Protocol

Recommended for AI agents. The API uses Coinbase's x402 protocol for machine-to-machine payments.

x402 Flow
# Step 1: Send request (no payment)
POST /v1/deploy → 402 Payment Required
Response includes PAYMENT-REQUIRED header
# Step 2: Agent wallet signs ERC-3009 authorization (USDC on Base)
Gasless for buyer — facilitator pays gas
# Step 3: Retry with payment
POST /v1/deploy + PAYMENT-SIGNATURE header → 201 Created

Works with Coinbase Agentic Wallet, any EVM wallet with USDC on Base. Client libraries like @x402/fetch handle this automatically.

Option B: Prepaid Credits

Buy credits and get a Bearer token for subsequent requests:

Purchase credits
$ curl -X POST https://api.sandboxdrop.dev/v1/credits/purchase \
    -H "Content-Type: application/json" \
    -d '{ "amount_usdc": 10.00, "refund_address": "0x..." }'

Response
{
  "credit_id": "cr_x9m2p...",
  "balance_usdc": 10.00,
  "token": "sdt_live_abc123..."
}

Then use the token in all requests: Authorization: Bearer sdt_live_abc123...

API Reference

Base URL: https://api.sandboxdrop.dev/v1

Method	Path	Description
POST	`/deploy`	Deploy files to a new sandbox
GET	`/sandbox/:id`	Get sandbox status and usage
POST	`/sandbox/:id/extend`	Extend sandbox TTL
PATCH	`/sandbox/:id/files`	Update files in a running sandbox
GET	`/sandbox/:id/logs`	Get logs (supports SSE streaming)
DELETE	`/sandbox/:id`	Terminate sandbox (refunds unused time)
GET	`/sandboxes`	List active sandboxes (credit token required)
POST	`/credits/purchase`	Buy prepaid credits
POST	`/webhooks`	Register webhook for sandbox events

POST /deploy

Deploy files to a new sandbox. Requires payment via x402 or a credit token.

Request Body

Field	Type	Default	Description
`files`	object	—	Key-value map of filepath → content
`runtime`	string	`static`	`static`, `nodejs20`, `python312`, `bun`
`ttl_hours`	int	`72`	1–168 (max 7 days)
`access.mode`	string	`token`	`token`, `ip_whitelist`, `open`
`access.allowed_ips`	string[]	`[]`	Required if mode is `ip_whitelist`
`env`	object	`{}`	Environment variables for the sandbox
`build_cmd`	string	—	Build command (e.g. `bun install`)
`start_cmd`	string	—	Start command (overrides runtime default)
`resources.tier`	string	`micro`	`micro`, `small`, `medium`, `large`

Response (201)

{
  "sandbox_id": "sb_a8f3k2x9",
  "url": "https://sb-a8f3k2x9.sandboxdrop.dev",
  "access_token": "ak_7hm2p9...",
  "ssh": { "host": "sb-a8f3k2x9.ssh.sandboxdrop.dev", "port": 2222 },
  "runtime": "static",
  "tier": "micro",
  "created_at": "2026-02-22T14:30:00.000Z",
  "expires_at": "2026-02-25T14:30:00.000Z",
  "cost_usdc": 0.25,
  "status": "running"
}

GET /sandbox/:id

Get sandbox status and real-time resource usage (CPU, memory) from the running container.

{
  "sandbox_id": "sb_a8f3k2x9",
  "status": "running",
  "url": "https://sb-a8f3k2x9.sandboxdrop.dev",
  "runtime": "static",
  "usage": { "cpu_percent": 2.5, "memory_mb": 45.2 }
}

POST /sandbox/:id/extend

Extend sandbox TTL. Requires payment or credit token.

Body: { "hours": 48 }

Returns the new expiry time and cost deducted.

PATCH /sandbox/:id/files

Update files in a running sandbox without redeploying. Files are injected into the running container instantly.

Request body
{
  "files": { "index.html": "<h1>Updated!</h1>" },
  "delete": ["old-file.css"]
}

GET /sandbox/:id/logs

Get sandbox logs. Combines system events with container stdout/stderr.

Query params: ?tail=100 (last N lines) • ?stream=true (SSE stream)

When stream=true, the endpoint returns a Server-Sent Events stream. Each event has event: log with a JSON data payload containing timestamp, level, message, and source (system or container).

DELETE /sandbox/:id

Terminate a sandbox. The Docker container is stopped and removed. Unused time is refunded proportionally to the credit balance.

{
  "sandbox_id": "sb_a8f3k2x9",
  "status": "terminated",
  "refund_usdc": 0.18
}

GET /sandboxes

List all sandboxes associated with your credit token. Requires Authorization: Bearer sdt_live_...

POST /credits/purchase

Purchase prepaid credits. Returns a sdt_live_ Bearer token.

Body: { "amount_usdc": 10.00, "refund_address": "0x..." }

POST /webhooks

Body: { "url": "https://...", "events": ["sandbox.ready", "sandbox.expiring", "sandbox.terminated"] }

Runtimes

Choose the runtime for your sandbox. All runtimes run on an oven/bun:1.1-alpine base image with runtime-specific behavior injected.

Runtime	Description	Default CMD
static	Static HTML/CSS/JS site. Served by a built-in Bun file server.	Built-in static server
nodejs20	Node.js/Bun-compatible apps. Run any JS/TS server.	`bun run /app/index.js`
python312	Python apps (requires `start_cmd`).	`bun run /app/index.js`
bun	Native Bun applications with TypeScript support.	`bun run /app/index.ts`

The entry file is auto-detected from your files map. For bun, it checks index.ts, index.js, server.ts, server.js in order. For nodejs20, it checks index.js, index.ts, server.js, server.ts. Use start_cmd to override. Use build_cmd for a build step (e.g. bun install). Your app should listen on PORT.

Pricing

Pay per sandbox. Unused time refunded on early termination.

Tier	Resources	Price	72h cost
Static	HTML/CSS/JS only	$0.25 flat	$0.25
Micro	0.25 vCPU • 256 MB	$0.005/hr	$0.36
Small	0.5 vCPU • 512 MB	$0.01/hr	$0.72
Medium	1 vCPU • 1 GB	$0.03/hr	$2.16
Large	2 vCPU • 2 GB	$0.08/hr	$5.76

Webhooks

Register webhook URLs to receive notifications about sandbox lifecycle events. Delivery uses exponential backoff with up to 3 retries.

Events

Event	When	Payload
`sandbox.ready`	Container is running	`{ url, runtime, tier }`
`sandbox.expiring`	10 minutes before TTL expires	`{ expires_at }`
`sandbox.terminated`	Sandbox stopped (expired, deleted, or failed)	`{ reason, refund_usdc }`

Webhook delivery payload

{
  "event": "sandbox.ready",
  "sandbox_id": "sb_a8f3k2x9",
  "timestamp": "2026-02-22T14:30:00.000Z",
  "data": { "url": "https://sb-a8f3k2x9.sandboxdrop.dev", ... }
}

MCP Integration

AI coding tools (Claude Code, Cursor, Cline) can deploy directly via the MCP server.

MCP Config (claude_desktop_config.json)
{
  "mcpServers": {
    "sandboxdrop": {
      "url": "https://mcp.sandboxdrop.dev/sse",
      "env": {
        "SANDBOXDROP_CREDIT_TOKEN": "sdt_live_abc123..."
      }
    }
  }
}

Available MCP tools

Tool	Description
`deploy_sandbox`	Deploy files to a new sandbox
`get_sandbox_status`	Check sandbox status and usage
`update_sandbox_files`	Hot-update files in a running sandbox
`get_sandbox_logs`	Retrieve sandbox logs
`extend_sandbox`	Extend sandbox TTL
`delete_sandbox`	Terminate a sandbox
`list_sandboxes`	List all active sandboxes

SDK & CLI

CLI

$ npx sandboxdrop deploy ./my-project --runtime nodejs20 --ttl 24h

Node.js SDK

JavaScript
import { SandboxDrop } from 'sandboxdrop';
const sd = new SandboxDrop(); // uses x402, no key needed
const sandbox = await sd.deploy({
  files: { 'index.html': '<h1>Hello</h1>' },
  runtime: 'static',
  ttl_hours: 24
});
console.log(sandbox.url);

Python SDK

Python
from sandboxdrop import SandboxDrop
sd = SandboxDrop()
sandbox = sd.deploy(
    files={"index.html": "<h1>Hello</h1>"},
    runtime="static",
    ttl_hours=24
)
print(sandbox.url)

Security

Every sandbox runs in an isolated Docker container with strict resource limits and security hardening:

Control	Detail
Capabilities	All capabilities dropped. Only `NET_BIND_SERVICE`, `CHOWN`, `SETUID`, `SETGID`, `DAC_OVERRIDE` added back.
Privilege	`no-new-privileges` flag set. Not a privileged container.
PID limit	Max 64 processes per container.
Memory	Hard cap per tier (256 MB – 2 GB). Swap disabled.
CPU	CPU quota per tier (0.25 – 2 vCPU) via NanoCpus.
Filesystem	`/tmp` is tmpfs (noexec, nosuid, 512 MB).
Network	Outbound SMTP blocked. HTTP rate-limited. Inbound via proxy only.
Abuse prevention	Payment barrier ($0.25+ per sandbox). Content scanning. IP reputation.