piclaw — your self-hosted AI workspace #

PiClaw packages the Pi Coding Agent into a self-hosted workspace with a streaming web UI, multi-provider LLM support, persistent state, and a growing collection of built-in tools — code editor, terminal, VNC client, document viewers, kanban boards, and autonomous experiment loops.

It is built for people who want a practical, stateful agent they can run locally or in a container without stitching together half a dozen separate services.

Why PiClaw #

• Streaming web UI — real-time chat with Markdown, KaTeX, Mermaid, and Adaptive Cards
• Persistent agent state — SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH / Proxmox / Portainer profiles
• Workspace-native workflow — browse files, preview documents, upload attachments, drag files into the workspace explorer with progress feedback and a client-side size guard, edit code, reference files in prompts, and optionally flip core tools to a remote SSH host for the current session
• Built-in tools — Ghostty-based terminal, code editor, Office/PDF/CSV/image/video viewers, draw.io, kanban board and mindmap editors, VNC client, browser automation, sharp-backed image processing, bundled MCP access via pi-mcp-adapter, and agent-only infrastructure tools for SSH, Proxmox, and Portainer
• Agent control features — steering, queued follow-ups, threading, side prompts, autoresearch experiment loops, and scheduled tasks
• Context conservation by default — small always-active tool baseline, staged tool/script discovery via list_tools / list_scripts (filtered or intent-guided discovery → compact summary → on-demand detail → activate/use), lazy activation for non-default tools, and opt-in examples for higher-detail workflow help
• Optional auth and channels — passkeys/TOTP for the web UI, plus optional WhatsApp integration

Quick start #

mkdir -p ./home ./workspace

docker run -d \
  --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 when you are not using one of the built-in hosted providers.

Web UI #

PiClaw is single-user, mobile-friendly, and streams updates over SSE.

Chat #

• Thought and draft panels during streaming
• Live steering and queued follow-ups
• Adaptive Cards with persisted submissions
• /btw side conversations
• File attachments, link previews, threaded turns, and syntax-highlighted previews for common text/code attachments
• Themes and tinting via /theme and /tint
• Mobile-friendly layout with webapp manifest

Workspace #

• Sidebar file browser with auto-refresh, drag-and-drop upload progress, and a client-side 256 MB upload guard before the request even starts
• File-reference pills in prompts
• Folder sizes in the starburst explorer
• Workspace search index status with one-click reindex from the explorer header

Editor #

• CodeMirror 6 with syntax highlighting for JS/TS, Python, Go, JSON, CSS, HTML, YAML, SQL, XML/SVG, Markdown, and Shell
• Search and replace, dirty-state tracking, line wrapping
• Lazy-loaded local bundle — no CDN dependency

Terminal #

• Ghostty-based web terminal — a real shell in the browser, not a simulation
• Runs as a dock panel or a standalone tab
• Detachable into popout windows with live session transfer
• Enabled by default on Linux and macOS; disable with PICLAW_WEB_TERMINAL_ENABLED=0
• Still disabled by default on Windows

Viewers #

• Draw.io — self-hosted editor with SVG/PNG/XML export back to workspace
• Office documents — .docx, .xlsx, .pptx, .odt, .ods, .odp
• CSV/TSV — dedicated table viewer
• PDF, images, video — inline viewers
• Text/code attachments — syntax-highlighted timeline preview modal for common code/config formats
• Kanban boards — *.kanban.md in a drag-and-drop board editor (Obsidian Kanban compatible)
• Mindmaps — *.mindmap.yaml in a D3/SVG visual editor
• VNC remote display — connect to allowlisted targets from a tab, with direct-connect enabled by default on Linux, macOS, and Windows (experimental); disable with PICLAW_WEB_VNC_ALLOW_DIRECT=0

Automation #

• /image and /flux — workspace-backed image generation commands for Azure OpenAI / Foundry; /image now supports --transparent for transparent PNG output when the Azure OpenAI model supports it
• image_process — sharp-backed workspace image manipulation for resize/crop/convert/optimise, metadata inspection, text/SVG/composite operations, and animated GIF frame/spritesheet workflows
• cdp_browser — Chromium/Edge/Chrome automation via CDP for navigation, JS evaluation, DOM clicking, and screenshots
• mcp via pi-mcp-adapter — token-efficient access to external MCP servers configured through .pi/mcp.json
• Experimental m365 extension — opt-in Microsoft 365 automation bundle for Teams, Graph, OneDrive, SharePoint, and calendar flows; enable with PICLAW_ENABLE_M365_EXPERIMENTAL=1 (primarily validated on Windows with YOLO mode, with Edge → Chrome → Chromium browser lookup across Windows/macOS/Linux). Graph-backed consumer-account support now exists; Teams chat flows still require a work/school tenant, and the auth/browser reuse path now follows the current Teams web-app entry instead of the stale legacy route.
• win_* tools — Windows-only desktop automation via Win32 FFI for window enumeration, screenshots, element inspection, clicking, typing, and process management. No-ops on non-Windows platforms.

Configuration #

Key environment variables:

For the full list, auth setup (TOTP/passkeys), session-scoped SSH-backed remote tools, reverse proxy configuration, and SSHFS/FUSE support, 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.

On Windows, PiClaw remains a secondary / not-officially-supported target. Shell-like child processes now run attached there (detached=false) so stdout/stderr remain capturable; Unix-like hosts still use detached process groups for cleaner tree termination on abort/shutdown.

Build from source #

See docs/development.md.

Documentation #

Setup & operations

• Configuration — environment variables, auth, reverse proxy, SSHFS
• Install from repo — Bun-based Docker-free install
• Release process — versioning, tagging, publishing

Architecture & internals

• Architecture
• Runtime flows
• Storage model
• Web pane extensions
• Extension UI contract

Reference

• Tools and skills — includes the uniform ssh / proxmox / portainer control surface (discover, capabilities, recommend, request, workflow) and the context-conserving discovery flow
• Keychain
• WhatsApp
• Cross-instance interop
• MCP via pi-mcp-adapter
• Azure OpenAI extension — managed-identity provider notes plus /image and /flux behaviour
• Experimental M365 extension — Microsoft 365 browser-auth automation, including current consumer-account support boundaries
• Development

Credits #

• rcarmo/agentbox
• qwibitai/nanoclaw
• badlogic/pi-mono
• davebcn87/pi-autoresearch — autonomous experiment loop by Tobi Lutke and David Cortés (vendored under runtime/vendor/autoresearch/)

Licence #

MIT