PicoClaw

Overview

PicoClaw is a lightweight AI gateway and dashboard. In this homelab, we use the Launcher edition (ghcr.io/sipeed/picoclaw:launcher), which combines the AI backend engine with a sleek web-based dashboard.

It connects to Home Assistant via MCP (streamable-http), enabling natural language control of devices, while exposing a web UI for chat and agent management. The system is fully declarative, using Mistral Small as the primary inference model. Secrets are fetched from 1Password at startup, and the container home is persistently mounted to ensure session stability.

Ports

Port	Protocol	Purpose
18800	TCP/HTTP	Launcher Web UI (Dashboard & API)
18790	TCP/HTTP	Gateway Inter-process (internal only)

External Access

The service is primarily used locally. The dashboard is protected by a persistent access token.

Access Method	Details
Web UI	http://<homelab.ip>:18800
Telegram	@JavierSCBot (private restricted bot)
Login Token	Uses the master Homelab password from 1Password.

[!TIP] To bypass the login screen automatically, use the token in the URL: http://<homelab.ip>:18800/?token=YOUR_1PASSWORD_TOKEN

Secrets

Credentials are fetched by picoclaw-secrets.service into /run/picoclaw/env at boot, then picoclaw-config.service renders config.json and runtime files. No secrets touch the Nix store.

Secret	1Password Item	Description
Launcher Token	op://Homelab/Homelab/password	The Web UI password.
Mistral API key	op://Homelab/PicoClaw - Mistral AI Token/credential	Primary key for Mistral Small/Large.
OpenRouter API key	op://Homelab/PicoClaw - OpenRouter Token/credential	Key for LLM fallback (Nemotron, etc).
Groq API key	op://Homelab/OpenClaw - Groq API Key/credential	Key for Groq fast inference.
Gemini API key	op://Homelab/OpenClaw - Gemini API Key/credential	Key for Gemini 2.0 Flash.
Telegram bot token	op://Homelab/PicoClaw - Telegram Token/credential	Bot API token from @BotFather.
Home Assistant token	op://Homelab/Home Assistant - PicoClaw Token/credential	Bearer token for MCP integration.
OpenCode Zen Token	op://Homelab/OpenCode - Zen Token/credential	Key for Big Pickle model via OpenCode.

Architecture

Unified Home Pattern

The container entrypoint requires a specific directory structure to bypass the initial setup wizard. We mount a single directory from the host to the container’s home:

• Host Path: /var/lib/picoclaw/.picoclaw
• Container Path: /root/.picoclaw

Inside this directory, the following files are pre-generated:

• config.json: Engine configuration (models, channels, tools).
• launcher-config.json: Dashboard configuration (port, public mode).
• workspace/: Persistent storage for agent data and memory.

Token Persistence

The PICOCLAW_LAUNCHER_TOKEN environment variable is used to set a static access token. This prevents the system from generating a random token on every restart, which would invalidate browser sessions.

Backup

State is backed up daily to Backblaze B2 via Restic.

• Backup Path: /var/lib/picoclaw
• Exclusions: Heavy ephemeral data (logs, temp workspaces).

Retention policy: 7 daily, 4 weekly, 6 monthly snapshots.

Troubleshooting

Stuck at “Setup / Set Password” screen

Symptom: The Web UI asks to create a new password instead of showing the login screen. Cause: The container entrypoint didn’t find config.json in /root/.picoclaw/. Fix: Ensure the volumes are correctly mounted and the picoclaw-config service is running. Check with sudo podman exec picoclaw ls -la /root/.picoclaw/.

”Invalid Pico token” in chat

Cause: Reusing the Launcher Token as the internal pico channel token. Fix: In config.json, use a distinct secret for channels.pico.token (currently set to a fixed internal string in modules/nixos/services/picoclaw.nix).

Home Assistant MCP connection refused

Cause: The container is not using the host network. Fix: Verify --network=host is in the extraOptions of the OCI container definition.

Check Logs

# Secret fetching & config rendering
sudo journalctl -u picoclaw-secrets -f
sudo journalctl -u picoclaw-config -f

# Main container logs
sudo podman logs -f picoclaw

picoclaw