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":"you@email.com"}'  # 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":"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

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