PiClaw provides a self-hosted, stateful AI agent experience through a web-first sandbox. It targets users who need a practical, integrated local agent without managing multiple services, offering a persistent environment with rich workspace tooling and a streaming UI. The primary benefit is a unified, user-friendly platform for running and interacting with AI agents locally.

How It Works

PiClaw packages the Pi Coding Agent into a Debian sandbox, accessible via a streaming web UI. It ensures persistent agent state using SQLite for messages, media, tasks, and token usage, alongside an encrypted keychain. The architecture supports a workspace-native workflow, enabling file browsing, document previews, and file referencing within prompts. It integrates various tools like an editor, Office viewer, Draw.io, and viewers for CSV, PDF, images, and video, alongside agent control features such as steering, queued follow-ups, and scheduled tasks.

Quick Start & Requirements

• Primary Install: Use the official Docker image: ghcr.io/rcarmo/piclaw:latest.
• Run Command:

  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
  

• Access: Navigate to http://localhost:8080.
• Build from Source: Execute make build and make up. For host user matching, use PUID=$(id -u) PGID=$(id -g) make up.
• Prerequisites: An OCI-compliant container runtime (Docker, Podman, etc.).
• Configuration: Model setup is done via /login within the container, reusing existing Pi Agent credentials. The authenticated web terminal can be enabled with PICLAW_WEB_TERMINAL_ENABLED=1.
• Links: Docker Image: ghcr.io/rcarmo/piclaw:latest.

Highlighted Details

• Streaming Web UI: Features real-time chat with support for Markdown, KaTeX, Mermaid, and Adaptive Cards, including thought/draft panels and live steering.
• Persistent State: SQLite-backed storage for chat history, media, tasks, token usage, and an encrypted keychain.
• Workspace Tooling: Integrated file explorer with previews, drag-and-drop uploads, and an editor (CodeMirror 6).
• Built-in Viewers: Includes Draw.io, Office document viewers (.docx, .xlsx, .pptx), CSV/TSV tables, PDFs, images, and videos.
• Agent Control: Supports steering, queued follow-ups, threading, side prompts, and scheduled tasks.
• Optional WhatsApp Integration: For extended communication channels.

Maintenance & Community

The project is maintained by rcarmo and inspired by agentbox and nanoclaw. Release management involves make bump-patch/minor and make push to publish multi-arch images to GHCR. No direct community links (e.g., Discord, Slack) or specific contributor/sponsorship details are provided in the README.

Licensing & Compatibility

• License: MIT.
• Compatibility: Permissive for commercial use and integration with closed-source projects due to the MIT license. Works with any OCI-compliant container runtime.

Limitations & Caveats

Source builds are primarily for development. Model provider login is currently terminal-first. The authenticated web terminal is disabled by default. Running behind a reverse proxy requires setting PICLAW_TRUST_PROXY=1. Critical agent state, including chat history and media, is stored in /workspace/.piclaw/store/messages.db and should not be deleted.