Raw capture — raw/piclaw.md

url: https://github.com/rcarmo/piclaw date_fetched: 2026-07-05 backfilled: true

Languages: English · 简体中文 · 日本語

PiClaw packages the Pi Coding Agent into a self-hosted workspace with a trilingual streaming web UI, persistent state, multi-provider LLM support, and a practical built-in toolset that includes many add-ons.

It is for people who want one stateful agent workspace they can run locally or in a container without stitching together half a dozen separate services.

• One workspace, one app— chat, editor, terminal, viewers, boards, uploads, and automation in the same web UI
• Persistent state— SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH / Proxmox / Portainer profiles
• Practical built-ins— code editing, Office/PDF/CSV/image/video viewing, draw.io, VNC, browser automation, image processing, MCP, infra tools, and optional cross-instance IPC for paired remote peers
• Agent-first workflows— steering, queued follow-ups, side prompts, autoresearch loops, scheduled tasks, and visual artifact generation
• Context conservation— small always-active tool baseline with staged discovery via- list_tools/- list_scripts
• Optional auth/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:latest

Open 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. The web UI currently ships with English, Simplified Chinese, and Japanese strings; use the Settings language switcher when English is not the hill you want to die on today.

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.

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.

For the full feature tour, see docs/web-ui.md.

Note

The default terminal renderer is now the bundled xterm.js implementation. The former Ghostty/WASM renderer was moved out of core and is available as the optional @rcarmo/piclaw-addon-ghostty-terminal add-on for high-end browsers.

Most users only need a few environment variables:

For the full list, auth setup (TOTP/passkeys), session-scoped SSH-backed remote tools, reverse proxy configuration, SSHFS/FUSE support, and the workspace environment hook, 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.

PiClaw also has an optional Electrobun desktop wrapper around the existing local web UI:

bun run build:desktopThe desktop shell starts Piclaw on 127.0.0.1 using an available port starting at 18080, opens a native window, and stores its default workspace under the platform application-data directory. Set PICLAW_DESKTOP_URL to wrap an already-running Piclaw web server instead of starting one.

See docs/development.md.

Work items and bug reports are tracked in GitHub Issues.

Use the issue templates and project board labels for lane definitions and triage taxonomy.

• pi.dev for a stupendously flexible and extensible core
• rcarmo/agentbox
• qwibitai/nanoclaw
• badlogic/pi-mono
• davebcn87/pi-autoresearch — autonomous experiment loop by Tobi Lutke and David Cortés (now carried by the autoresearch add-on in rcarmo/piclaw-addons)
• nicobailon/visual-explainer — visual artifact generation skill philosophy, prompt workflow, and template patterns by Nico Bailon (adapted, not vendored)

Note

piclaw is not directly affiliated with pi.dev. It is a derivative work that leverages all of its core Pi functionality and builds additional runtime, tooling, and UI layers around it.

MIT