🍓 Raspberry Pi Setup

Deploy SeaClip spoke on Raspberry Pi devices

Supported Models

Model RAM Recommended For
Raspberry Pi 5 4-8 GB ✅ Full spoke + small LLMs
Raspberry Pi 4 4-8 GB ✅ Full spoke functionality
Raspberry Pi 4 2 GB ⚠️ Spoke only (no local LLM)
Raspberry Pi 3B+ 1 GB ⚠️ Limited (telemetry only)
Raspberry Pi Zero 2 W 512 MB ⚠️ Telemetry only

Prerequisites

Operating System

64-bit Required: SeaClip requires a 64-bit OS for Node.js 20 compatibility.

Flash the OS

  1. Download Raspberry Pi Imager
  2. Select "Raspberry Pi OS (64-bit)"
  3. Click the gear icon to configure:
    • Set hostname (e.g., pi-spoke-01)
    • Enable SSH
    • Set username/password
    • Configure WiFi (if needed)
  4. Flash to SD card

One-Line Install

SSH into your Pi and run:

bash 
curl -sSL https://raw.githubusercontent.com/t4tarzan/seaclip/main/scripts/spoke-install.sh | bash -s -- --hub http://YOUR_HUB_IP:51842

Replace YOUR_HUB_IP with your hub server's IP address.

Manual Installation

Step 1: Update System

bash 
sudo apt update && sudo apt upgrade -y

Step 2: Install Node.js 20

bash 
# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify
node -v  # Should show v20.x.x

Step 3: Install pnpm

bash 
sudo npm install -g pnpm

Step 4: Clone and Install

bash 
sudo mkdir -p /opt/seaclip-spoke
sudo chown $USER:$USER /opt/seaclip-spoke

git clone --depth 1 https://github.com/t4tarzan/seaclip.git /opt/seaclip-spoke
cd /opt/seaclip-spoke

pnpm install --filter @seaclip/spoke --filter @seaclip/shared

Step 5: Configure

bash 
cat > /opt/seaclip-spoke/.env << EOF
SEACLIP_HUB_URL=http://YOUR_HUB_IP:51842
SEACLIP_DEVICE_NAME=$(hostname)
SEACLIP_DEVICE_TYPE=raspberry-pi
SEACLIP_TELEMETRY_INTERVAL=30
EOF

Step 6: Register with Hub

bash 
cd /opt/seaclip-spoke
pnpm spoke register

Step 7: Set Up Systemd Service

bash 
sudo tee /etc/systemd/system/seaclip-spoke.service > /dev/null << 'EOF'
[Unit]
Description=SeaClip Spoke Agent
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/opt/seaclip-spoke
ExecStart=/usr/bin/node /opt/seaclip-spoke/spoke/dist/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
EnvironmentFile=/opt/seaclip-spoke/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable seaclip-spoke
sudo systemctl start seaclip-spoke

Optional: Install Ollama

Run local LLMs on Pi 4/5 with 4GB+ RAM:

bash 
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a small model
ollama pull tinyllama
# or
ollama pull phi

# Test
ollama run tinyllama "Hello, world!"
Performance Note: LLM inference on Raspberry Pi is slow. Use small models (tinyllama, phi) and expect 1-5 tokens/second.

Telemetry Data

The spoke reports these metrics to the hub:

Metric Source
CPU Usage /proc/stat
Memory Usage /proc/meminfo
CPU Temperature /sys/class/thermal/thermal_zone0/temp
Disk Usage df
Network Stats /proc/net/dev
Uptime /proc/uptime

Verify Installation

bash 
# Check service status
sudo systemctl status seaclip-spoke

# View logs
sudo journalctl -u seaclip-spoke -f

# Test hub connection
curl http://YOUR_HUB_IP:51842/api/health

# Check device appears on hub
curl http://YOUR_HUB_IP:51842/api/devices | jq

Troubleshooting

Node.js won't install

Ensure you're using 64-bit Raspberry Pi OS. Check with:

bash 
uname -m  # Should show aarch64, not armv7l

High CPU temperature

Add a heatsink or fan. Reduce telemetry frequency:

bash 
echo "SEACLIP_TELEMETRY_INTERVAL=60" >> /opt/seaclip-spoke/.env
sudo systemctl restart seaclip-spoke

Out of memory

Increase swap space:

bash 
sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile
sudo dphys-swapfile setup
sudo dphys-swapfile swapon