PiClaw: a self-hosted Pi coding agent behind a browser workspace
pi coding agent in a technicolor web trenchcoat
At a glance
- What is it?
- PiClaw wraps the Pi Coding Agent in a single-user web workspace with a file browser, editor, terminal and VNC panes. It is a strong fit for one operator on a dedicated box, and the wrong tool if you need filesystem isolation between users.
- Who is it for?
- Adopt PiClaw if you are one operator on a container, VM or dedicated machine and want the agent, file browser, editor and terminal in one browser tab. Do not adopt it if you need filesystem isolation between multiple users: the README states isolated-container mode is unavailable and family-shared deployments share one workspace and process.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap PiClaw fills between a terminal agent and a remote desktop
A coding agent that lives in a terminal gives you a prompt and a stream of text. PiClaw's premise is that you also want to see the artefacts: the file it wrote, the CSV it produced, the PDF it rendered, the terminal it opened. The README describes the goal plainly as working with an agent, editing files, running commands and inspecting the results in the same browser window. That is the whole product thesis.
The target user is someone who already runs a Pi Coding Agent and wants a persistent surface for it. Conversations, files and scheduled tasks survive between visits, according to the README, and model requests go to whichever provider you configure, including local OpenAI-compatible servers. The self-hosted framing matters: application state stays on your machine, though the README is explicit that cloud models and external tools still receive whatever you send them. If you want a hosted agent product, this is not that. If you want a local one with a UI, this is aimed at you.
What actually runs: Pi core, a Bun process and a mounted workspace
PiClaw is TypeScript on Bun and is built on the Pi Coding Agent from earendil-works/pi. The container image bundles Bun, PiClaw and a set of command-line tools, which is why the Docker path is listed as the recommended deployment. The README credits rcarmo/vibes as the original PiClaw UX design, so the web layer is a deliberate rework of an earlier interface rather than an incidental addition.
Data flow is directory-based and easy to reason about. The container mounts two paths: /config for home and /workspace for the working tree. Both are persistent. The README warns in bold that workspace/.piclaw/store/messages.db must never be deleted to reset or upgrade PiClaw, which tells you the chat history lives in a SQLite file inside the workspace rather than in a separate database service. There is no external database to provision.
The UI surface is broad for a single process: a workspace browser, uploads, a CodeMirror editor, shell tools, a detachable xterm.js terminal, viewers for CSV/TSV, PDF, image, video and code, and VNC remote-display panes. Extensibility runs through skills, MCP servers, browser automation, image processing, Adaptive Cards and interactive visual artefacts. Optional add-ons, installed separately through Settings, cover Draw.io, Office document rendering, kanban boards, alternative terminal renderers, Windows desktop automation, Proxmox, Portainer and Microsoft 365.
Getting it running with Docker, and the login step people miss
The README gives a concrete command. Create the two host directories first, then run the container with --init, --restart unless-stopped, and the port published on localhost only:
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
PICLAW_WEB_PORT is the one environment key shown here. The README states that provider setup happens after startup, not through Docker environment variables. You open http://localhost:8080 on the Docker host and send /login in chat to configure a model provider. PiClaw reuses Pi's provider credentials, so API keys do not go into the docker run line. Then /model selects a model. The README's suggested first task is to ask the agent to create a Markdown checklist in the workspace and show the file, which exercises the write path and the viewer in one go.
The warning attached to that command is worth repeating: a fresh instance has no web login gate, and the localhost binding is the only thing keeping it private until you configure authentication. The README points to a secure browser access section in the getting started guide and says to set up HTTPS before allowing access from other machines. Browser authentication supports authenticator codes (TOTP) and passkeys.
Single-user by default, and what family mode does not give you
This is where PiClaw's boundaries are drawn most clearly, and where a prospective adopter should slow down. Single-user is the default. There is an experimental family mode described as a trusted multi-user mode for small groups. Promoted family-shared deployments provide owned conversations while sharing one workspace and one process. They do not provide filesystem isolation. Isolated-container mode is unavailable.
Read that as a design statement, not a roadmap gap. The agent runs with its process user's permissions. On a native install it can reach that user's files and commands. In a container it sees the mounted files and the configured network access. The README's own guidance is to use a dedicated environment and mount only what you intend to share. If your requirement is that two people's agents cannot read each other's files, PiClaw does not meet it today, and the documentation says so rather than implying otherwise.
The optional keychain is another place to read carefully. It needs a master key and, per the README, does not encrypt the whole workspace or chat history. So it is not a substitute for disk encryption or for keeping the host itself private.
Where the documentation is thin
The README is unusually candid about security and unusually quiet about operations. First-run checks, backups and upgrades are delegated to the getting started guide, and the only upgrade instruction visible in the README is a negative one: do not delete messages.db. There is no stated migration path between major versions, and the release cadence is fast. v3.0.0, v3.1.0 and v3.1.1 all landed within four days in September 2026, with release names taken from films (Ohana, Addams Family Values, Brazil). Fast majors plus a persistent SQLite store is a combination where you want a backup before you pull a new tag.
The README does advise pinning a release tag for repeatable deployments, which is the right default here. What it does not give you is a compatibility matrix or a statement about whether a v3.0.0 workspace opens cleanly under v3.1.1. Treat that as unverified from the supplied material.
Resource expectations are also absent. The README does not state memory or CPU requirements, and it does not say how many concurrent browser sessions the single process handles comfortably. If you plan to leave VNC panes and a terminal open alongside chat, that is something you will have to measure on your own hardware.
How PiClaw differs from running the Pi agent directly
The obvious alternative is the Pi Coding Agent on its own, in a terminal, without PiClaw. The difference is not capability but surface area. Pi gives you an agent loop and a prompt. PiClaw adds a browser workspace around it: persistent conversations, a file browser with uploads, a CodeMirror editor, a detachable terminal, media viewers and scheduled tasks. If your workflow is already terminal-native and you never need to look at a rendered PDF or a CSV table, the web layer is overhead you would be adding on purpose.
The other axis is deployment shape. PiClaw's recommended path is a container with two mounted directories, which means the agent's reach is defined by what you mount. A native Pi install runs with your user's permissions over your whole home directory. That is a real difference in blast radius, and it is the reason the README pushes containers and dedicated machines. The trade-off is that anything you want the agent to touch has to be inside /workspace or reachable over the network you configured.
Licence, maintenance and what upgrading actually costs
PiClaw is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. It gives no patent grant and no warranty. This is not legal advice; if you are redistributing PiClaw inside a product, read the licence text and the licences of the bundled dependencies yourself, since the container ships Bun and a set of command-line tools whose terms are separate from PiClaw's.
Maintenance cost has two parts. The first is tracking upstream: PiClaw is built on Pi and reuses Pi's provider credentials, so changes in the Pi core can reach you through a PiClaw release. The second is your own deployment. The README's persistence model is simple (two directories, one SQLite file), which keeps backup cheap, but it also means the upgrade path is a container swap plus whatever the new version does to messages.db. Pin a tag, keep a copy of ./home and ./workspace, and check the release notes before moving between majors. The add-ons are installed separately through Settings and are not covered by the core image, so each one is its own upgrade decision.
Editorial conclusion
Adopt PiClaw if you are one operator on a container, VM or dedicated machine and want the agent, file browser, editor and terminal in one browser tab. Do not adopt it if you need filesystem isolation between multiple users: the README states isolated-container mode is unavailable and family-shared deployments share one workspace and process. Before exposing it, verify the login gate is configured, since a fresh instance ships without one, and confirm your reverse proxy is the only source trusted for forwarded headers.
Community notes