# PillDrops

> PillDrops (pilldrops.com) is a code-execution sandbox cloud for AI agents: isolated
> microVM/container sandboxes that safely run untrusted or AI-generated code, host
> app servers with public preview URLs, support pause/resume, and bill per second of
> compute. E2B-compatible env vars; open-source engine you can self-host.

## Get access

- Sign up at https://pilldrops.com/dashboard ($5 free credits, no card)
- Create an API key: dashboard → API keys. Auth = `Authorization: Bearer <key>`
- Env vars (SDKs + CLI resolve in this order): PILLDROPS_API_KEY / PILLDROPS_API_URL,
  then PILLDROPS_*, E2B_*, SANDBOX_* (drop-in for code written against E2B)

## Quickstart (pick one)

- Python: `pip install pilldrops` → `from pilldrops import Sandbox` →
  `Sandbox.create(template="python-3.11").run("python -c 'print(2+2)'")`
- JS/TS: `npm install @pilldrops/sdk` → `import { Sandbox } from '@pilldrops/sdk'` →
  `await Sandbox.create({ template: 'python-3.11' })`
- CLI: `curl -fsSL https://pilldrops.com/install.sh | sh` (or `npm i -g @pilldrops/cli`) →
  `pilldrops login --key <key>` → `pilldrops sandbox create --template python-3.11`
- Raw HTTP: `POST https://pilldrops.com/v1/sandboxes {"template":"python-3.11"}` →
  `POST /v1/sandboxes/{id}/exec {"cmd":"echo hi"}`

## MCP server (native agent tools)

- Remote, zero install: `claude mcp add --transport http pilldrops https://pilldrops.com/mcp`
  — discovery (tools/list) is open; the first tool call triggers OAuth sign-in in the
  browser (auto-approved if already signed in to pilldrops.com), and the token flows
  back automatically. CI/headless: skip OAuth with
  `--header "Authorization: Bearer <api-key>"`.
- Local via the CLI: `claude mcp add pilldrops -- pilldrops mcp` — uses the stored
  login, and auto-opens the browser sign-in if you're not logged in yet.
- 14 tools: create_sandbox, run_command, write_file, read_file, get_logs, get_metrics,
  start_server, pause/resume/destroy_sandbox, list_sandboxes, list_templates, get_usage
- OAuth discovery: /.well-known/oauth-protected-resource + /.well-known/oauth-authorization-server
  (dynamic client registration, S256 PKCE, public clients)

## For AI agents (important)

- Run `pilldrops ai` — the complete agent catalog: every command, JSON output contract,
  exit codes, copy-paste workflows (run code / deploy app with preview URL / debug via
  logs+ps+metrics / CI gates), and an error→remediation table. `pilldrops ai --json`
  returns it machine-structured.
- `pilldrops doctor --json` self-diagnoses auth/connectivity. `pilldrops upgrade` self-updates.
- All commands accept `--json`. Errors are `{"error","code","hint"}` on stderr.
- App preview URLs require the app to bind the injected `$PORT` env var (hardcoded
  ports are the #1 cause of preview 502s).

## API surface (Bearer auth, JSON)

- POST /v1/sandboxes — create (template|image, start, ports, env, vcpu, memory_mb,
  storage_mb, timeout, idle_timeout, runtime, public). Returns {id, status, url?, ...}.
  Previews are private by default (URL needs the returned token); pass public:true
  (CLI: --public) for a shareable preview URL that needs no token.
- GET /v1/sandboxes · GET/DELETE /v1/sandboxes/{id} — list / inspect / destroy
- POST /v1/sandboxes/{id}/exec {cmd, cwd?, timeout?} → {stdout, stderr, exit_code}
- GET|POST /v1/sandboxes/{id}/files?path= — read / write files
- POST /v1/sandboxes/{id}/pause · /resume · /timeout · /start — lifecycle
- GET /v1/sandboxes/{id}/logs · /metrics — debugging
- GET /v1/templates · /v1/usage · /v1/history — catalog, billing, past sandboxes
- Machine spec: https://pilldrops.com/openapi.json

## By use case (template → step-by-step guide)

- Code interpreter / data analysis: template `code-interpreter-v1` —
  guide https://pilldrops.com/guides/code-interpreter · https://pilldrops.com/code-interpreter
- Browser automation / scraping: template `playwright` (Chromium pre-baked) —
  guide https://pilldrops.com/guides/browser-automation · https://pilldrops.com/cloud-playwright
- Run untrusted user code: template `python-3.11` with vcpu/mem/timeout caps —
  guide https://pilldrops.com/guides/untrusted-code · https://pilldrops.com/run-untrusted-code
- Code execution API (POST code → stdout/artifacts, for LLM apps & SaaS):
  https://pilldrops.com/code-execution-api
- AI agent sandbox (filesystem, browser, Android, desktop, preview URLs — one API):
  https://pilldrops.com/ai-agent-sandbox
- Sandboxing coding agents (Docker vs VM vs microVM, honest guide):
  https://pilldrops.com/sandbox-coding-agents
- Coding agents (Claude Code, Codex, OpenCode, Amp): template `claude` etc. —
  guide https://pilldrops.com/guides/coding-agents · https://pilldrops.com/claude-code-execution
- Computer use / desktop agents: template `desktop` (Linux desktop over VNC) —
  guide https://pilldrops.com/guides/computer-use · https://pilldrops.com/computer-use-sandbox
- Full-stack app previews: template `nextjs`/`node-20` + start/ports —
  guide https://pilldrops.com/guides/app-preview
- Android / mobile E2E testing: template `android` (emulator warm-baked) —
  guide https://pilldrops.com/guides/mobile-testing · https://pilldrops.com/cloud-android-emulator
- Evals & RL rollouts at scale: template `python-3.11`, one sandbox per rollout —
  guide https://pilldrops.com/guides/evals · https://pilldrops.com/rl-environments
- CI for AI-written code: guide https://pilldrops.com/guides/ci-tests
- Custom images (any Dockerfile): guide https://pilldrops.com/guides/custom-images
- Long-running / background agents: guide https://pilldrops.com/guides/long-running
- Data pipelines / ETL: guide https://pilldrops.com/guides/data-pipeline
- Self-hosting the platform: https://pilldrops.com/self-hosted-sandbox

## Docs

- [Runnable examples repo](https://github.com/pilldrops-oss/pilldrops-examples): 8 copy-paste
  examples (code interpreter, browser automation, untrusted code, coding agent, app
  preview, evals at scale, MCP, CLI tour) — clone and run
- [SDK documentation](https://pilldrops.com/sdk): Python/JS SDKs + CLI — install, auth,
  every Sandbox method with examples, preview URLs, custom images
- [Interactive API reference](https://pilldrops.com/docs): every endpoint, live playground
- [Use-case guides](https://pilldrops.com/guides): agent patterns, CI, app hosting
- [Pricing + cost calculator](https://pilldrops.com/pricing): per-second rates