PiClaw is a Docker-based sandbox for running the Pi Coding Agent in an isolated Debian environment. It bundles piclaw — a web-first orchestrator built on the Pi SDK with persistent sessions, a streaming web UI, and scheduled tasks. WhatsApp is optional. Inspired by agentbox and nanoclaw.
- Streaming web UI — real-time token-by-token updates over SSE, with Markdown, KaTeX, and Mermaid rendering
- Workspace explorer — file tree sidebar with previews, file reference pills, and downloads
- Disk usage starburst — folder-size visualization with hover details and drill-down
- Code editor — built-in CodeMirror 6 with syntax highlighting for 12 languages, search/replace, and save
- Persistent storage — SQLite-backed messages, media, tasks, token usage, and encrypted keychain
- Skills — setup, debugging, Playwright, scheduling, charts, web search, and more
- Passkeys + TOTP authentication — optional WebAuthn passkeys with TOTP fallback (iOS/Android webapp support)
- WhatsApp — optional secondary channel
make build # Build the Docker image
make up # Start the container (supervisord launches piclaw)Open http://localhost:8080 in your browser. To use pi interactively instead:
docker exec -u agent -it piclaw bash
cd /workspace && piProvision provider credentials via /shell <command> in the web UI or docker exec with pi /login. See docs/configuration.md for details.
The UI is single-user, mobile-friendly, and streams updates over SSE:
- Thought/Draft panels — visible during streaming
- Live steering — send follow-ups while the agent is still responding
- File attachments with download links
- Link previews via server-side OpenGraph fetch
- Multi-turn threading — subsequent turns are visually threaded under the first
- Themes + tinting — presets plus
/themeand/tintcommands (Solarized auto light/dark) - Mobile-first layout with webapp manifest
The sidebar shows a file tree of /workspace with auto-refresh. Click a file to preview it or add a file reference pill to the next prompt. Drag and drop files onto the tree to upload them. It also includes a folder-size starburst preview with hover details and drill-down.
Click the pencil icon on any text file preview (up to 256 KB) to open the built-in editor. It appears as a resizable centre pane between the sidebar and the chat.
- 12 languages — JS/TS (JSX/TSX), Python, Go, JSON, CSS, HTML, YAML, SQL, XML/SVG, Markdown, Shell
- Search and replace — Cmd/Ctrl+F and Cmd/Ctrl+H
- Save — Cmd/Ctrl+S or the Save button; dirty state is tracked
- Line wrapping, line numbers, and active line highlight
- Vendored bundle (~245 KB gzip) — no external CDN dependencies
| Mount | Container path | Contents |
|---|---|---|
| Home | /config |
Agent home (.pi/, .gitconfig, .bashrc) |
| Workspace | /workspace |
Projects, piclaw state, notes |
Never delete /workspace/.piclaw/store/messages.db — it holds all chat history, media, and tasks.
Key environment variables:
| Variable | Default | Purpose |
|---|---|---|
PICLAW_WEB_PORT |
8080 |
Web UI port |
PICLAW_WEB_TOTP_SECRET |
(empty) | Base32 TOTP secret; enables login gate |
PICLAW_WEB_PASSKEY_MODE |
totp-fallback |
Passkey mode: totp-fallback, passkey-only, or totp-only |
PICLAW_ASSISTANT_NAME |
PiClaw |
Display name in the UI |
PICLAW_KEYCHAIN_KEY |
(empty) | Master key for encrypted secret storage |
For the full list (TLS, reverse proxies, timeouts, Pushover, WhatsApp, keychain, external workspaces), see docs/configuration.md.
If piclaw is running behind a reverse proxy or tunnel (for example Cloudflare Tunnel, Caddy, or Nginx TLS termination), enable proxy trust so origin checks and absolute URL generation use the external host/proto:
or in .piclaw/config.json:
{ "web": { "trustProxy": true
}
}Your proxy should forward either the standard Forwarded header or the usual X-Forwarded-Host / X-Forwarded-Proto headers.
make build-piclaw # Full build: vendor bundle + web assets + TypeScript
make vendor # Rebuild CodeMirror vendor bundle only
make lint # ESLint
make test # Run all tests
make local-install # Pack, install globally, and restart piclawTests use the Bun runner (cd piclaw && bun test). Sequential mode is recommended for SQLite safety (--max-concurrency=1).
Pushing a version tag triggers .github/workflows/publish.yml — multi-arch builds (amd64 + arm64) published to GHCR.
make bump-patch # bump patch version, commit, and tag
make bump-minor # bump minor version, commit, and tag
make push # push commits + tag → triggers CIPiClaw works with any OCI-compliant runtime:
- Docker / Docker Desktop — primary target
- Apple Containers (macOS 26+)
- Podman, nerdctl, etc.
MIT
