PiClaw: a self-hosted Pi coding agent in a browser workspace

The problem PiClaw solves, and who it is actually for

Most coding agents assume a terminal. You type a prompt, the agent edits files, and you switch to another window to look at the result. PiClaw's premise is that the agent, the files it touches and the output it produces belong in one browser window. The README describes it as a self-hosted AI workspace, single-user by default, built on the Pi Coding Agent, where you can work with an agent, edit files, run commands and inspect the results without leaving the page.

The target user is someone who already runs services on their own hardware. The README recommends a container, VM or dedicated machine specifically to limit which files and services the agent can reach. That is not a hosting suggestion, it is a security posture: the agent runs with the permissions of its process user, so a native install can reach that user's files and commands. PiClaw is for the person who accepts that trade and wants the convenience of a persistent workspace in exchange for keeping the agent boxed in.

It is not a team product. The default is one user, and the README is explicit that experimental family mode is a trusted multi-user mode for small groups, not an isolation boundary.

How the workspace, memory and scheduled tasks fit together

PiClaw is a TypeScript project that runs on Bun. The package entry is runtime/src/index.ts, and the package.json exposes two binaries: piclaw and imgcat. The web frontend is built into static asset bundles under web/static/classic/dist for authenticated UI assets and web/static/common/dist for shared and login assets, according to the Makefile comments. Vendor libraries such as CodeMirror, marked, katex and mermaid are kept as separate pre-built assets rather than bundled into the main output.

Persistence is file-based. Conversations, files and scheduled tasks survive between visits, and the README points to a SQLite store at workspace/.piclaw/store/messages.db. Dream memory is also file-based, documented in docs/dream-memory.md. That combination means the workspace directory is the unit of backup, not an opaque database service.

Model requests go to whichever provider you configure, including local OpenAI-compatible servers. PiClaw reuses Pi's provider credentials rather than storing API keys in the container definition, which is why provider setup happens after startup through the chat command /login. The README separates that from browser sign-in, which supports authenticator codes and passkeys.

The feature surface is broad: streaming chat with live steering and queued follow-ups, a workspace browser with uploads and a CodeMirror editor, shell tools, a detachable xterm.js terminal, viewers for CSV, TSV, PDF, images, video and code, VNC remote-display panes, MCP servers, skills and Adaptive Cards. Optional add-ons cover Draw.io, Office rendering, kanban boards and Windows desktop automation, installed separately.

Installing PiClaw with Docker and running a first task

The README's recommended deployment is Docker, because the image bundles Bun, PiClaw and command-line tools. You need Docker plus credentials for a model provider or a reachable local model server. Create the two host directories first, then start the container. The README publishes the port on localhost only and warns that a fresh instance has no web login gate.

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. You should see the PiClaw web UI. Note that /config maps to the persisted agent home and /workspace holds the workspace plus PiClaw state.

Provider setup is a chat command, not an environment variable. Send /login in chat to configure a model provider, then select a model with /model. The README suggests this first task: "Create a Markdown checklist in the workspace and show me the file." You should see the agent write the file and the workspace browser list it.

Before exposing the instance to other machines, the README says to set up browser authentication and HTTPS. If you prefer Compose, the repository ships a docker-compose.yml whose service is named pibox, with PICLAW_WEB_PORT defaulting to 8080, PICLAW_AUTOSTART defaulting to 1, and CPU and memory limits set through CPU_LIMITS and MEMORY_LIMITS. Both ./home and ./workspace are persistent data, and the README says never to delete workspace/.piclaw/store/messages.db to reset or upgrade.

The single-user default is a limit, not a footnote

The most consequential thing in the README is the security section. Single-user is the default. Family mode is described as experimental and trusted, and promoted family-shared deployments give owned conversations while sharing one workspace and one process. The README states plainly that they do not provide filesystem isolation, and that isolated-container mode is unavailable. If your plan was to give each person their own agent with their own file access, PiClaw does not do that today.

The second limit is the agent's reach. It runs with its process user's permissions. A native install can read that user's files and run that user's commands; a container exposes only its mounted files and configured network access. That is the argument for the container route, and it is also the reason to mount only what you intend to share.

The third is data leaving the machine. Self-hosting keeps application state local, but the README notes that cloud models and external tools still receive whatever you send them. The optional keychain requires a master key and, per the README, does not encrypt the whole workspace or chat history. Anyone who reads "self-hosted" as "nothing leaves" will be wrong.

Finally, the desktop shell is labelled experimental in the install table, and the Bun repository install is labelled experimental too. The portable release is the documented Docker-free path for Linux, Apple Silicon macOS and experimental Windows use.

PiClaw versus running the Pi Coding Agent directly

The honest alternative is the Pi Coding Agent itself, which PiClaw is built on. Running Pi directly gives you a terminal agent with no HTTP surface, no web login gate to configure, and no browser session holding your workspace. If your work is already terminal-shaped, the direct route removes an entire layer of deployment concerns: no port to publish, no reverse proxy, no TOTP or passkey setup.

What PiClaw adds is the shared surface. The file browser, the CodeMirror editor, the xterm.js terminal, the CSV and PDF viewers and the VNC panes all exist so that inspection happens next to the conversation rather than in a second window. Scheduled tasks and searchable chat history make the workspace something you return to rather than a session you close. The trade is that you now operate a web service, and the README's own warning about the missing login gate on a fresh instance shows what that costs if you skip the hardening step.

A second comparison point is the add-on system. PiClaw's core deliberately excludes Draw.io, Office rendering and kanban boards, pushing them to a separate add-on site installed through settings. That keeps the base image smaller but means a feature you saw in a screenshot may be a second install.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-09-10. The three most recent releases are v3.1.1 on 2026-09-10, v3.1.0 on 2026-09-08 and v3.0.0 on 2026-09-07, so releases arrive close together. The package.json version is 3.1.2, one patch ahead of the newest published tag in the release list, which is worth checking before you pin.

The README recommends pinning a release tag for repeatable deployments rather than tracking latest. That advice matters more here than for a stateless service, because workspace/.piclaw/store/messages.db holds conversation state and the README warns against deleting it to reset or upgrade. The getting-started document covers first-run checks, backups and upgrades; the README does not describe an automated migration or rollback path, so the upgrade procedure is something to read in that document before you pull a new tag.

Licensing is MIT, per the repository's LICENSE file and the licence field in package.json. MIT is permissive and places few conditions on redistribution, but this is not legal advice. The practical implication for a self-hoster is that you should check the licences of the bundled tools and vendor libraries in the image separately, since the PiClaw licence covers PiClaw, not everything the container ships.

Editorial conclusion

Adopt PiClaw if you want one browser window for an agent, a file tree and a shell, and you are willing to run it in a container on a machine you control. Do not adopt it if you need filesystem isolation between users: the README states that isolated-container mode is unavailable and that family mode shares one workspace and process. Before mounting anything, verify the licence file, the pinned image tag and how you will back up workspace/.piclaw/store/messages.db.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. rcarmo/piclaw on GitHub
4. README
5. Releases