picoclaw-ai-assistant

PicoClaw AI Assistant

Skill by ara.so — Daily 2026 Skills collection.

PicoClaw is an ultra-lightweight personal AI assistant written in Go. It runs on $10 hardware with under 10MB RAM and boots in under 1 second. It supports multiple LLM providers (OpenAI-compatible, Anthropic, Volcengine), optional web search tools, and deploys as a single self-contained binary on x86_64, ARM64, MIPS, and RISC-V Linux devices.

---

Installation

Precompiled Binary

Download from the releases page:

# Linux ARM64 (Raspberry Pi, LicheeRV-Nano, etc.)
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
chmod +x picoclaw-linux-arm64
./picoclaw-linux-arm64 onboard

Build from Source

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# Install dependencies
make deps

# Build for current platform
make build

# Build for all platforms
make build-all

# Raspberry Pi Zero 2 W — 32-bit
make build-linux-arm      # → build/picoclaw-linux-arm

# Raspberry Pi Zero 2 W — 64-bit
make build-linux-arm64    # → build/picoclaw-linux-arm64

# Build both Pi Zero variants
make build-pi-zero

# Build and install to system PATH
make install

Docker Compose

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# First run — generates docker/data/config.json then exits
docker compose -f docker/docker-compose.yml --profile gateway up

# Edit config
vim docker/data/config.json

# Start in background
docker compose -f docker/docker-compose.yml --profile gateway up -d

# View logs
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

# Stop
docker compose -f docker/docker-compose.yml --profile gateway down

Docker: Web Console (Launcher Mode)

docker compose -f docker/docker-compose.yml --profile launcher up -d
# Open http://localhost:18800

Docker: One-shot Agent Mode

# Single question
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"

# Interactive session
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent

Docker: Expose Gateway to Host

If the gateway needs to be reachable from the host, set:

PICOCLAW_GATEWAY_HOST=0.0.0.0 docker compose -f docker/docker-compose.yml --profile gateway up -d

Or set PICOCLAW_GATEWAY_HOST=0.0.0.0 in docker/data/config.json.

Termux (Android)

pkg install wget proot
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
chmod +x picoclaw-linux-arm64
termux-chroot ./picoclaw-linux-arm64 onboard

---

Quick Start

1. Initialize

picoclaw onboard

This creates ~/.picoclaw/config.json with a starter configuration.

2. Configure ~/.picoclaw/config.json

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt-4o",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "gpt-4o",
      "model": "openai/gpt-4o",
      "api_key": "$OPENAI_API_KEY",
      "request_timeout": 300
    },
    {
      "model_name": "claude-sonnet",
      "model": "anthropic/claude-sonnet-4-5",
      "api_key": "$ANTHROPIC_API_KEY"
    },
    {
      "model_name": "ark-code",
      "model": "volcengine/ark-code-latest",
      "api_key": "$VOLCENGINE_API_KEY",
      "api_base": "https://ark.cn-beijing.volces.com/api/coding/v3"
    }
  ],
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "$BRAVE_API_KEY"
      },
      "tavily": {
        "enabled": false,
        "api_key": "$TAVILY_API_KEY"
      }
    }
  }
}

Never hard-code API keys. Reference environment variables using $VAR_NAME notation in config, or set them in your shell environment before launch.

3. Run

# Interactive chat
picoclaw

# Single message
picoclaw -m "Summarize the latest Go release notes"

# Use a specific model
picoclaw -model claude-sonnet -m "Refactor this function for clarity"

---

Key CLI Commands

---

Configuration Reference

Model Entry Fields

{
  "model_name": "my-model",        // Alias used in -model flag and agent defaults
  "model": "provider/model-id",    // Provider-prefixed model identifier
  "api_key": "$ENV_VAR",           // API key — use env var reference
  "api_base": "https://...",       // Optional: override base URL (for self-hosted or regional endpoints)
  "request_timeout": 300           // Optional: seconds before timeout
}

Supported Provider Prefixes

Agent Defaults

"agents": {
  "defaults": {
    "workspace": "~/.picoclaw/workspace",  // Working directory for file operations
    "model_name": "gpt-4o",                // Default model alias
    "max_tokens": 8192,                    // Max response tokens
    "temperature": 0.7,                    // Sampling temperature
    "max_tool_iterations": 20              // Max agentic tool-call loop iterations
  }
}

