新实例默认没有网页登录验证,端口只绑定 localhost,配置好认证前不要对外暴露;启动后需在聊天里发 /login 配置模型提供方,API Key 不写在 docker 命令里;workspace/.piclaw/store/messages.db 是持久数据,升级或重置时绝不能删除。
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:latestREADME 未说明具体显存或 CPU 要求;推荐用 Docker 部署,也可用便携版在 Linux、Apple Silicon macOS 或实验性 Windows 上运行,模型请求可指向本地 OpenAI 兼容服务器。
基于 Pi 编码代理的自托管单用户 AI 工作台,在浏览器里聊天、改文件、跑命令
把 pi 编码 Agent 装进浏览器里的自托管 Web 工作台,带 VNC 和自适应卡片界面,让 LLM 编码助手随时在线可用。
核心能力
- 流式对话并支持实时干预与排队追问
- 内置工作区浏览器、CodeMirror 编辑器与 xterm.js 终端
- 可查看 CSV/PDF/图片/视频/代码及 VNC 远程桌面
- 定时任务、可搜索历史与基于文件的 Dream 记忆
- 通过 Skills、MCP 服务器和浏览器自动化扩展工作流
容易踩的坑
- v3.3.4PiClaw v3.3.4 — “Galaxy Quest”最新正式版2026-10-15 · 2026-10-15 23:31 UTC
PiClaw v3.3.4 — “Galaxy Quest”
The ship’s computer has received several clarifications. A status report must describe the turn currently on the bridge, a message must reach the conversation that actually exists, and an instruction to finish without tools must not include directions to the armoury. The crew may still improvise; the routing system should not.
Credential handling receives similar attention. A locked storage compartment is distinguishable from an invalid access code, reducing the occasions on which the captain is invited to log in again because someone misplaced the cupboard.
Highlights
- Manual compaction keeps reliable status. Older turn updates cannot overwrite current compaction state, and compaction claims ownership before asynchronous work begins.
- Credential failures are diagnosed more accurately. Storage, locking and configuration faults are distinguished from rejected authentication; recovery handles transient refresh and synchronisation failures.
- Pi moves to 1.2.0. The published upstream release is qualified with the existing Piclaw integration.
- Branches and windows keep their identities. Exact branch targeting, remote-session lifetime checks and UI lifecycle fixes reduce misdirected messages and stale state.
- Recovery finishes without contradicting itself. Tools-disabled finalisation receives a matching prompt while retaining enforcement against tool reactivation.
The current bridge watch
Manual compaction status is fenced to its owning turn. Late updates from an older turn still deliver their responses, but cannot replace newer compaction state. Early ownership claims close a second race before asynchronous compaction and rotation begin.
Compaction output budgets follow the available reserve, model output limit and remaining context instead of a fixed 8,192-token ceiling. The computer consults the available space before promising to fit another shuttle in it.
Credentials with the correct access codes
Credential diagnostics distinguish storage, lock and configuration faults from authentication rejection. Transient OAuth failures receive bounded retries, and offline synchronisation recovery uses fences to avoid overwriting newer credential state.
These changes do not replay inference requests after a 401 or force-refresh credentials indiscriminately. Diagnostic messages remain sanitised.
Messages to the right ship
Exact local add-on targeting considers live sibling branches even when their advertised alias is deduplicated.
Remote delivery checks the target branch’s lifetime during admission, preventing a stale reference from silently attaching to a replacement conversation. Supporting incarnation, cancellation and transactional admission checks preserve that boundary. A familiar call sign does not make it the same vessel.
Stand down means stand down
Recovery and finalisation paths that disable tools use a dedicated text-only prompt. Tool fences remain enforced, attempted reactivation stays blocked, and the normal tool loadout is restored afterwards.
Tool-enabled continuation retains its existing behaviour. The instruction sheet and the locked armoury now agree.
Windows and widgets
Widget isolation and status, editor and pop-out lifecycle fixes address stale state and ownership handoffs across the interface.
These changes reuse the existing conversation, queue and activity surfaces. They do not add a second bridge from which to command the first.
Upstream compatibility
The Pi package family advances to 1.2.0 following qualification of the published release.
The existing Piclaw integration remains in place. This release does not implement the planned
pi-durablemigration.Known limits
- Native MCP remains experimental; Adapter selection is unchanged.
- Local-lite remains opt-in and defaults to off.
- Credential recovery does not guarantee that an upstream provider will accept a request.
- Native desktop applications remain di
- v3.3.3PiClaw v3.3.3 — “Batteries Not Included”2026-10-13 · 2026-10-13 07:38 UTC
查看更新说明
PiClaw v3.3.3 — “Batteries Not Included”
The maintenance department has repaired the phone’s Delete button, fitted the GPU gauges with better instruments, and clarified which doors an add-on may use. The desktop application has meanwhile left the building. Its historical releases remain available, but new releases will concentrate on the web interface, server, containers and portable command-line packages.
Dependency updates arrive together, with their browser and authentication compatibility repairs included. The committee responsible for moving one chair at a time has been replaced by a committee capable of checking whether anyone is still sitting in it.
Highlights
- Keychain controls work on narrow screens. Delete and confirmation controls remain reachable on phones, with touch targets and keyboard focus behaviour preserved.
- GPU meters show more useful telemetry. VRAM displays gain sparklines and alignment fixes; optional NVML data adds GPU activity history.
- Add-ons gain dictation and authenticated socket hooks. Lifecycle fixes and qualification cover the new extension surfaces.
- Provider waits and proxy handling improve. Bounded wait fixes address slow prompt startup, while trusted-proxy HTTPS handling controls secure cookies and HSTS correctly.
- Dependencies move forward together. Browser, passkey and consumer compatibility fixes accompany the upgrades. Native desktop applications are discontinued.
Controls within reach
Keychain action cells wrap correctly at narrow widths. Delete, Yes and No controls remain inside their action area, with usable touch targets and focus restoration after confirmation.
The fix was exercised in the real Settings interface in Chromium and WebKit at phone, tablet and desktop widths. The button is once again responsible for deleting the selected entry, rather than testing the user’s accuracy.
Better instruments
VRAM meters gain sparklines and consistent alignment. Optional NVML telemetry supplies GPU activity readings and history alongside memory usage.
These displays depend on available telemetry. Unsupported or unavailable measurements are not invented to keep the instruments looking busy.
Add-on connections
Core hooks support dictation providers and authenticated add-on sockets. Follow-up changes address dictation lifecycle, import and socket behaviour, public hook parity and keychain availability.
Tool-activation responses report the effective active tools. Session-command eviction protection and activation guidance improve recovery paths.
These are extension surfaces and supporting fixes; they do not install or activate a server-dictation service automatically.
Same-origin widgets can also load WebAssembly through the qualified widget capability path.
Providers and proxies
Provider-concurrency fixes bound waits associated with prompt startup and provider operations.
Trusted-proxy HTTPS handling determines secure-cookie and HSTS behaviour from the trusted request context. Operators should retain the intended proxy trust configuration; forwarding headers from arbitrary clients do not acquire authority by arriving confidently.
The strict reply-persistence adjustment is scoped to UI-only theme replies.
Dependencies and desktop retirement
The coordinated update includes:
- Preact 11.0.1, with browser and consumer compatibility fixes.
- SimpleWebAuthn 14.0.3, with coordinated ASN.1 dependency pins.
- OpenAI 7.31.0.
- Updated GitHub Actions pins.
- Pi 1.1.0, unchanged.
Native desktop application source, build commands and release-asset production are removed. Existing historical desktop assets are retained. Web, server, container and portable command-line installations remain supported.
Related piclaw-addons #201 coordinates Pi 1.1 compatibility and browser/consumer fixes. Add-ons retain their separate publication lifecycle.
Documentation
The provider-
- v3.3.2PiClaw v3.3.2 — “Apollo 13”2026-10-10 · 2026-10-10 00:25 UTC
查看更新说明
Locally tested hotfix. Local qualification for #1619 passed before merging. The artifact-only release workflow skipped repeat test suites, UX, integration and image smoke checks. Source: c4c7f699aa8fa5afc7d10cd416609cb2cd10149b. Actor: piclaw-bot. Artifact run.
PiClaw v3.3.2 — “Apollo 13”
The composer’s controls had become sufficiently enthusiastic about sharing a row that typing was beginning to require clearance from the navigation department. This patch restores their seating arrangement and teaches the quota display to read the duration printed on each window’s paperwork.
The release machinery receives a repair of its own: Docker smoke checks no longer require a host-side Bun installation merely to inspect the Bun installation inside the image.
Composer steering and release repair
Ctrl/Cmd+Enter steers an active turn in both skins; Enter queues while busy, and Shift+Enter inserts a newline. Starting-turn submissions retain their payload through the durable fallback, and draft clearing requires a positive acknowledgement. #1617 implements these changes.
The Docker smoke fixture now passes the runner’s UID/GID to the container, allowing its agent to write private bind-mounted workspace/config directories. This preserves strict permissions and avoids assuming runner UID 1000. The previously failing AMD64 image passes both bind and named-volume checks with this fixture.
#1618 corrects browser-test ordering: the malformed-ACK probe waits for the enabled send control, confirms submission, and waits for the error notice. Runtime behaviour and original assertions are preserved.
Emergency feedback hotfix
#1619 restores native pending feedback and timeline steering conventions in both skins, removing redundant post-acknowledgement banners while retaining draft/error safety. This retag uses the explicitly authorised artifact-only emergency path; local qualification passed before merging; the artifact workflow does not repeat release tests, UX, integration or image smoke checks. Historical UX reports will be removed because they describe the prior tag.
Highlights
- The Visual composer is usable again across screen sizes. The jump-to-latest divider occupies its own full-width row, leaving the textarea, tools and send controls accessible.
- Codex quota labels follow the reported interval. Weekly-only and other window layouts no longer inherit misleading labels from their position in the response.
- Docker publication can reach its smoke checks. The Makefile invokes the shell entrypoint directly, removing the missing-host-Bun failure while retaining mandatory image validation.
Room for the controls
The Visual skin separates the jump-to-latest divider from the horizontal compose controls. Desktop, tablet and phone checks cover layout, hit-testing and actual typing in Chromium and WebKit.
The existing timeline and divider behaviour is preserved. The divider still helps you reach the latest message; it has relinquished its claim to the keyboard’s floor space.
Quotas with the correct timetable
Structured and compact Codex quota labels now derive independently from each window’s reported duration. A weekly-only primary window is labelled weekly; conventional five-hour and weekly windows retain their familiar labels.
Other durations receive corresponding labels, while missing or invalid durations use an unknown-window label. Usage percentages, reset information and credits are unchanged.
The launch checklist
Docker smoke checks still target the exact built image digest and verify the expected Bun and restic versions, HTTP serving and process supervision. Failures still block downstream publication.
The host starts those checks through the shell script directly. Regression tests exercise the
- v3.3.1PiClaw v3.3.1 — “The Last Starfighter”2026-10-09 · 2026-10-09 13:10 UTC
查看更新说明
PiClaw v3.3.1 — “The Last Starfighter”
The Department of Release Scheduling has acquired a calendar. Previously it worked from Earendil’s release announcements, which arrived with such enthusiasm that yesterday’s compatibility work occasionally qualified as archaeology before lunch. PiClaw is moving to a monthly release cadence, allowing upstream releases to accumulate, receive proper testing, and enter the building through the same door as everyone else.
Most future development will focus on transitioning to
pi-durable, whatever that turns out to be once the plans have finished negotiating with the implementation, and reviewing and merging community pull requests. Contributions are welcome. The maintainer will continue tending the machinery, but will cease personally answering every upstream trumpet with a fresh expedition.This also leaves room for other projects: rcarmo/gi and a
pi-durable-based Obsidian extension using rcarmo/fixtures-vibes. The latter proposes to give the notes a durable agent, which should at least ensure that someone remembers why all those notes were written.Local-model hotfix
Local models now use the normal system prompt and active tools by default. The compact local-lite profile is explicitly opt-in through Settings → Compaction → Local models → Local-lite prompt and tools in both web skins. Turning it off restores the previous tools on the next turn. The persisted setting is
domains.tools.localLitePromptProfileEnabled, defaultfalse; Ollama, llama.cpp and private-network endpoints no longer trigger automatic tool removal unless it is enabled.This v3.3.1 retag includes 754097577.
Release-tip update
This retag includes #1613, which fixes negative process-group operands in the local test runner’s stop/resume commands. A
--delimiter prevents the group ID from being parsed as a signal option. Linux regression tests cover both signals and preserve the child exit code.The previous Docker publication failed because the ARM64 runner could not find
bunbefore starting its smoke gate. Image publication is being retried; this test-runner fix does not repair that workflow setup issue.Highlights
- A shared live browser pane. CDP streaming provides a common browser surface with input, fit modes and resizing, qualified against Chromium and Safari-engine clients.
- Less uncertainty while working. Immediate prompt-submission feedback, safer editor saves, stable thought previews and per-window workspace state make the interface easier to trust.
- Pi 1.1.0 compatibility. The Pi package family moves together to the exact 1.1.0 release. The existing integration wrapper is retained; a durable-runtime migration is future work.
- Stricter packaging checks. Vendor inventory, gzip and metadata checks detect repository payload drift; Docker smoke failures block publication.
Windows, editors and messages
An About dialog exposes version information, and each window remembers its workspace state. Divider scroll chevrons are visible on both sides. Quick-action popups ignore keys already handled elsewhere and repeated typeahead keys, preventing two officials from processing the same form.
Prompt submission reports sending and startup progress immediately. Stale HTTP responses no longer revert newer thought previews. Editor saves preserve edits made while a save is in flight, and conflict copies are created beside the original file instead of being dispatched to an unrelated district.
GPU meters retain previously proven rows through transient telemetry loss, with unavailable samples represented as gaps rather than invented measurements.
Agents and browser work
Agents gain quota inspection and combined model/thinking controls. Multi-agent respons
- v3.3.0PiClaw v3.3.0 — “Modern Times”2026-10-06 · 2026-10-06 18:15 UTC
查看更新说明
PiClaw v3.3.0 — “Modern Times”
The factory has been refitted while the workers were still arguing with the machinery. MCP servers get a management desk, provider login gets a private interview room, and the conversation timeline is required to contain the conversation. The GPU department has been issued meters. Previously it was allowed to describe its workload by making the rest of the building warm. Management called this telemetry. The fire brigade had another word.
The promised Earendil upgrade also happened. Then upstream kept moving, so the migration followed it through to Pi 1.0.4. The factory now checks the version stamped on the actual package, having learned that an upstream announcement is neither a delivery receipt nor a signed confession. This release concerns the tools you can use, the controls you can reach, and the long-standing arrangement whereby one SQLite writer could establish a five-second dictatorship while the interface stood respectfully silent.
Highlights
- Manage MCP servers in Settings. Classic and Visual can preview and apply adapter server overrides for transport, authentication references, tool exposure, lifecycle and timeouts, while preserving inherited and private configuration.
- Enable MCP codemode deliberately. Adapter scripting has Auto/On/Off controls and acknowledged Apply. Nested tool calls retain policy hooks; model execution inside scripts is disabled.
- Provider login keeps its secrets to itself. Owner-bound, transient dialogs handle sensitive instructions and inputs; successful login requires an explicit action before selecting a model.
- Return to a conversation without losing the middle. Cached timelines catch up through contiguous pages, restore their viewport and reading position, and offer a compose-divider handle to jump to latest.
- Inspect supported GPUs without hiring a subprocess per glance. Linux Intel i915 gets activity and memory details; NVIDIA VRAM uses a shared, cached NVML worker.
- Send and pin while the database is busy. Input admission yields during writer contention; pin and picker conflicts report a retryable failure instead of holding the web event loop hostage.
- Pickers stop hiding the matches they found. Model and session popup headings stay in normal flow during typeahead instead of covering the first result. Disabled meter rows also disappear; actual zero readings stay visible.
MCP acquires a personnel department
Both web skins now expose adapter server management through owner-only Settings. Preview shows the proposed effective configuration before Apply; edits invalidate old previews. Disabling a server leaves it inert. Removing a local override may reveal an inherited definition, and the preview warns about it. The office will accept a resignation, but it must first check whether someone downstairs still employs the same server.
Apply requires acknowledgement that active turns may be interrupted. Server changes drain current main and side sessions, await adapter shutdown acknowledgements, save privately and reload through a common startup barrier while retaining session identity and history. A failed activation reports saved but not activated. The old server must acknowledge its departure before a successor starts; a death certificate signed by the replacement is no longer considered sufficient evidence.
Adapter codemode can be switched on or off for current and new sessions. Auto leaves scripting inactive, On enables it, and Off blocks it even after explicit tool activation. Scripts can make nested tool calls under the existing policy hooks. Images and truncated output can be written to private temporary files with reported paths. Model execution inside scripts remains disabled: the accounts department has declined to approve a machine that can employ another machine without establishing who receives the invoice.
The standard MCP adapter remains the runtime owner. Native engine replacement is unavail
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
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
| 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 | Development and local testing |
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
- 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.
What you can do
| 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.
Security and limits
- Single-user operation. Family accounts and deployment have been removed. Isolated-container mode is unavailable. See Access modes for validation and historical-store preservation.
- 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.
- Enabled runtime locking refuses every existing lock path, including stale or malformed records. A crash can require offline operator cleanup before startup or maintenance can proceed; never remove a lock while an owner may be running.
- 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.
Use the issue templates when reporting a problem. For code changes, read development, native validation and the repository workflow; submit changes through a pull request. make ci-full requires host and offline native qualification; make ci-fast covers the host only.
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.