PiClaw
A self-hosted, persistent Pi Coding Agent workspace with a streaming web interface and built-in developer tools.
What does this agent do, and when should you use it?
PiClaw packages Pi Coding Agent as a single-user, self-hosted AI workspace with a streaming web UI. Its interface combines chat, code editing, a terminal, file browsing, uploads, and several viewers, with updates delivered over SSE. SQLite persists messages, media, tasks, run logs, token usage, encrypted keychain entries, and session-scoped SSH profiles. It can run in Docker or be installed globally with Bun, and it also offers an experimental Electrobun desktop wrapper. The product operates as a Pi runtime and tool-enabled local or containerized workspace, with optional add-ons extending both runtime and web UI.
A user drives Pi Coding Agent through the web chat while editing code, using the embedded xterm.js terminal, uploading files, and browsing the workspace in the same application. Built-in panes view CSV/TSV, PDF, images, video, code previews, and VNC targets; automation includes image_process, cdp_browser, and mcp. PiClaw stores messages, media, tasks, token usage, and run records in /workspace/.piclaw/store/messages.db, while Pi state is persisted under /config/.pi. Tool loading is staged: a small always-active set exposes further capabilities through list_tools and list_scripts. Chat workflows include steering, queued follow-ups, side prompts, and scheduled tasks.
- A solo developer who wants a browser-based coding assistant, editor, and terminal on a self-hosted machine or server.
- A developer using Docker who needs Pi login state, model metadata, and project files to survive container recreation.
- An engineer who needs a coding session to inspect CSV files, PDFs, images, videos, or a VNC desktop from the same workspace.
- A single-user workflow that needs scheduled tasks, follow-up instructions, chat branches, and retained run logs in one interface.
- A self-hosting user who needs a custom OpenAI-compatible endpoint or a local llama.cpp router preset.
What are this agent's strengths and limitations?
- Combines Pi Coding Agent, chat, a CodeMirror 6 editor, an xterm.js terminal, and file viewers in one self-hosted interface.
- SQLite persistence covers chats, tasks, media, token usage, run logs, encrypted keychain entries, and session-scoped SSH profiles.
- Includes image_process, cdp_browser, mcp, VNC, and viewers for CSV/TSV, PDF, images, and video.
- Supports custom OpenAI-compatible endpoints and local llama.cpp router presets, with add-ons for runtime and UI extensions.
- Use depends on Pi Agent provider login and model configuration; the supplied material does not document an included model or free inference service.
- Windows support is explicitly experimental, and PICLAW_WEB_TERMINAL_ENABLED defaults to off on Windows.
- messages.db is the source of truth for chats, tasks, token records, keychain entries, and sessions, so deleting it loses that persisted data.
- Some capabilities require optional add-ons, including the Ghostty terminal, Draw.io, Office rendering, Windows desktop automation, Proxmox, and Portainer.
How do you install or deploy this agent?
Create persistent directories, then run:
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:latest
An experimental alternative is bun add -g github:rcarmo/piclaw. The container route requires Docker; the global-install route requires Bun.
How do you use this agent?
Open http://localhost:8080, type /login in chat, and configure provider credentials in Pi Agent settings; provider API keys do not need to be set as PiClaw environment variables. Then send coding tasks in chat, browse projects and uploads in Workspace, or open the Terminal, CSV/TSV, PDF, image, video, and VNC panes. Deployment behavior can be configured with environment variables including PICLAW_WEB_PORT, PICLAW_WEB_TERMINAL_ENABLED, PICLAW_WEB_TOTP_SECRET, PICLAW_WEB_PASSKEY_MODE, PICLAW_KEYCHAIN_KEY, and PICLAW_TRUST_PROXY.
How does this agent compare with similar options?
PiClaw is a derivative built on the Pi Coding Agent core, adding its own runtime, tooling, and web UI layers; the repository states that it is not directly affiliated with pi.dev.