piclaw

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# PiClaw — self-hosted AI workspace

![PiClaw](https://github.com/rcarmo/piclaw/raw/HEAD/docs/icon-256.png)

Languages: **English** · [简体中文](https://github.com/rcarmo/piclaw/blob/HEAD/README.zh-CN.md) · [日本語](https://github.com/rcarmo/piclaw/blob/HEAD/README.ja.md)

PiClaw packages the [Pi Coding Agent](https://github.com/badlogic/pi-mono) into a self-hosted workspace with a trilingual streaming web UI, persistent state, multi-provider LLM support, and built-in tools. [Optional add-ons](https://rcarmo.github.io/piclaw-addons/) extend the runtime and web UI.

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

## Capabilities

![Demo Animation](https://github.com/rcarmo/piclaw/raw/HEAD/docs/demo.gif)

| Capability | Details |
|---|---|
| Web workspace | Chat, editor, terminal, viewers, uploads, and automation in the same UI |
| Persistent state | SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH profiles |
| Built-in tools | Code editing, CSV/PDF/image/video viewing, VNC, browser automation, image processing, MCP, and optional cross-instance IPC for paired remote peers |
| Agent workflows | Steering, queued follow-ups, side prompts, scheduled tasks, and visual artifact generation; the optional autoresearch add-on supplies experiment loops |
| Staged tool loading | A small always-active tool set with discovery through `list_tools` and `list_scripts` |
| Optional authentication and channels | Passkeys or TOTP for the web UI, plus optional WhatsApp integration |
| Optional add-ons | Extra tools, skills, viewers, terminals, settings panes, Draw.io, Office document rendering and tools, Windows desktop automation, Proxmox, and Portainer |

## Quick start

```bash
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](https://github.com/rcarmo/piclaw/blob/HEAD/docs/llama-cpp.md). 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.

| Mount | Container path | Contents |
|---|---|---|
| Home | `/config` | Persistent Pi state (`.pi/`) and Git configuration (`.gitconfig`) |
| Workspace | `/workspace` | Projects, notes, and piclaw state |

> [!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`](https://github.com/rcarmo/piclaw/blob/HEAD/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, chat branches, and remote-peer state.

> [!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.

| Area | Highlights |
|---|---|
| Chat | Thought/draft panels, steering, queued follow-ups, Adaptive Cards, `/btw`, link previews, threaded turns, recovery/timeout chips |
| Language | English, Simplified Chinese, and Japanese UI strings with a Settings language switcher |
| Status UX | Tool/intended status stays visible during silence probing, recent activity restores useful context, and tool rows can show compact `x ago` hints in the meta row |
| Workspace | Sidebar browser, drag-and-drop uploads, file-reference pills, explorer search/reindex status |
| Editor | CodeMirror 6, search/replace, dirty-state tracking, syntax highlighting, lazy local bundle |
| Terminal | Bundled xterm.js web terminal as dock or tab; detachable popouts; Ghostty is available separately as an optional add-on |
| Viewers | Built-in CSV/TSV, PDF, image, video, code-preview, and VNC panes; optional add-ons supply Draw.io, the Office viewer backend, and kanban support |
| Automation | Built-in `image_process`, `cdp_browser`, and `mcp`; experimental `m365`; `/image` and `/flux` when Azure OpenAI/Foundry is configured; Windows desktop automation through the optional `win-ui` add-on |

For the full feature tour, see [docs/web-ui.md](https://github.com/rcarmo/piclaw/blob/HEAD/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`](https://rcarmo.github.io/piclaw-addons/addons/ghostty-terminal/) add-on.

## Configuration

Common environment variables:

| Variable | Default | Purpose |
|---|---|---|
| `PICLAW_WEB_PORT` | `8080` | Web UI port |
| `PICLAW_WEB_TERMINAL_ENABLED` | `1` on Linux/macOS, `0` on Windows | Enable or disable the authenticated bundled web terminal |
| `PICLAW_WEB_VNC_ALLOW_DIRECT` | `1` on Linux/macOS/Windows | Allow or disable direct VNC targets supplied at runtime |
| `PICLAW_WEB_TOTP_SECRET` | _(empty)_ | Base32 TOTP secret; enables login gate (or initialize with `/totp`) |
| `PICLAW_WEB_PASSKEY_MODE` | `totp-fallback` | `totp-fallback`, `passkey-only`, or `totp-only` |
| `PICLAW_ASSISTANT_NAME` | `PiClaw` | Display name in the UI |
| `PICLAW_ENABLE_M365_EXPERIMENTAL` | `0` | Enable the experimental Microsoft 365 extension bundle |
| `PICLAW_KEYCHAIN_KEY` | _(empty)_ | Master key for encrypted secret storage |
| `PICLAW_TRUST_PROXY` | `0` | Enable when behind a reverse proxy or tunnel |

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](https://github.com/rcarmo/piclaw/blob/HEAD/docs/configuration.md).

## Other install methods

### Install without Docker

```bash
bun add -g github:rcarmo/piclaw
```

Experimental. Linux/macOS/Windows. See [docs/install-from-repo.md](https://github.com/rcarmo/piclaw/blob/HEAD/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:

```bash
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](https://github.com/rcarmo/piclaw/blob/HEAD/docs/development.md).

## Documentation

| Area | Docs |
|---|---|
| Getting started | [Configuration](https://github.com/rcarmo/piclaw/blob/HEAD/docs/configuration.md), [Web UI](https://github.com/rcarmo/piclaw/blob/HEAD/docs/web-ui.md), [Install from repo](https://github.com/rcarmo/piclaw/blob/HEAD/docs/install-from-repo.md) |
| Operations | [Azure VM deployment](https://github.com/rcarmo/piclaw/blob/HEAD/docs/azure/README.md), [Azure OpenAI extension](https://github.com/rcarmo/piclaw/blob/HEAD/docs/azure/azure-openai-extension.md), [Reverse proxy](https://github.com/rcarmo/piclaw/blob/HEAD/docs/reverse-proxy.md), [Release process](https://github.com/rcarmo/piclaw/blob/HEAD/docs/release.md) |
| Runtime internals | [Architecture](https://github.com/rcarmo/piclaw/blob/HEAD/docs/architecture.md), [Pipelined smart compaction](https://github.com/rcarmo/piclaw/blob/HEAD/docs/pipelined-compaction.md), [Runtime flows](https://github.com/rcarmo/piclaw/blob/HEAD/docs/runtime-flows.md), [Runtime stream sessions](https://github.com/rcarmo/piclaw/blob/HEAD/docs/runtime-stream-sessions.md), [Storage model](https://github.com/rcarmo/piclaw/blob/HEAD/docs/storage.md), [Observability](https://github.com/rcarmo/piclaw/blob/HEAD/docs/observability.md) |
| UI extension model | [Web pane extensions](https://github.com/rcarmo/piclaw/blob/HEAD/docs/web-pane-extensions.md), [Extension UI contract](https://github.com/rcarmo/piclaw/blob/HEAD/docs/extension-ui-contract.md), [Vendored widget libraries](https://github.com/rcarmo/piclaw/blob/HEAD/docs/vendored-widget-libraries.md) |
| Agent capabilities | [Tools and skills](https://github.com/rcarmo/piclaw/blob/HEAD/docs/tools-and-skills.md), [Visual artifact generator](https://github.com/rcarmo/piclaw/blob/HEAD/docs/visual-artifact-generator.md), [MCP via pi-mcp-adapter](https://github.com/rcarmo/piclaw/blob/HEAD/docs/mcp.md), [Keychain](https://github.com/rcarmo/piclaw/blob/HEAD/docs/keychain.md) |
| Other references | [Dream memory system](https://github.com/rcarmo/piclaw/blob/HEAD/docs/dream-memory.md), [Thinking persistence](https://github.com/rcarmo/piclaw/blob/HEAD/docs/thinking-persistence.md), [Web notification delivery policy](https://github.com/rcarmo/piclaw/blob/HEAD/docs/web-notification-delivery-policy.md), [iOS PWA reference](https://github.com/rcarmo/piclaw/blob/HEAD/docs/PWA.md), [WhatsApp](https://github.com/rcarmo/piclaw/blob/HEAD/docs/whatsapp.md), [Cross-instance interop](https://github.com/rcarmo/piclaw/blob/HEAD/docs/cross-instance-ipc.md), [Experimental M365 extension](https://github.com/rcarmo/piclaw/blob/HEAD/docs/m365-experimental-extension.md), [Development](https://github.com/rcarmo/piclaw/blob/HEAD/docs/development.md) |
| Platform study | [Azure Functions feasibility study](https://github.com/rcarmo/piclaw/blob/HEAD/docs/azure/azure-functions-feasibility-study-2026-04-17.md) |

## Contributing

Work items and bug reports are tracked in **[GitHub Issues](https://github.com/rcarmo/piclaw/issues)**.

- [Open a work item or bug report](https://github.com/rcarmo/piclaw/issues/new?template=workitem.md)
- [Ask a question](https://github.com/rcarmo/piclaw/issues/new?template=question.md)
- [View the project board](https://github.com/users/rcarmo/projects/13)

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

## Credits

- [pi.dev](http://pi.dev) for the Pi core used by piclaw
- [rcarmo/agentbox](https://github.com/rcarmo/agentbox)
- [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw)
- [badlogic/pi-mono](https://github.com/badlogic/pi-mono)
- [davebcn87/pi-autoresearch](https://github.com/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](https://github.com/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](https://pi.dev). It is a derivative work built on the Pi core and adds its own runtime, tooling, and UI layers.

## Licence

MIT

PiClaw — self-hosted AI workspace

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

Demo Animation

Capability	Details
Web workspace	Chat, editor, terminal, viewers, uploads, and automation in the same UI
Persistent state	SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH profiles
Built-in tools	Code editing, CSV/PDF/image/video viewing, VNC, browser automation, image processing, MCP, and optional cross-instance IPC for paired remote peers
Agent workflows	Steering, queued follow-ups, side prompts, scheduled tasks, and visual artifact generation; the optional autoresearch add-on supplies experiment loops
Staged tool loading	A small always-active tool set with discovery through `list_tools` and `list_scripts`
Optional authentication and channels	Passkeys or TOTP for the web UI, plus optional WhatsApp integration
Optional add-ons	Extra tools, skills, viewers, terminals, settings panes, Draw.io, Office document rendering and tools, Windows desktop automation, Proxmox, and Portainer

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.

Mount	Container path	Contents
Home	`/config`	Persistent Pi state (`.pi/`) and Git configuration (`.gitconfig`)
Workspace	`/workspace`	Projects, notes, and piclaw state

[!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, chat branches, and remote-peer state.

[!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.

Area	Highlights
Chat	Thought/draft panels, steering, queued follow-ups, Adaptive Cards, `/btw`, link previews, threaded turns, recovery/timeout chips
Language	English, Simplified Chinese, and Japanese UI strings with a Settings language switcher
Status UX	Tool/intended status stays visible during silence probing, recent activity restores useful context, and tool rows can show compact `x ago` hints in the meta row
Workspace	Sidebar browser, drag-and-drop uploads, file-reference pills, explorer search/reindex status
Editor	CodeMirror 6, search/replace, dirty-state tracking, syntax highlighting, lazy local bundle
Terminal	Bundled xterm.js web terminal as dock or tab; detachable popouts; Ghostty is available separately as an optional add-on
Viewers	Built-in CSV/TSV, PDF, image, video, code-preview, and VNC panes; optional add-ons supply Draw.io, the Office viewer backend, and kanban support
Automation	Built-in `image_process`, `cdp_browser`, and `mcp`; experimental `m365`; `/image` and `/flux` when Azure OpenAI/Foundry is configured; Windows desktop automation through the optional `win-ui` add-on

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:

Variable	Default	Purpose
`PICLAW_WEB_PORT`	`8080`	Web UI port
`PICLAW_WEB_TERMINAL_ENABLED`	`1` on Linux/macOS, `0` on Windows	Enable or disable the authenticated bundled web terminal
`PICLAW_WEB_VNC_ALLOW_DIRECT`	`1` on Linux/macOS/Windows	Allow or disable direct VNC targets supplied at runtime
`PICLAW_WEB_TOTP_SECRET`	(empty)	Base32 TOTP secret; enables login gate (or initialize with `/totp`)
`PICLAW_WEB_PASSKEY_MODE`	`totp-fallback`	`totp-fallback`, `passkey-only`, or `totp-only`
`PICLAW_ASSISTANT_NAME`	`PiClaw`	Display name in the UI
`PICLAW_ENABLE_M365_EXPERIMENTAL`	`0`	Enable the experimental Microsoft 365 extension bundle
`PICLAW_KEYCHAIN_KEY`	(empty)	Master key for encrypted secret storage
`PICLAW_TRUST_PROXY`	`0`	Enable when behind a reverse proxy or tunnel

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

Area	Docs
Getting started	Configuration, Web UI, Install from repo
Operations	Azure VM deployment, Azure OpenAI extension, Reverse proxy, Release process
Runtime internals	Architecture, Pipelined smart compaction, Runtime flows, Runtime stream sessions, Storage model, Observability
UI extension model	Web pane extensions, Extension UI contract, Vendored widget libraries
Agent capabilities	Tools and skills, Visual artifact generator, MCP via pi-mcp-adapter, Keychain
Other references	Dream memory system, Thinking persistence, Web notification delivery policy, iOS PWA reference, WhatsApp, Cross-instance interop, Experimental M365 extension, Development
Platform study	Azure Functions feasibility study

Contributing

Work items and bug reports are tracked in GitHub Issues.

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