QWE AI Academy So you want to run an embedded AI agent on a $10 board – the obvious question is: do you grab the Docker image or the raw Go binary? Both work. Both have traps. This guide picks Docker as the default (it’s what the official docs lead with) and tells you exactly when the binary path makes more sense.
PicoClaw is a Go-based personal AI agent from Sipeed that, per the official site, deploys as a single self-contained binary across RISC-V, ARM, x86_64 and Android. It hit 26K stars by late March 2026, and the most recent tagged release is v0.2.4 (2026-03-25), which adds the SubTurn/Hooks/Steering/EventBus agent architecture overhaul, WeChat and WeCom integration, a .security.yml config split, plus AWS Bedrock, Azure and Xiaomi MiMo providers.
Should you actually deploy PicoClaw right now?
Honest answer: it depends what “deploy” means. The project README states it plainly – PicoClaw is in early rapid development, may have unresolved security issues, and you shouldn’t run it in production before v1.0. For a home lab, a Raspberry Pi side project, or a Telegram bot on a personal VPS – fine. For anything customer-facing – wait.
The marketing line is <10MB RAM. The README footnote is more honest: recent builds may use 10-20MB because of rapid PR merges, and resource optimization is planned after feature stabilization. Plan for 20MB, not 10.
System requirements (the real numbers)
The official FAQ on picoclaw.io lists the floor and the comfortable target.
| Resource | Minimum | Recommended |
|---|---|---|
| RAM | 64MB | 512MB |
| Architecture | x86_64, ARM64, ARMv7, ARMv6, RISC-V, MIPS | x86_64 or ARM64 |
| Network | Outbound HTTPS for LLM API | Stable connection (timeout default is 120s) |
| Disk | ~50MB for binary + workspace | 1GB if using JSONL memory at scale |
| Docker | Compose v2 | Compose v2 + named volumes |
No GPU needed – inference runs at the provider’s API, not on-device. The 64MB floor assumes a stable outbound connection; without reliable HTTPS to your chosen LLM provider, even 512MB won’t save you.
Install PicoClaw v0.2.4 via Docker Compose
Four commands. The first one intentionally exits – that’s the one nobody warns you about.
# 1. Clone the official repo
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. First run - generates docker/data/config.json then EXITS
docker compose -f docker/docker-compose.yml --profile launcher up
# You'll see: "First-run setup complete." and the container stops. This is correct.
# 3. Edit your API keys
vim docker/data/config.json
# 4. Start it for real (detached)
docker compose -f docker/docker-compose.yml --profile launcher up -d
# Open http://localhost:18800That sequence comes straight from the README quickstart. But which profile do you actually want? The docs distinguish them quietly – turns out the choice matters a lot. According to the official Docker deployment guide, the gateway profile only serves webhook handlers and health endpoints; it does not expose generic REST chat endpoints or a browser UI. The launcher profile adds the Web UI on port 18800. Pick launcher if you want the browser interface; pick gateway if you only need Telegram/Discord webhooks and want a smaller surface area.
The first-time config that actually matters
Open docker/data/config.json. Two things to set before anything else: a provider with an API key, and the default model. A minimal config needs an agents block with model_name set and a model_list entry pointing the provider at your chosen endpoint – OpenAI, Claude, DeepSeek, and a dozen others are all supported as of v0.2.4.
Here’s a gotcha that bites everyone migrating from older builds. Per the pkg.go.dev module documentation: config.example.json is format version 0 with sensitive keys inline; on first run it auto-migrates to version 1+, after which config.json holds only insensitive data and API keys live in .security.yml. If you edit config.json for your API keys after migration, they won’t load and you’ll get cryptic auth errors. The key file is now .security.yml – check it exists in docker/data/ after first run.
Deploying on a remote host (not localhost)? Set
PICOCLAW_GATEWAY_HOST=0.0.0.0in your compose environment before anything else. Skip this and the gateway binds to 127.0.0.1 inside the container – your health endpoint, your webhook URL, everything appears dead from outside even though logs show it running fine. The official Docker docs flag this explicitly.
Verify the install
Three checks. Do them in order.
- Container is alive:
docker compose -f docker/docker-compose.yml ps– both services should show “running”. - Logs are clean:
docker compose -f docker/docker-compose.yml logs -f. Look for the absence of red, not a specific success line. - Agent responds:
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"If you get a reply, your provider key loaded correctly.
Common errors and what actually fixes them
These come from real GitHub issues and community write-ups, not theory.
- “Agent doesn’t respond on Telegram”: Three usual causes per the DataCamp community write-up – wrong Telegram token, missing from-user ID, or unset model/API keys. Run
docker compose -f docker/docker-compose.yml logs -f picoclaw-gatewayand the specific problem prints there. - SOUL.md edits don’t apply: GitHub issue #288 documents this – even after editing
soul.md/identity.md, removing config directories, and rebuilding the Docker image, the bot keeps its old identity. The workaround: stop the stack, delete the named volume (docker volume rm picoclaw_workspace), then re-run the first-run sequence so the workspace regenerates from your edited files. - Duplicate long-poll error: Telegram and Discord allow exactly one active long-poll consumer per token. If another process is already connected – even a stale container – you’ll get a conflict error.
docker compose down, kill any straypicoclawprocesses, then restart. - Search returns empty results: Normal if you haven’t added a Brave or DuckDuckGo key. The agent falls back to manual search links rather than failing hard.
Workspace sandbox – a feature that surprises people
The agent can’t touch anything outside its workspace directory. Destructive commands like rm are blocked – one community tester tried to delete their home folder and the guardrails stopped it cold. You can loosen this in config. Think carefully before you do.
Upgrade and uninstall
Upgrades are two commands:
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile launcher up -dBecause v0.2.4 ships the .security.yml split, the first upgrade from a pre-0.2.4 install will migrate your config.json automatically. Back up docker/data/ first. Always.
Full uninstall:
docker compose -f docker/docker-compose.yml --profile launcher down -v
docker rmi $(docker images 'sipeed/picoclaw*' -q)
cd .. && rm -rf picoclawThe -v flag removes named volumes. Without it, old config sticks around and re-binds on the next install.
When to skip Docker entirely
64MB RISC-V board? Docker is the wrong tool. Download the precompiled binary from the GitHub releases page, copy it to the device, run picoclaw agent. The official installation guide lists three deployment methods – on actual embedded hardware, the bare binary is method #1 and the right call. Docker is for VPS deployments where you already have Compose running.
There’s something worth sitting with here: PicoClaw exists because running a useful AI agent shouldn’t require a server farm. A single Go binary, no runtime, no dependency chain – it boots in under a second on a 0.6GHz processor. That design choice has real consequences for how you think about deployment. Docker is a convenience wrapper for people who already live in Docker. On the hardware PicoClaw was actually built for, it’s just a file you copy over SSH.
FAQ
Is PicoClaw safe to expose to the public internet?
No. Not yet. The maintainers say so directly in the README – wait for v1.0.
Can I use a local model instead of OpenAI?
Yes. PicoClaw speaks the OpenAI-compatible API, so any Ollama, vLLM, or LM Studio endpoint works – point model_list[].model at your local URL and drop the api_key field. If you’re running it on a homelab box that already hosts a local LLM, this cuts your per-token costs to zero and your round-trip to whatever the local hardware can deliver. The catch is RAM: PicoClaw stays under 20MB, but a 7B model alongside it needs 5-8GB more.
What’s the difference between PicoClaw and OpenClaw or NanoBot?
PicoClaw is a clean-room Go implementation, not a fork. Single binary, no Python, no Node. Features lag behind older projects but the gap closes every release.
Next: clone the repo right now, run the first-run command, and confirm “First-run setup complete.” prints. Don’t configure anything yet – just get past that one moment. That’s where most installs break.