paperpod

# PaperPod

Isolated, agent-native sandboxes for code execution, live preview URLs, browser automation, 50+ tools (ffmpeg, sqlite, pandoc, imagemagick), LLM inference, and persistent memory — all via CLI or HTTP, no SDK or API keys required. Billed per second of compute usage and topup via stripe or x402.

## Quick Start

```bash
curl -X POST https://paperpod.dev/login -d '{"email":"you@email.com"}'  # Verify and get token
npm install -g @paperpod/cli
ppod login <token> && ppod help
```

## Authentication

**Step 1: Get a token**
```bash
curl -X POST https://paperpod.dev/login -d '{"email":"you@email.com"}'
# Check email → click magic link → copy token (pp_sess_...)
```

**Step 2: Use the token** (pick one method)

| Method | How | Best for |
|--------|-----|----------|
| **CLI login** | `ppod login pp_sess_...` | Everyday, Interactive use |
| **Env var** | `export PAPERPOD_TOKEN=pp_sess_...` | Scripts, CI/CD |
| **Per-request** | `-H "Authorization: Bearer pp_sess_..."` | HTTP one-shots |

Tokens expire in **15 days**. On `EXPIRED_TOKEN` error, re-authenticate via `POST /login`.

---

## CLI (Recommended)

The CLI is the easiest way to use PaperPod. It handles streaming, sessions, and reconnection automatically.

### CLI Commands

| Category | Command | Description |
|----------|---------|-------------|
| **Sandbox** | `ppod exec <cmd>` | Run shell command |
| | `ppod write <path> [file]` | Write file (stdin if no file) |
| | `ppod read <path>` | Read file |
| | `ppod ls <path>` | List directory |
| **Processes** | `ppod start <cmd>` | Start background process |
| | `ppod ps` | List processes |
| | `ppod kill <id>` | Stop process |
| **Ports** | `ppod expose <port>` | Get public URL (-q for URL only) |
| **Browser** | `ppod browser:screenshot <url>` | Capture webpage |
| | `ppod browser:pdf <url>` | Generate PDF |
| | `ppod browser:scrape <url> [sel]` | Scrape elements (default: body) |
| | `ppod browser:markdown <url>` | Extract markdown |
| | `ppod browser:content <url>` | Get rendered HTML |
| | `ppod browser:test <url> '<json>'` | Run Playwright tests |
| | `ppod browser:acquire` | Acquire reusable session |
| | `ppod browser:connect <id>` | Connect to existing session |
| | `ppod browser:sessions` | List active sessions |
| | `ppod browser:limits` | Check browser limits |
| **AI** | `ppod ai <prompt>` | Text generation |
| | `ppod ai:embed <text>` | Generate embeddings |
| | `ppod ai:image <prompt>` | Generate image |
| | `ppod ai:transcribe <audio>` | Transcribe audio |
| | `ppod ai:models` | List available AI models |
| **Code** | `ppod interpret <code>` | Rich output (charts) |
| **Memory** | `ppod mem:write <path>` | Persist data |
| | `ppod mem:read <path>` | Read persisted data |
| | `ppod mem:ls` | List memory files |
| | `ppod mem:rm <path>` | Delete from memory |
| | `ppod mem:usage` | Check quota |
| **Account** | `ppod balance` | Check credits |
| | `ppod status` | Connection info |
| | `ppod help` | Show all commands |
| | `ppod <cmd> --help` | Help for specific command |

**Update CLI:** `npm update -g @paperpod/cli`

### CLI Examples

