Installation

Install PicoClaw from precompiled binaries or build from source

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

   Linux x86_64

   # 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

Raspberry Pi Zero 2 W

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)

macOS Gatekeeper Warning

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”.

RISC-V Devices

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:

   Standard Build

   # 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

Build with WhatsApp Native Support

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

Custom Build Flags

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

Development Build

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

Command	Description
make deps	Install Go dependencies
make build	Build for current platform
make build-all	Cross-compile for all platforms
make build-linux-amd64	Build for Linux x86_64
make build-linux-arm64	Build for Linux ARM64
make build-linux-arm	Build for Linux ARM 32-bit
make build-pi-zero	Build both ARM variants for Pi Zero 2 W
make install	Build and install to /usr/local/bin
make clean	Remove 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:

One-shot Question

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

Managing Docker Deployment

View Logs

# 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