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

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

Authentication

Step 1: Get a token

curl -X POST https://paperpod.dev/login -d '{"email":"[email protected]"}'
# 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

# 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

# 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.