PiClaw — self-hosted AI workspace

[!IMPORTANT]

Temporary submission pause: Bug reports and pull-request submissions are disabled while we complete repository housekeeping and planning. Follow the draft Earendil-aligned agent harness integration ADR for the current work and reopening criteria.

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 built-in tools. Optional add-ons extend the runtime and web UI.

Run it locally or in a container as one stateful agent workspace.

Capabilities

Quick start

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 and local llama.cpp router presets. The web UI ships with English, Simplified Chinese, and Japanese strings; switch languages in Settings.

[!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 docker run example above or the bundled docker-compose.yml, Pi home state 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

[!WARNING] Never delete /workspace/.piclaw/store/messages.db. It is the source of truth for chat history, media, tasks and run logs, token usage, encrypted keychain entries, passkeys, web sessions, and chat branches.

[!IMPORTANT] You do not need to set provider API keys in piclaw environment variables. PiClaw reuses provider credentials configured in Pi Agent settings.

[!NOTE] Workspace-scoped shell environment overrides can go in /workspace/.env.sh. PiClaw sources that file for the embedded terminal and during runtime startup. Use it for settings such as PATH changes or a persistent GitHub CLI directory with GH_CONFIG_DIR=/workspace/.config/gh. Invalid contents can break startup, shell behavior, or tool resolution.

Web UI at a glance

PiClaw is single-user, mobile-friendly, and streams updates over SSE.

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

[!NOTE] The bundled xterm.js implementation is the default terminal renderer. The Ghostty/WASM renderer is available separately through the optional @rcarmo/piclaw-addon-ghostty-terminal add-on.

Configuration

Common environment variables:

For the full list, TOTP/passkey setup, session-scoped SSH-backed remote tools, reverse proxy configuration, and the workspace environment hook, see docs/configuration.md.

Other install methods

Install without Docker

bun add -g github:rcarmo/piclaw

Experimental. Linux/macOS/Windows. See docs/install-from-repo.md.

Windows support is experimental. Shell-like child processes run attached there (detached=false) so stdout and stderr remain capturable. Unix-like hosts use detached process groups so abort and shutdown can terminate the process tree.

Experimental desktop shell

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

bun run build:desktop

The 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.

Build from source

See docs/development.md.

Documentation

Contributing

Work items and bug reports are tracked in GitHub Issues.

• Open a work item or bug report
• Ask a question
• View the project board

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

Credits

• pi.dev for the Pi core used by piclaw
• 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 built on the Pi core and adds its own runtime, tooling, and UI layers.

Licence

MIT