PiClaw — self-hosted AI workspace

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.

Install

Published downloads are on GitHub Releases; container images are on GHCR. Pin a release tag for repeatable deployments.

Quick start with Docker

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

1. Open http://localhost:8080 on the Docker host.
2. Send /login in 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.
3. Select a model with /model, then try: “Create a Markdown checklist in the workspace and show me the file.”
4. 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.

What you can do

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.

Security and limits

• Single-user is the default. Experimental family mode is a trusted multi-user mode for small groups. Promoted family-shared deployments 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.

Documentation

• 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

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 when reporting a problem. For code changes, read development and the repository workflow; submit changes through a pull request.

Credits

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

Licence

MIT