mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-02 23:56:24 +08:00
329 lines
7.4 KiB
Plaintext
329 lines
7.4 KiB
Plaintext
---
|
|
title: Raspberry Pi
|
|
sidebarTitle: Raspberry Pi
|
|
description: Running IronClaw on Raspberry Pi with ARM64 and local inference
|
|
---
|
|
|
|
IronClaw runs well on Raspberry Pi 4 and Pi 5 with a 64-bit OS. Pair it with Ollama for fully local inference — no cloud dependency, no API keys required.
|
|
|
|
<Note>
|
|
Raspberry Pi 4 (4 GB RAM) and Pi 5 (4/8 GB) are the recommended hardware. Pi 3 and earlier models lack sufficient memory for comfortable operation. A 64-bit OS (Raspberry Pi OS 64-bit or Ubuntu 22.04 ARM64) is required.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Hardware Requirements
|
|
|
|
| Component | Minimum | Recommended |
|
|
|-----------|---------|-------------|
|
|
| Model | Raspberry Pi 4 (4 GB) | Raspberry Pi 5 (8 GB) |
|
|
| OS | Raspberry Pi OS 64-bit | Ubuntu 22.04 LTS ARM64 |
|
|
| Storage | 16 GB microSD | 32 GB+ microSD or USB SSD |
|
|
| RAM | 4 GB | 8 GB |
|
|
| Swap | 2 GB | 4 GB |
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Shell Script
|
|
|
|
```bash
|
|
curl -fsSL https://install.ironclaw.ai | bash
|
|
```
|
|
|
|
This downloads the ARM64 binary automatically. Add to PATH:
|
|
|
|
```bash
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
### Verify the Architecture
|
|
|
|
```bash
|
|
uname -m # Should print: aarch64
|
|
ironclaw --version
|
|
```
|
|
|
|
---
|
|
|
|
## Recommended Configuration
|
|
|
|
The libSQL backend is strongly recommended for Raspberry Pi — it requires no separate database server and runs embedded in the IronClaw process.
|
|
|
|
Create `~/.ironclaw/.env`:
|
|
|
|
```bash
|
|
# Database: embedded SQLite (no server needed)
|
|
DATABASE_BACKEND=libsql
|
|
LIBSQL_PATH=~/.ironclaw/ironclaw.db
|
|
|
|
# LLM: local Ollama inference
|
|
LLM_BACKEND=ollama
|
|
OLLAMA_BASE_URL=http://127.0.0.1:11434
|
|
OLLAMA_MODEL=llama3.2:3b
|
|
|
|
# Web Gateway
|
|
GATEWAY_ENABLED=true
|
|
GATEWAY_HOST=127.0.0.1
|
|
GATEWAY_PORT=3000
|
|
GATEWAY_AUTH_TOKEN=change_this_to_a_random_secret
|
|
|
|
# Embeddings: disable if RAM-constrained
|
|
EMBEDDING_ENABLED=false
|
|
|
|
# Docker sandbox: optional, disable to save resources
|
|
SANDBOX_ENABLED=false
|
|
|
|
# Routines
|
|
ROUTINES_ENABLED=true
|
|
```
|
|
|
|
---
|
|
|
|
## Ollama for Local Inference
|
|
|
|
Ollama runs language models entirely on the Pi. No data leaves the device.
|
|
|
|
### Install Ollama
|
|
|
|
```bash
|
|
curl -fsSL https://ollama.ai/install.sh | sh
|
|
```
|
|
|
|
### Pull a Model
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="4 GB RAM (Pi 4 / Pi 5 4 GB)" icon="cpu">
|
|
Use a 3B parameter model that fits comfortably:
|
|
|
|
```bash
|
|
ollama pull llama3.2:3b
|
|
```
|
|
|
|
This model uses ~2 GB RAM and leaves headroom for the OS and IronClaw.
|
|
</Accordion>
|
|
|
|
<Accordion title="8 GB RAM (Pi 5 8 GB)" icon="cpu">
|
|
You can run a larger model with better quality:
|
|
|
|
```bash
|
|
# 7B quantized — good quality, fits in 8 GB
|
|
ollama pull llama3.1:8b-instruct-q4_K_M
|
|
|
|
# Or Mistral 7B
|
|
ollama pull mistral:7b-instruct-q4_K_M
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
### Verify Ollama is Running
|
|
|
|
```bash
|
|
# Start Ollama service
|
|
sudo systemctl enable --now ollama
|
|
|
|
# Test a completion
|
|
curl http://127.0.0.1:11434/api/chat -d '{
|
|
"model": "llama3.2:3b",
|
|
"messages": [{"role": "user", "content": "Hello"}],
|
|
"stream": false
|
|
}'
|
|
```
|
|
|
|
### IronClaw Configuration for Ollama
|
|
|
|
```bash
|
|
LLM_BACKEND=ollama
|
|
OLLAMA_BASE_URL=http://127.0.0.1:11434
|
|
OLLAMA_MODEL=llama3.2:3b
|
|
```
|
|
|
|
---
|
|
|
|
## Memory and Swap
|
|
|
|
The Pi's limited RAM makes swap configuration important.
|
|
|
|
### Check Current Swap
|
|
|
|
```bash
|
|
free -h
|
|
swapon --show
|
|
```
|
|
|
|
### Increase Swap to 2 GB
|
|
|
|
```bash
|
|
# Disable current swap
|
|
sudo dphys-swapfile swapoff
|
|
|
|
# Edit swap config
|
|
sudo nano /etc/dphys-swapfile
|
|
# Set: CONF_SWAPSIZE=2048
|
|
|
|
# Re-enable
|
|
sudo dphys-swapfile setup
|
|
sudo dphys-swapfile swapon
|
|
|
|
# Verify
|
|
free -h
|
|
```
|
|
|
|
### Use a USB SSD for Swap (Better Performance)
|
|
|
|
If you have a USB SSD attached:
|
|
|
|
```bash
|
|
sudo mkswap /dev/sda1
|
|
sudo swapon /dev/sda1
|
|
|
|
# Make permanent
|
|
echo '/dev/sda1 none swap sw 0 0' | sudo tee -a /etc/fstab
|
|
```
|
|
|
|
<Warning>
|
|
Avoid heavy swap usage on microSD cards — the write cycles degrade cards quickly. If you rely on swap, route it to a USB SSD.
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## systemd Service
|
|
|
|
Run IronClaw as a background service on the Pi.
|
|
|
|
Create `/etc/systemd/system/ironclaw.service`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=IronClaw AI Assistant
|
|
After=network-online.target ollama.service
|
|
Wants=network-online.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=pi
|
|
EnvironmentFile=/home/pi/.ironclaw/.env
|
|
ExecStart=/home/pi/.local/bin/ironclaw run
|
|
Restart=on-failure
|
|
RestartSec=10s
|
|
StandardOutput=journal
|
|
StandardError=journal
|
|
SyslogIdentifier=ironclaw
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
Enable and start:
|
|
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now ironclaw
|
|
journalctl -u ironclaw -f
|
|
```
|
|
|
|
---
|
|
|
|
## Docker Sandbox (Optional)
|
|
|
|
Docker works on Raspberry Pi but is resource-intensive. For a Pi with 4 GB RAM, disable the sandbox unless you specifically need job isolation.
|
|
|
|
### Install Docker on Pi
|
|
|
|
```bash
|
|
curl -fsSL https://get.docker.com | sh
|
|
sudo usermod -aG docker $USER
|
|
newgrp docker
|
|
```
|
|
|
|
### Sandbox Configuration
|
|
|
|
```bash
|
|
# Enable sandbox (requires Docker)
|
|
SANDBOX_ENABLED=true
|
|
SANDBOX_IMAGE=ironclaw-worker:latest
|
|
SANDBOX_MEMORY_LIMIT_MB=256 # Keep low on Pi
|
|
SANDBOX_TIMEOUT_SECS=300
|
|
```
|
|
|
|
<Note>
|
|
On a 4 GB Pi, each sandbox container takes ~200-300 MB RAM. With Ollama also running, a single concurrent job is the practical limit. On an 8 GB Pi 5, you can run 2-3 concurrent sandbox jobs.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Performance Tips
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Disable embeddings if RAM-constrained" icon="database">
|
|
Semantic memory search uses an embedding model that requires additional RAM and an embedding API call. If you are not using the memory search features, disable it:
|
|
|
|
```bash
|
|
EMBEDDING_ENABLED=false
|
|
```
|
|
|
|
Full-text search (FTS5) still works without embeddings.
|
|
</Accordion>
|
|
|
|
<Accordion title="Use a microSD A2 card or USB SSD" icon="hard-drive">
|
|
Database I/O on a slow microSD card significantly affects response times. An A2-rated microSD or USB SSD reduces latency for libSQL writes.
|
|
</Accordion>
|
|
|
|
<Accordion title="Disable the heartbeat if idle periods are long" icon="activity">
|
|
The heartbeat runs every 30 minutes by default and triggers an LLM call. On Ollama with a 3B model, this can take 10-30 seconds and consumes RAM. Adjust the interval or disable:
|
|
|
|
```bash
|
|
HEARTBEAT_ENABLED=false
|
|
# Or slow it down
|
|
HEARTBEAT_INTERVAL_SECS=7200 # 2 hours
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Reduce max parallel jobs" icon="layers">
|
|
Lower the concurrency limit to avoid memory pressure:
|
|
|
|
```bash
|
|
MAX_PARALLEL_JOBS=1
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Use quantized models" icon="cpu">
|
|
Quantized models (Q4_K_M) use 30-50% less RAM than full-precision models with only modest quality loss. Always prefer quantized variants on Pi hardware.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
---
|
|
|
|
## Accessing IronClaw from Your Network
|
|
|
|
By default IronClaw binds to `127.0.0.1`. To access it from another device on your LAN:
|
|
|
|
```bash
|
|
GATEWAY_HOST=0.0.0.0
|
|
GATEWAY_PORT=3000
|
|
```
|
|
|
|
Then navigate to `http://<pi-ip-address>:3000` from another machine. Secure with a strong `GATEWAY_AUTH_TOKEN`.
|
|
|
|
<Warning>
|
|
Do not expose port 3000 directly to the internet. If you need remote access, use a VPN (WireGuard, Tailscale) or SSH tunnel instead.
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={3}>
|
|
<Card title="Ollama Provider" icon="cpu" href="/providers/ollama">
|
|
Full configuration reference for the Ollama LLM provider
|
|
</Card>
|
|
<Card title="Linux Platform" icon="terminal" href="/platforms/linux">
|
|
systemd, GNOME Keyring, and UFW hardening for Linux
|
|
</Card>
|
|
<Card title="Configuration" icon="settings" href="/setup/configuration">
|
|
Full environment variable reference
|
|
</Card>
|
|
</CardGroup>
|