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 && pi

Provision 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 /theme and /tint commands (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

Never delete /workspace/.piclaw/store/messages.db — it holds all chat history, media, and tasks.

Key environment variables:

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 piclaw

Tests 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 CI

PiClaw works with any OCI-compliant runtime:

• Docker / Docker Desktop — primary target
• Apple Containers (macOS 26+)
• Podman, nerdctl, etc.

MIT