Languages: English · 简体中文 · 日本語
PiClaw is a self-hosted AI workspace, single-user by default, built on the Pi Coding Agent. Work with an agent, edit files, run commands and inspect the results in the same browser window. Conversations, files and scheduled tasks persist between visits; model requests go to the provider you configure, including local OpenAI-compatible servers.
The web UI supports English, Simplified Chinese and Japanese, with desktop and mobile layouts. Use a container, VM or dedicated machine to limit the files and services available to the agent.
| Method | Use it for |
|---|---|
| Docker | Recommended deployment; includes Bun, PiClaw and bundled command-line tools |
| Portable release | Docker-free Linux, Apple Silicon macOS or experimental Windows use; bundles Bun and runtime dependencies |
| Bun repository install | Experimental tagged install using an existing Bun installation |
| Source build / desktop shell | Development and local testing; the desktop wrapper is experimental |
Published downloads are on GitHub Releases; container images are on GHCR. Pin a release tag for repeatable deployments.
You need Docker and credentials for a model provider, or a reachable local model server. Provider setup happens after startup.
Warning
A fresh instance has no web login gate. The command below publishes the port on localhost only. Keep it private while you configure authentication. Anyone with access to an unprotected instance can use the agent's files and tools.
mkdir -p ./home ./workspace
docker run -d \
--init \
--name piclaw \
--restart unless-stopped \
-p 127.0.0.1:8080:8080 \
-e PICLAW_WEB_PORT=8080 \
-v "$(pwd)/home:/config" \
-v "$(pwd)/workspace:/workspace" \
ghcr.io/rcarmo/piclaw:latest- Open http://localhost:8080 on the Docker host.
- Send
/loginin chat to configure a model provider. This is separate from browser sign-in. PiClaw reuses Pi's provider credentials; you do not need to put API keys in the Docker command. - Select a model with
/model, then try: “Create a Markdown checklist in the workspace and show me the file.” - Before allowing access from other machines, set up browser authentication and HTTPS.
Both ./home and ./workspace are persistent data. Keep them when replacing the container; never delete workspace/.piclaw/store/messages.db to reset or upgrade PiClaw. See first-run checks, backups and upgrades.
| Task | Included in core |
|---|---|
| Work with an agent | Streaming chat, model selection, live steering, queued follow-ups, separate conversations and /btw side questions |
| Work on files | Workspace browser, uploads, CodeMirror editor, shell tools and a detachable xterm.js terminal |
| Inspect results | CSV/TSV tables, PDF, image, video and code viewers; VNC remote-display panes |
| Continue work between visits | Scheduled tasks, searchable chat history and file-based Dream memory |
| Extend workflows | Skills, MCP servers, browser automation, image processing, Adaptive Cards and interactive visual artefacts |
The web UI guide and tools and skills reference cover the controls and commands. Local model setup is documented in llama.cpp; Azure image generation requires Azure OpenAI/Foundry configuration.
Optional add-ons supply Draw.io, Office document rendering and tools, kanban boards, alternative terminal renderers, Windows desktop automation, Proxmox, Portainer, Microsoft 365 and paired-instance messaging. Install them separately through Settings and add-ons.
- Single-user is the default. Experimental family mode is a trusted multi-user mode for small groups. Promoted
family-shareddeployments provide owned conversations while sharing one workspace and process; they do not provide filesystem isolation. Isolated-container mode is unavailable. See the family user guide. - The agent runs with its process user's permissions. Native installs can access that user's files and commands; containers expose their mounted files and configured network access. Use a dedicated environment and mount only what you intend to share.
- Browser authentication supports authenticator codes (TOTP) and passkeys. Keep the backend private, use HTTPS for remote access, and trust forwarded headers only from your configured reverse proxy.
- Self-hosting keeps application state on your machine. Cloud models and external tools still receive the data you send to them. The optional keychain needs a master key and does not encrypt the whole workspace or chat history.
- Getting started — installation, first chat, authentication, persistence and upgrades
- Configuration — settings, paths, providers, SSH tools and environment overrides
- Web UI — chat, workspace, editor, terminal and viewers
- Documentation index — operations, integrations, development and architecture
Work items and bug reports are tracked in GitHub Issues.
Use the issue templates when reporting a problem. For code changes, read development and the repository workflow; submit changes through a pull request.
- pi.dev for the Pi core used by piclaw
- rcarmo/vibes — the original PiClaw UX design
- qwibitai/nanoclaw
- earendil-works/pi
- 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.
