Skip to main content

​
Overview

PicoClaw’s ultra-lightweight design makes it perfect for Raspberry Pi devices. With less than 10MB RAM usage and fast startup times, it runs smoothly even on low-powered boards like the Pi Zero 2 W.

​
Supported Devices

  • Raspberry Pi Zero 2 W (tested)
  • Raspberry Pi 3/4/5
  • Any Raspberry Pi with ARMv7 (32-bit) or ARM64 (64-bit) support

​
Performance Expectations

MetricPerformance
RAM Usage< 10MB
Boot Time~1 second (even on 0.6GHz single core)
ArchitectureARM (32-bit), ARM64 (64-bit)

​
Installation Methods

​
Method 1: Download Precompiled Binary

  1. Download the appropriate binary for your Raspberry Pi OS:
# For 32-bit Raspberry Pi OS
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm
chmod +x picoclaw-linux-arm
sudo mv picoclaw-linux-arm /usr/local/bin/picoclaw

# For 64-bit Raspberry Pi OS
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
chmod +x picoclaw-linux-arm64
sudo mv picoclaw-linux-arm64 /usr/local/bin/picoclaw
Replace v0.1.1 with the latest version from the Releases page.
  1. Initialize PicoClaw:
picoclaw onboard
  1. Configure your API keys in ~/.picoclaw/config.json
  2. Test the installation: 
picoclaw agent -m "Hello from Raspberry Pi!"

​
Method 2: Build from Source

Building from source gives you the latest features and allows customization.

​
Prerequisites

# Install Go 1.21 or higher
sudo apt update
sudo apt install -y golang-go git make

# Verify Go installation
go version

​
Build Instructions

# Clone the repository
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# Install dependencies
make deps

# Build for your Raspberry Pi
# For 32-bit OS (ARMv7):
make build-linux-arm

# For 64-bit OS (ARM64):
make build-linux-arm64

# Or build both versions:
make build-pi-zero

​
Binary Locations

After building:
  • 32-bit binary: build/picoclaw-linux-arm
  • 64-bit binary: build/picoclaw-linux-arm64

​
Install the Binary

# For 32-bit:
sudo cp build/picoclaw-linux-arm /usr/local/bin/picoclaw

# For 64-bit:
sudo cp build/picoclaw-linux-arm64 /usr/local/bin/picoclaw

# Make it executable
sudo chmod +x /usr/local/bin/picoclaw

​
Determining Your OS Architecture

Use the binary that matches your Raspberry Pi OS: 
# Check your architecture
uname -m
OutputOS TypeBinary to Use
armv7l32-bitpicoclaw-linux-arm
aarch6464-bitpicoclaw-linux-arm64

​
Configuration

​
Basic Configuration

After installation, configure PicoClaw: 
picoclaw onboard
Edit ~/.picoclaw/config.json to set your API keys: 
{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key"
    }
  ]
}

​
Running as a Service

For always-on operation, see the systemd setup guide.

​
Raspberry Pi Zero 2 W Specific Notes

The Pi Zero 2 W has:
  • 512MB RAM (PicoClaw uses <10MB)
  • 1GHz quad-core ARM Cortex-A53
  • WiFi and Bluetooth
Tips for Pi Zero 2 W:
  1. Use 32-bit OS - Better memory efficiency on 512MB RAM
  2. Enable swap - Recommended for stability:
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set CONF_SWAPSIZE=512
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
  1. Optimize config - Use lower max_tokens to reduce memory:
{
  "agents": {
    "defaults": {
      "max_tokens": 4096
    }
  }
}

​
Troubleshooting

​
Binary Won’t Run

# Check file permissions
ls -l /usr/local/bin/picoclaw

# Make it executable
sudo chmod +x /usr/local/bin/picoclaw

​
Out of Memory Errors

  • Check current memory usage: free -h
  • Reduce max_tokens in config
  • Enable swap (see Pi Zero notes above)
  • Close other applications

​
Slow Performance

  • Ensure you’re using the correct binary for your architecture
  • Check CPU temperature: vcgencmd measure_temp
  • Ensure adequate cooling

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us