```bash
# Execute code
ppod exec "python -c 'print(2+2)'"
ppod exec "npm init -y && npm install express"
# Start server + expose (--bind 0.0.0.0 required for public access)
ppod start "python -m http.server 8080 --bind 0.0.0.0"
ppod expose 8080  # → https://8080-{sandbox-id}-p8080_v1.paperpod.work (stable URL)
# Browser with tracing
ppod browser:screenshot https://example.com --trace debug.zip
# Persistent storage (survives sandbox reset)
echo '{"step":3}' | ppod mem:write state.json
# Built-in tools (50+ available: ffmpeg, sqlite3, pandoc, imagemagick, git, jq, ripgrep...)
ppod exec "ffmpeg -i input.mp4 -vf scale=640:480 output.mp4"  # Video processing
ppod exec "sqlite3 data.db 'SELECT * FROM users'"             # Database queries
ppod exec "convert image.png -resize 50% thumbnail.png"       # Image manipulation
```
---

## HTTP Endpoints

Use HTTP for one-shot tasks or when CLI isn't available. Run `curl https://paperpod.dev/docs` or visit https://paperpod.dev/docs for full API reference.

### Quick Reference

| Endpoint | Purpose |
|----------|---------|
| `POST /execute` | Run code (python, javascript, shell) |
| `POST /execute/stream` | Stream output (SSE) |
| `POST /files/write` | Write file |
| `POST /files/read` | Read file |
| `POST /files/list` | List directory |
| `POST /process/start` | Start background process |
| `POST /process/list` | List processes |
| `POST /expose` | Get preview URL for port |
| `POST /memory/write` | Persist data |
| `POST /memory/read` | Read persisted data |
| `POST /browser/screenshot` | Capture screenshot |
| `POST /browser/pdf` | Generate PDF |
| `POST /browser/markdown` | Extract markdown |
| `POST /ai/generate` | Text generation |
| `POST /ai/embed` | Embeddings |
| `POST /ai/image` | Image generation |
| `GET /ai/models` | List models |

### HTTP Example

```bash
# Execute shell command
curl -X POST https://paperpod.dev/execute \
  -H "Authorization: Bearer $PAPERPOD_TOKEN" \
  -d '{"code": "ls -la", "language": "shell"}'
```
---

## Capabilities

| Category | What you can do |
|----------|-----------------|
| **Code Execution** | Python, JavaScript, shell commands |
| **Processes** | Background servers, long-running jobs |
| **Preview URLs** | Expose ports → `https://8080-{sandbox-id}-p8080_v1.paperpod.work` |
| **Agent Memory** | 10MB persistent storage (R2) |
| **Browser** | Screenshots, PDFs, scraping (Playwright) |
| **AI Models** | Text, embeddings, images, transcription |
| **Files** | Read/write, git, bulk operations |

### Pre-installed Tools (50+)

| Category | Tools |
|----------|-------|
| **Runtimes** | python, node, npm, bun, pip |
| **Version Control** | git, gh (GitHub CLI) |
| **HTTP & Networking** | curl, httpie, jq, dig, ss |
| **Search & Text** | ripgrep (rg), find, sed, awk, tree |
| **Media & Docs** | ffmpeg, imagemagick, pandoc |
| **Build & Data** | make, sqlite3, tar, gzip, zip, unzip |

## Key Notes

- **Sandboxes are isolated** — each user gets their own container with a full Linux environment; you can only affect your own ephemeral sandbox
- **Sandbox is ephemeral** — use Agent Memory (`/memory/*`) for persistence
- **Working directory is `/workspace`** — relative paths like `file.txt` resolve to `/workspace/file.txt`
- **Servers must bind to `0.0.0.0`** for public access
- **Ports 3000-3010 are reserved** — use 8080, 5000, 4000, etc.
- **Browser sessions** — Each command creates an ephemeral session. Use `browser:acquire` for multi-command session reuse, `--trace` to capture Playwright traces

## Billing

**$0.0001/sec** compute + browser, **$0.02/1K neurons** AI. New accounts get **$5 free** (~14 hours), no credit card required.

## Discovery

- `ppod help` — CLI command reference
- `GET https://paperpod.dev/` — API schema (JSON)
- `GET https://paperpod.dev/docs` — Full documentation

---

## Advanced: WebSocket (not recommended for normal workflows). For programmatic integrations or custom apps, connect via WebSocket. `GET https://paperpod.dev/docs` to learn more.