GitHub - rcarmo/piclaw: I'm going to build my own OpenClaw, with blackjack... and bun!

6 min read Original article ↗

piclaw — A pi-based general-purpose agent

PiClaw

PiClaw is a Docker-based sandbox for running the Pi Coding Agent in an isolated Debian environment. It bundles piclaw — a web-first orchestrator built on the Pi SDK with persistent sessions, a streaming web UI, and scheduled tasks. WhatsApp is optional. Inspired by agentbox and nanoclaw.

Highlights

Demo Animation

  • Streaming web UI — real-time token-by-token updates over SSE, with Markdown, KaTeX, Mermaid, and Adaptive Cards
  • Adaptive Cards + structured actions — inline cards, persisted submissions, read-only finished cards, and built-in /test-card validation flows so structured UI behaves like a proper feature rather than a hopeful sketch
  • Workspace explorer — file tree sidebar with previews, file reference pills, and downloads
  • Disk usage starburst — folder-size visualization with hover details and drill-down
  • Code editor — built-in CodeMirror 6 with syntax highlighting for 12 languages, search/replace, and save
  • Persistent storage — SQLite-backed messages, media, tasks, token usage, and encrypted keychain
  • Skills — setup, debugging, Playwright, scheduling, charts, web search, Adaptive Card authoring, and more
  • Passkeys + TOTP authentication — optional WebAuthn passkeys with TOTP fallback (iOS/Android webapp support)
  • WhatsApp — optional secondary channel

Quick Start

make build    # Build the Docker image
make up       # Start the container (supervisord launches piclaw)

Open http://localhost:8080 in your browser. To use pi interactively instead:

docker exec -u agent -it piclaw bash
cd /workspace && pi

Setting up provider credentials

The easiest way to set up model/provider credentials is from the terminal pane in the web UI.

Note

For security, the authenticated web terminal is disabled by default. To use it, set PICLAW_WEB_TERMINAL_ENABLED=1 before starting piclaw, for example:

PICLAW_WEB_TERMINAL_ENABLED=1 make up
  1. Open the web UI.
  2. Click the terminal button to open the terminal pane.
  3. Run pi /login.
  4. Follow the provider flow:
    • for OAuth/device-login providers, complete the browser/device-code sign-in
    • for API-key-based providers, enter or configure the required key/secret as prompted

This stores credentials in the agent profile inside the container, so the web UI and tools can reuse them afterwards.

If you prefer, you can do the same via docker exec or /shell <command> in the web UI. See docs/configuration.md for details.

Web UI

The UI is single-user, mobile-friendly, and streams updates over SSE:

  • Thought/Draft panels — visible during streaming
  • Live steering + queued follow-ups — keep typing while the agent is busy
  • Adaptive Cards — inline cards, compact submission receipts, and finished cards that display submitted values read-only
  • /btw side conversations — a lightweight side panel for streamed side prompts that can later inject back into the main chat
  • File attachments with download links
  • Link previews via server-side OpenGraph fetch
  • Multi-turn threading — subsequent turns are visually threaded under the first
  • Themes + tinting — presets plus /theme and /tint commands (Solarized auto light/dark)
  • Terminal pane — optional authenticated shell inside the container for setup tasks like running pi /login to add provider credentials (enable with PICLAW_WEB_TERMINAL_ENABLED=1)
  • Context usage indicator — compose-footer pie indicator refreshes on reconnect and when returning to the tab, instead of lingering until the next poll cycle takes notice
  • Mobile-first layout with webapp manifest

Workspace explorer

The sidebar shows a file tree of /workspace with auto-refresh. Click a file to preview it or add a file reference pill to the next prompt. Drag and drop files onto the tree to upload them. It also includes a folder-size starburst preview with hover details and drill-down.

Code editor

Click the pencil icon on any text file preview (up to 256 KB) to open the built-in editor. It appears as a resizable centre pane between the sidebar and the chat.

  • 12 languages — JS/TS (JSX/TSX), Python, Go, JSON, CSS, HTML, YAML, SQL, XML/SVG, Markdown, Shell
  • Search and replace — Cmd/Ctrl+F and Cmd/Ctrl+H
  • Save — Cmd/Ctrl+S or the Save button; dirty state is tracked
  • Line wrapping, line numbers, and active line highlight
  • Vendored bundle (~245 KB gzip) — no external CDN dependencies

Volumes

Mount Container path Contents
Home /config Agent home (.pi/, .gitconfig, .bashrc)
Workspace /workspace Projects, piclaw state, notes

Never delete /workspace/.piclaw/store/messages.db — it holds all chat history, media, and tasks.

Configuration

Key environment variables:

Variable Default Purpose
PICLAW_WEB_PORT 8080 Web UI port
PICLAW_WEB_TERMINAL_ENABLED 0 Enable the authenticated web terminal pane/backend; disabled by default for security
PICLAW_WEB_TOTP_SECRET (empty) Base32 TOTP secret; enables login gate
PICLAW_WEB_PASSKEY_MODE totp-fallback Passkey mode: totp-fallback, passkey-only, or totp-only
PICLAW_ASSISTANT_NAME PiClaw Display name in the UI
PICLAW_KEYCHAIN_KEY (empty) Master key for encrypted secret storage

For the full list (TLS, reverse proxies, timeouts, Pushover, WhatsApp, keychain, external workspaces), see docs/configuration.md.

Reverse proxies / tunnels

If piclaw is running behind a reverse proxy or tunnel (for example Cloudflare Tunnel, Caddy, or Nginx TLS termination), enable proxy trust:

See docs/reverse-proxy.md for the full operator guide, required forwarded headers, Cloudflare Tunnel example, generic reverse-proxy examples, and troubleshooting notes.

Development

make build-piclaw    # Full build: vendor bundle + web assets + TypeScript
make vendor          # Rebuild CodeMirror vendor bundle only
make lint            # ESLint
make test            # Run all tests
make local-install   # Pack, install globally, and restart piclaw

Tests use the Bun runner (cd piclaw && bun test). Sequential mode is recommended for SQLite safety (--max-concurrency=1).

CI / Release

Pushing a version tag triggers .github/workflows/publish.yml — multi-arch builds (amd64 + arm64) published to GHCR.

make bump-patch   # bump patch version, commit, and tag
make bump-minor   # bump minor version, commit, and tag
make push         # push commits + tag → triggers CI

Container runtime

PiClaw works with any OCI-compliant runtime:

  • Docker / Docker Desktop — primary target
  • Apple Containers (macOS 26+)
  • Podman, nerdctl, etc.

Documentation

Credits

Licence

MIT