Founder Guide

Everything about how SandboxDrop works, from architecture to deployment.

01 Project Overview

SandboxDrop is a zero-signup ephemeral hosting platform for AI agents and developers. The core idea:

• One API request deploys code to a live URL with a real Docker container behind it
• Payment-as-auth via the x402 protocol (Coinbase) — no accounts, no API keys, no signup
• Auto-expiring sandboxes with configurable TTL (1 hour to 7 days)
• Built for AI agents that need to deploy autonomously (Claude Code, Cursor, Devin)

Target market: AI coding agents, developers needing quick previews, CI/CD preview environments, coding education.

Revenue model: Per-sandbox pricing in USDC. Static sites at $0.25 flat, compute sandboxes from $0.005/hr to $0.08/hr depending on resources.

02 Architecture

Key design decisions

• Single Hono app — all routes under one new Hono() to avoid body-stream consumption issues with nested routers
• Host networking (dev mode) — containers listen directly on random host ports (10000-60000). Production should use bridge networking with iptables.
• Single base image — all runtimes use oven/bun:1.1-alpine. Runtime-specific behavior is injected via server scripts at container creation time. No custom images to build.
• Manual JSON parsing on deploy endpoint — avoids Hono's zValidator body-stream issues in certain middleware chains

03 Tech Stack

04 Container Provisioning

Every sandbox gets its own Docker container. The provisioning flow:

1. API receives deploy request with files, runtime, and tier
2. Docker container created from oven/bun:1.1-alpine base image
3. Resource limits applied (CPU, memory, PIDs) based on tier
4. Files injected via tar archive into /app directory
5. Build command executed (if provided) via docker exec
6. Container started with runtime-specific CMD
7. Host port registered in proxy mapping

Runtime behavior

Security hardening

Note: Bridge networking (with explicit port bindings) is used instead of host networking. Host networking doesn't work on Docker Desktop for macOS/Windows since containers run inside a VM. Each container listens on port 3000 internally, mapped to a random host port (10000–60000).

File injection

Files are injected into containers using a custom tar archive builder. The system builds a proper POSIX tar archive in memory:

• Creates directory entries for nested paths
• Sets proper permissions (0644 for files, 0755 for directories)
• Computes checksum per tar header block
• Uses container.putArchive() to inject into /app

Hot file updates (PATCH /sandbox/:id/files) use the same tar injection for new/updated files, and docker exec rm -f for deleted files.

05 Database Schema

6 tables managed by Drizzle ORM, plus 4 enums:

Enums

• sandbox_status: provisioning, running, stopped, terminated
• runtime: static, nodejs20, python312, bun
• tier: micro, small, medium, large
• access_mode: token, ip_whitelist, open

ID format

• sb_ — sandbox IDs (10-char nanoid)
• cr_ — credit IDs
• sdt_live_ — credit Bearer tokens (32-char)
• ak_ — sandbox access tokens

06 Payment Flow

x402 Protocol (Coinbase)

SandboxDrop uses x402 V2 for payment-as-auth on Base network (USDC). The flow:

1. Client sends POST /v1/deploy without payment headers
2. x402 middleware returns 402 Payment Required with PAYMENT-REQUIRED header
3. Client wallet signs an ERC-3009 transferWithAuthorization (EIP-712 typed data)
4. Client retries with PAYMENT-SIGNATURE header
5. Facilitator verifies signature and settles payment (pays gas on behalf of buyer)
6. Server returns resource with PAYMENT-RESPONSE header

Credit system

Alternative to x402. User purchases credits via POST /credits/purchase, receives a sdt_live_ Bearer token.

• Credit deduction on deploy and extend operations
• Prorated refund on early termination: refund = (unused_hours / total_hours) * cost
• Minimum transaction: $0.10 USDC

07 API Routes

All routes are mounted under /v1 in a single Hono app. The middleware chain:

Deploy flow (POST /deploy)

1. Parse and validate JSON body with Zod schema
2. Check credit balance (if Bearer token) or let x402 handle payment
3. Deduct credits from balance
4. Insert sandbox record in DB (status: provisioning)
5. Store files in sandbox_files table
6. Call createContainer() to provision Docker container
7. Update DB with container_id and container_port (status: running)
8. Register port mapping in reverse proxy
9. Fire sandbox.ready webhook (non-blocking)
10. Return sandbox details to client

On failure: marks sandbox as terminated, refunds credits, returns error detail.

08 Reverse Proxy

A separate Bun.serve() instance runs on port 4001 (configurable via PROXY_PORT). It routes sandbox URLs to containers.

1. Extracts sandbox ID from Host header: sb-XXXX.sandboxdrop.dev → sb_XXXX
2. Looks up host port in in-memory map (fast path)
3. Falls back to DB lookup if not in memory
4. Proxies request to http://127.0.0.1:{port}
5. Adds X-Sandbox-Id header to response

Important: The API server (port 4000) and the proxy (port 4001) are separate servers. To access a sandbox via its URL locally, always use the proxy port:

In production, this sits behind Caddy or Traefik for TLS termination and wildcard certificate handling.

09 Background Workers

Expiry worker

Runs every 30 seconds. Two jobs:

1. Expire sandboxes: Finds sandboxes where expires_at < now and status != terminated. Terminates Docker container, updates DB, fires sandbox.terminated webhook.
2. Expiry warnings: Finds running sandboxes expiring within 10 minutes. Fires sandbox.expiring webhook.

10 Webhook Delivery

When a lifecycle event occurs, the system:

1. Looks up the sandbox's credit token
2. Finds all webhooks registered to that credit token matching the event type
3. Delivers payload via POST with Content-Type: application/json
4. Retries up to 3 times with exponential backoff (1s, 2s, 4s delays)

Events

11 Testing & CI

31 tests across 4 files, all passing:

CI Pipeline

GitHub Actions workflow (.github/workflows/ci.yml):

• PostgreSQL service container
• Bun install + schema push
• Unit tests: bun test tests/pricing.test.ts tests/ids.test.ts
• Integration tests: starts server, runs bun test tests/api.test.ts
• TypeScript check: bunx tsc --noEmit

12 Development Setup

Environment variables

Debugging containers

Sandbox containers use labels prefixed with sandboxdrop. — use the full label key when filtering:

13 Domains & Infrastructure

14 Feature Status

15 Roadmap

Next priorities

1. Production deployment — TLS via Caddy/Traefik, bridge networking with iptables, proper DNS wildcard
2. SSH bastion — SSH access to running containers on port 2222 via bastion host
3. MCP server — Enable AI tools (Claude Code, Cursor) to deploy directly
4. Dynamic x402 pricing — Price x402 payments per tier instead of flat $0.25
5. SDK packages — Publish sandboxdrop to npm and pypi
6. Multipart deploy — Accept zip/tar.gz uploads alongside JSON file maps
7. Content scanning — Automated abuse detection and content policy enforcement
8. Dashboard — Optional web UI for credit token holders to manage sandboxes