Web Search Tools

Get free API keys:

• Tavily: https://tavily.com — 1,000 free queries/month
• Brave Search: https://brave.com/search/api — 2,000 free queries/month

"tools": {
  "web": {
    "tavily": {
      "enabled": true,
      "api_key": "$TAVILY_API_KEY"
    },
    "brave": {
      "enabled": false,
      "api_key": "$BRAVE_API_KEY"
    }
  }
}

Only enable one search provider at a time unless you want fallback behavior.

---

Common Patterns

Pattern: Minimal $10 Device Setup

For a LicheeRV-Nano or similar ultra-low-resource board:

# Download the RISC-V or ARM binary from releases
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-riscv64
chmod +x picoclaw-linux-riscv64

# Initialize
./picoclaw-linux-riscv64 onboard

# Edit config — use a lightweight model, low max_tokens
cat > ~/.picoclaw/config.json << 'EOF'
{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt-4o-mini",
      "max_tokens": 2048,
      "temperature": 0.5,
      "max_tool_iterations": 10
    }
  },
  "model_list": [
    {
      "model_name": "gpt-4o-mini",
      "model": "openai/gpt-4o-mini",
      "api_key": "$OPENAI_API_KEY",
      "request_timeout": 120
    }
  ]
}
EOF

./picoclaw-linux-riscv64

Pattern: Full-Stack Dev Assistant with Web Search

{
  "agents": {
    "defaults": {
      "workspace": "~/projects",
      "model_name": "claude-sonnet",
      "max_tokens": 8192,
      "temperature": 0.3,
      "max_tool_iterations": 30
    }
  },
  "model_list": [
    {
      "model_name": "claude-sonnet",
      "model": "anthropic/claude-sonnet-4-5",
      "api_key": "$ANTHROPIC_API_KEY",
      "request_timeout": 600
    }
  ],
  "tools": {
    "web": {
      "tavily": {
        "enabled": true,
        "api_key": "$TAVILY_API_KEY"
      }
    }
  }
}

Pattern: Docker with Environment Variables

# docker/docker-compose.override.yml
services:
  picoclaw-gateway:
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - TAVILY_API_KEY=${TAVILY_API_KEY}
      - PICOCLAW_GATEWAY_HOST=0.0.0.0

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
docker compose -f docker/docker-compose.yml -f docker/docker-compose.override.yml --profile gateway up -d

Pattern: Build for a Specific Target in Go

# Cross-compile for MIPS (OpenWRT routers)
GOOS=linux GOARCH=mips GOMIPS=softfloat go build -o build/picoclaw-linux-mips ./cmd/picoclaw

# Cross-compile for 32-bit ARM (older Raspberry Pi)
GOOS=linux GOARCH=arm GOARM=7 go build -o build/picoclaw-linux-arm ./cmd/picoclaw

# Cross-compile for RISC-V 64-bit
GOOS=linux GOARCH=riscv64 go build -o build/picoclaw-linux-riscv64 ./cmd/picoclaw

---

Troubleshooting

Binary won't execute on device

# Verify the binary matches the device architecture
file picoclaw-linux-arm64
uname -m   # Should match: aarch64 = arm64, x86_64 = amd64

# Ensure executable permission
chmod +x picoclaw-linux-arm64

"Permission denied" on Termux

Termux requires proot for some system calls:

pkg install proot
termux-chroot ./picoclaw-linux-arm64 onboard

API key not recognized

• Do not use "api_key": "sk-..." literals in config — set env vars and reference them as "$OPENAI_API_KEY".
• Verify the env var is exported in your current shell: echo $OPENAI_API_KEY.

Docker gateway not reachable from host

Set PICOCLAW_GATEWAY_HOST=0.0.0.0 in the environment or in config.json before starting the container.

High memory usage in recent versions

The project notes that recent PRs may push RAM usage to 10–20MB. If this is a concern on ultra-low-memory devices, pin to an earlier release tag:

git checkout v0.1.1
make build

Config file location

Default: ~/.picoclaw/config.json

Override at runtime:

picoclaw -config /path/to/custom-config.json

Rebuild after dependency changes

cd picoclaw
make deps
make build

---

Hardware Targets Quick Reference