mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
docs: Add mintlify docs (#2189)
This commit is contained in:
Guille
328
docs/drafts/platforms/raspberry-pi.mdx
Normal file
328
docs/drafts/platforms/raspberry-pi.mdx
Normal file
@@ -0,0 +1,328 @@
|
||||
---
|
||||
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>
|
||||
Reference in New Issue
Block a user