PiClaw packages the Pi Coding Agent into a self-hosted workspace with a streaming web UI, multi-provider LLM support, persistent state, and a growing collection of built-in tools — code editor, terminal, VNC client, document viewers, kanban boards, and autonomous experiment loops.
It is built for people who want a practical, stateful agent they can run locally or in a container without stitching together half a dozen separate services.
- Streaming web UI — real-time chat with Markdown, KaTeX, Mermaid, and Adaptive Cards
- Persistent agent state — SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH / Proxmox / Portainer profiles
- Workspace-native workflow — browse files, preview documents, upload attachments, drag files into the workspace explorer with progress feedback and a client-side size guard, edit code, reference files in prompts, and optionally flip core tools to a remote SSH host for the current session
- Built-in tools — Ghostty-based terminal, code editor, Office/PDF/CSV/image/video viewers, draw.io, kanban board and mindmap editors, VNC client, browser automation, sharp-backed image processing, bundled MCP access via
pi-mcp-adapter, and agent-only infrastructure tools for SSH, Proxmox, and Portainer - Visual artifact generation — agent-driven HTML pages, architecture diagrams, data tables, diff reviews, slide decks, and draw.io files using vendored Mermaid, ECharts, D3, and KaTeX libraries with a consistent visual-design profile (adapted from nicobailon/visual-explainer)
- Agent control features — steering, queued follow-ups, threading, side prompts, autoresearch experiment loops, and scheduled tasks
- Context conservation by default — small always-active tool baseline, staged tool/script discovery via
list_tools/list_scripts(filtered or intent-guided discovery → compact summary → on-demand detail → activate/use), lazy activation for non-default tools, and opt-in examples for higher-detail workflow help - Optional auth and channels — passkeys/TOTP for the web UI, plus optional WhatsApp integration
mkdir -p ./home ./workspace
docker run -d \
--init \
--name piclaw \
--restart unless-stopped \
-p 8080:8080 \
-e PICLAW_WEB_PORT=8080 \
-v "$(pwd)/home:/config" \
-v "$(pwd)/workspace:/workspace" \
ghcr.io/rcarmo/piclaw:latestOpen http://localhost:8080 and type /login to configure your LLM provider, including custom OpenAI-compatible endpoints when you are not using one of the built-in hosted providers.
Tip
Keep --init enabled for docker run / podman run so the runtime inserts a tiny init process for signal forwarding and zombie reaping. The bundled docker-compose.yml now sets the equivalent init: true flag.
| Mount | Container path | Contents |
|---|---|---|
| Home | /config |
Agent home (.pi/, .gitconfig, .bashrc) |
| Workspace | /workspace |
Projects, notes, and piclaw state |
Note
In the container image, /home/agent/.pi is backed by /config/.pi. With the stock docker run / docker-compose.yml examples above, Pi home state therefore persists on the host under ./home/.pi/agent/.
That means provider login state and model metadata should survive rebuilds/recreates when stored under files such as:
./home/.pi/agent/auth.json./home/.pi/agent/models.json
Mounting directly to /home/agent or /home/agent/.pi/agent can also work, but /config is the canonical documented persistence path for the container image.
Warning
Never delete /workspace/.piclaw/store/messages.db. It contains chat history, media, and task state.
Important
You do not need to set provider API keys in piclaw environment variables. PiClaw reuses provider credentials configured in Pi Agent settings.
Note
Power users can place workspace-scoped shell environment overrides in /workspace/.env.sh. PiClaw sources that file for the embedded terminal and on runtime startup, which is useful for things like PATH tweaks or persisting gh auth login with GH_CONFIG_DIR=/workspace/.config/gh. This hook is user-controlled: if its contents break PiClaw startup, shell behavior, or tool resolution, that breakage is the user's responsibility.
PiClaw is single-user, mobile-friendly, and streams updates over SSE.
- Thought and draft panels during streaming
- Live steering and queued follow-ups
- Adaptive Cards with persisted submissions
/btwside conversations- File attachments, link previews, threaded turns, and syntax-highlighted previews for common text/code attachments
- Themes and tinting via
/themeand/tint - Mobile-friendly layout with webapp manifest
- Sidebar file browser with auto-refresh, drag-and-drop upload progress, and a client-side 256 MB upload guard before the request even starts
- File-reference pills in prompts
- Folder sizes in the starburst explorer
- Workspace search index status with one-click reindex from the explorer header
- CodeMirror 6 with syntax highlighting for JS/TS, Python, Go, JSON, CSS, HTML, YAML, SQL, XML/SVG, Markdown, and Shell
- Search and replace, dirty-state tracking, line wrapping
- Lazy-loaded local bundle — no CDN dependency
- Ghostty-based web terminal — a real shell in the browser, not a simulation
- Runs as a dock panel or a standalone tab
- Detachable into popout windows with live session transfer
- Enabled by default on Linux and macOS; disable with
PICLAW_WEB_TERMINAL_ENABLED=0 - Still disabled by default on Windows
- Draw.io — self-hosted editor with SVG/PNG/XML export back to workspace
- Office documents —
.docx,.xlsx,.pptx,.odt,.ods,.odp - CSV/TSV — dedicated table viewer
- PDF, images, video — inline viewers
- Text/code attachments — syntax-highlighted timeline preview modal for common code/config formats
- Kanban boards —
*.kanban.mdin a drag-and-drop board editor (Obsidian Kanban compatible) - Mindmaps —
*.mindmap.yamlin a D3/SVG visual editor - VNC remote display — connect to allowlisted targets from a tab, with direct-connect enabled by default on Linux, macOS, and Windows (experimental); disable with
PICLAW_WEB_VNC_ALLOW_DIRECT=0
/imageand/flux— workspace-backed image generation commands for Azure OpenAI / Foundry;/imagenow supports--transparentfor transparent PNG output when the Azure OpenAI model supports itimage_process— sharp-backed workspace image manipulation for resize/crop/convert/optimise, metadata inspection, text/SVG/composite operations, and animated GIF frame/spritesheet workflowscdp_browser— Chromium/Edge/Chrome automation via CDP for navigation, JS evaluation, DOM clicking, and screenshotsmcpviapi-mcp-adapter— token-efficient access to external MCP servers configured through.pi/mcp.json- Experimental
m365extension — opt-in Microsoft 365 automation bundle for Teams, Graph, OneDrive, SharePoint, and calendar flows; enable withPICLAW_ENABLE_M365_EXPERIMENTAL=1(primarily validated on Windows with YOLO mode, with Edge → Chrome → Chromium browser lookup across Windows/macOS/Linux). Graph-backed consumer-account support now exists; Teams chat flows still require a work/school tenant, and the auth/browser reuse path now follows the current Teams web-app entry instead of the stale legacy route. win_*tools — Windows-only desktop automation via Win32 FFI for window enumeration, screenshots, element inspection, clicking, typing, and process management. No-ops on non-Windows platforms.
Key environment variables:
| Variable | Default | Purpose |
|---|---|---|
PICLAW_WEB_PORT |
8080 |
Web UI port |
PICLAW_WEB_TERMINAL_ENABLED |
1 on Linux/macOS, 0 on Windows |
Enable or disable the authenticated Ghostty-based web terminal |
PICLAW_WEB_VNC_ALLOW_DIRECT |
1 on Linux/macOS/Windows |
Allow or disable direct VNC targets supplied at runtime |
PICLAW_WEB_TOTP_SECRET |
(empty) | Base32 TOTP secret; enables login gate (or initialize with /totp) |
PICLAW_WEB_PASSKEY_MODE |
totp-fallback |
totp-fallback, passkey-only, or totp-only |
PICLAW_ASSISTANT_NAME |
PiClaw |
Display name in the UI |
PICLAW_ENABLE_M365_EXPERIMENTAL |
0 |
Enable the experimental Microsoft 365 extension bundle |
PICLAW_KEYCHAIN_KEY |
(empty) | Master key for encrypted secret storage |
PICLAW_TRUST_PROXY |
0 |
Enable when behind a reverse proxy or tunnel |
For the full list, auth setup (TOTP/passkeys), session-scoped SSH-backed remote tools, reverse proxy configuration, and SSHFS/FUSE support, see docs/configuration.md.
bun add -g github:rcarmo/piclawExperimental. Linux/macOS/Windows. See docs/install-from-repo.md.
On Windows, PiClaw remains a secondary / not-officially-supported target. Shell-like child processes now run attached there (detached=false) so stdout/stderr remain capturable; Unix-like hosts still use detached process groups for cleaner tree termination on abort/shutdown.
See docs/development.md.
Setup & operations
- Configuration — environment variables, auth, reverse proxy, SSHFS
- Install from repo — Bun-based Docker-free install
- Azure VM deployment — provisioning, systemd service, Caddy reverse proxy, managed-identity
- Reverse proxy — Caddy, nginx, Cloudflare Tunnel, and trusted-proxy config
- Release process — versioning, tagging, publishing
Architecture & internals
- Architecture
- Runtime flows
- Storage model
- Web pane extensions
- Extension UI contract
- Vendored widget libraries — Babylon.js, ECharts, D3, Mermaid, fonts, and the widget post-processing helpers
- Visual artifact generator — skill for generating polished HTML pages, diagrams, tables, slide decks, and draw.io files from vendored libraries
- Dream memory system — nightly memory consolidation and daily note maintenance
- Web notification delivery policy
- iOS PWA reference — viewport, safe area, and standalone-mode quirks
Reference
- Tools and skills — includes the uniform
ssh/proxmox/portainercontrol surface (discover,capabilities,recommend,request,workflow) and the context-conserving discovery flow - Keychain
- Cross-instance interop
- MCP via pi-mcp-adapter
- Azure OpenAI extension — managed-identity provider notes plus
/imageand/fluxbehaviour - Experimental M365 extension — Microsoft 365 browser-auth automation, including current consumer-account support boundaries
- Development
Platform studies
- Azure Functions feasibility study — detailed analysis of running Piclaw entirely on Azure Functions (verdict: not recommended)
- rcarmo/agentbox
- qwibitai/nanoclaw
- badlogic/pi-mono
- davebcn87/pi-autoresearch — autonomous experiment loop by Tobi Lutke and David Cortés (vendored under
runtime/vendor/autoresearch/) - nicobailon/visual-explainer — visual artifact generation skill philosophy, prompt workflow, and template patterns by Nico Bailon (adapted, not vendored)
MIT