> ## Documentation Index
> Fetch the complete documentation index at: https://sipeed-picoclaw-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#precompiled-binary)**
>
> Fastest way to get started (recommended)

> **[Build from Source](#build-from-source)**
>
> Latest features and custom builds

> **[Docker Compose](#docker-installation)**
>
> Containerized deployment

> **[Android (Termux)](#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](https://github.com/sipeed/picoclaw/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

```bash Linux x86_64 theme={null}
# Replace v0.1.1 with the latest version
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-amd64
```

```bash Linux ARM64 theme={null}
# For Raspberry Pi 4, ARM64 boards
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
```

```bash Linux ARM (32-bit) theme={null}
# For Raspberry Pi Zero 2 W (32-bit OS)
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm
```

```bash macOS Apple Silicon theme={null}
# For M1/M2/M3 Macs
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-darwin-arm64
```

**2. Make it Executable**

Add execute permissions to the downloaded binary:

```bash theme={null}
chmod +x picoclaw-linux-amd64
```

> [!NOTE]
>
> 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:

```bash theme={null}
# 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:

```bash theme={null}
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:
>
> ```bash theme={null}
> 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:
>
> ```bash theme={null}
> 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:
>
> ```bash theme={null}
> 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.

> [!NOTE]
>
> **Requirements:**
>
> * Go 1.21 or higher
> * Git
> * Make (optional, but recommended)

**1. Clone the Repository**

```bash theme={null}
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
```

**2. Install Dependencies**

```bash theme={null}
make deps
```

This installs all required Go dependencies.

**3. Build PicoClaw**

Choose one of the following build options:

```bash Standard Build theme={null}
# Build for your current platform
make build

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

```bash Build & Install theme={null}
# Build and install to /usr/local/bin
make install
```

```bash Build All Platforms theme={null}
# Cross-compile for all supported platforms
make build-all

# Outputs:
# - build/picoclaw-linux-amd64
# - build/picoclaw-linux-arm64
# - build/picoclaw-linux-arm
# - build/picoclaw-darwin-amd64
# - build/picoclaw-darwin-arm64
# - etc.
```

```bash Raspberry Pi Zero 2 W theme={null}
# Build both ARM variants
make build-pi-zero

# Or build specifically:
make build-linux-arm      # 32-bit
make build-linux-arm64    # 64-bit
```

**4. Run PicoClaw**

After building, run the binary:

```bash theme={null}
# 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:
>
> ```bash theme={null}
> make build-whatsapp-native
> ```
>
> Or manually:
>
> ```bash theme={null}
> go build -tags whatsapp_native ./cmd/picoclaw
> ```

> **Custom Build Flags**
>
> For custom compilation:
>
> ```bash theme={null}
> # 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:
>
> ```bash theme={null}
> # 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**

```bash theme={null}
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
```

**2. Initial Setup**

Run the first-time setup to generate the config file:

```bash theme={null}
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:

```bash theme={null}
vim docker/data/config.json
```

Add your API keys for LLM providers, bot tokens, etc. See the [Quickstart](https://sipeed-picoclaw-44.mintlify.site/quickstart.md#configure-api-keys) for details.

**4. Start the Gateway**

Start PicoClaw in detached mode:

```bash theme={null}
docker compose -f docker/docker-compose.yml --profile gateway up -d
```

> [!NOTE]
>
> **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:

```bash theme={null}
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
```

### Docker Agent Mode (One-shot)

For quick questions without running the gateway:

```bash One-shot Question theme={null}
# Ask a single question
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
```

```bash Interactive Mode theme={null}
# Enter interactive chat
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
```

### Managing Docker Deployment

```bash View Logs theme={null}
# Follow gateway logs
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
```

```bash Stop Services theme={null}
# Stop all containers
docker compose -f docker/docker-compose.yml --profile gateway down
```

```bash Update to Latest theme={null}
# Pull latest image and restart
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile gateway up -d
```

```bash Clean Up theme={null}
# Remove containers and volumes
docker compose -f docker/docker-compose.yml --profile gateway down -v
```

## 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](https://f-droid.org/packages/com.termux/) or Google Play.

> [!WARNING]
>
> 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:

```bash theme={null}
# 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:

```bash theme={null}
pkg install proot
```

**4. Initialize PicoClaw**

Run the onboarding process:

```bash theme={null}
termux-chroot ./picoclaw-linux-arm64 onboard
```

Follow the instructions to complete configuration.

**5. Start Using**

Run PicoClaw commands:

```bash theme={null}
termux-chroot ./picoclaw-linux-arm64 agent -m "Hello!"
```

> [!TIP]
>
> Now your old Android phone is a fully functional AI assistant! Proceed to the [Quick Start](https://sipeed-picoclaw-44.mintlify.site/quickstart.md) guide to configure it.

## Next Steps

> **[Quick Start](https://sipeed-picoclaw-44.mintlify.site/quickstart.md)**
>
> Configure PicoClaw and start chatting

> **[Configuration](https://sipeed-picoclaw-44.mintlify.site/configuration/overview.md)**
>
> Deep dive into configuration options


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.