Skip to main content

​
Installation

PicoClaw supports multiple installation methods across different platforms. Choose the method that works best for your environment.

Precompiled Binary

Fastest way to get started (recommended)

Build from Source

Latest features and custom builds

Docker Compose

Containerized deployment

Android (Termux)

Run on old Android phones

​
Precompiled Binary

The easiest way to install PicoClaw is to download a precompiled binary for your platform.
1

Download the Binary

Visit the GitHub Releases page and download the appropriate binary for your platform:Available Platforms:
  • picoclaw-linux-amd64 — Linux x86_64
  • picoclaw-linux-arm64 — Linux ARM64 (Raspberry Pi 4, etc.)
  • picoclaw-linux-arm — Linux ARM 32-bit (Raspberry Pi Zero 2 W with 32-bit OS)
  • picoclaw-linux-riscv64 — Linux RISC-V 64-bit
  • picoclaw-darwin-amd64 — macOS Intel
  • picoclaw-darwin-arm64 — macOS Apple Silicon
# Replace v0.1.1 with the latest version
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-amd64
2

Make it Executable

Add execute permissions to the downloaded binary:
chmod +x picoclaw-linux-amd64
Replace picoclaw-linux-amd64 with the actual filename you downloaded.
3

Move to PATH (Optional)

For easier access, move the binary to a directory in your PATH:
# Rename and move to /usr/local/bin
sudo mv picoclaw-linux-amd64 /usr/local/bin/picoclaw
Now you can run picoclaw from anywhere!
4

Verify Installation

Check that PicoClaw is installed correctly:
picoclaw --version
You should see version information printed to the terminal.

​
Platform-Specific Notes

The Raspberry Pi Zero 2 W can run either 32-bit or 64-bit operating systems. Choose the correct binary:
  • 32-bit Raspberry Pi OS → Use picoclaw-linux-arm
  • 64-bit Raspberry Pi OS → Use picoclaw-linux-arm64
Check your OS architecture:
uname -m
# armv7l = 32-bit (use picoclaw-linux-arm)
# aarch64 = 64-bit (use picoclaw-linux-arm64)
On macOS, you may see a security warning when running the binary. To allow it:
xattr -d com.apple.quarantine picoclaw-darwin-arm64
Or go to System Preferences → Security & Privacy and click “Allow Anyway”.
For RISC-V devices like LicheeRV-Nano, use the picoclaw-linux-riscv64 binary:
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-riscv64
chmod +x picoclaw-linux-riscv64
./picoclaw-linux-riscv64 onboard

​
Build from Source

Building from source gives you access to the latest features and allows for custom builds.
Requirements:
  • Go 1.21 or higher
  • Git
  • Make (optional, but recommended)
1

Clone the Repository

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

Install Dependencies

make deps
This installs all required Go dependencies.
3

Build PicoClaw

Choose one of the following build options:
# Build for your current platform
make build

# Binary will be in build/picoclaw-<platform>-<arch>
4

Run PicoClaw

After building, run the binary:
# If you used 'make install'
picoclaw onboard

# Or run directly from build directory
./build/picoclaw-linux-amd64 onboard

​
Advanced Build Options

The WhatsApp native integration is optional to keep the binary small. To include it:
make build-whatsapp-native
Or manually:
go build -tags whatsapp_native ./cmd/picoclaw
For custom compilation:
# Static binary (no external dependencies)
CGO_ENABLED=0 go build -ldflags="-s -w" -o picoclaw ./cmd/picoclaw

# With version information
go build -ldflags="-X main.Version=v1.0.0" -o picoclaw ./cmd/picoclaw
For development with hot reload:
# Install air for hot reload
go install github.com/cosmtrek/air@latest

# Run with auto-reload
air

​
Available Makefile Targets

CommandDescription
make depsInstall Go dependencies
make buildBuild for current platform
make build-allCross-compile for all platforms
make build-linux-amd64Build for Linux x86_64
make build-linux-arm64Build for Linux ARM64
make build-linux-armBuild for Linux ARM 32-bit
make build-pi-zeroBuild both ARM variants for Pi Zero 2 W
make installBuild and install to /usr/local/bin
make cleanRemove build artifacts

​
Docker Installation

Run PicoClaw in a containerized environment without installing anything locally.
1

Clone the Repository

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

Initial Setup

Run the first-time setup to generate the config file:
docker compose -f docker/docker-compose.yml --profile gateway up
The container will print “First-run setup complete.” and exit. This creates docker/data/config.json.
3

Configure API Keys

Edit the generated config file:
vim docker/data/config.json
Add your API keys for LLM providers, bot tokens, etc. See the Quickstart for details.
4

Start the Gateway

Start PicoClaw in detached mode:
docker compose -f docker/docker-compose.yml --profile gateway up -d
Docker Network Access: By default, the Gateway listens on 127.0.0.1 which is not accessible from the host. If you need to access health endpoints or expose ports, set PICOCLAW_GATEWAY_HOST=0.0.0.0 in your environment or update config.json.
5

Verify it's Running

Check the logs:
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

​
Docker Agent Mode (One-shot)

For quick questions without running the gateway: 
# Ask a single question
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"

​
Managing Docker Deployment

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

​
Android (Termux)

Give your decade-old Android phone a second life by turning it into a smart AI Assistant!
1

Install Termux

Download Termux from F-Droid or Google Play.
Use the F-Droid version for the latest updates. The Google Play version is often outdated.
2

Download PicoClaw

Inside Termux, download the ARM64 binary:
# Replace v0.1.1 with the latest version
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
chmod +x picoclaw-linux-arm64
3

Install proot

PicoClaw needs a Linux-like environment:
pkg install proot
4

Initialize PicoClaw

Run the onboarding process:
termux-chroot ./picoclaw-linux-arm64 onboard
Follow the instructions to complete configuration.
5

Start Using

Run PicoClaw commands:
termux-chroot ./picoclaw-linux-arm64 agent -m "Hello!"
Now your old Android phone is a fully functional AI assistant! Proceed to the Quick Start guide to configure it.

​
Next Steps

Quick Start

Configure PicoClaw and start chatting

Configuration

Deep dive into configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us