Raspberry Pi

Run a persistent, always-on Velaclaw Gateway on a Raspberry Pi. Since the Pi is just the gateway (models run in the cloud via API), even a modest Pi handles the workload well.

Prerequisites

Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended)
MicroSD card (16 GB+) or USB SSD (better performance)
Official Pi power supply
Network connection (Ethernet or WiFi)
64-bit Raspberry Pi OS (required — do not use 32-bit)
About 30 minutes

Setup

Flash the OS

Use Raspberry Pi OS Lite (64-bit) — no desktop needed for a headless server.

Download Raspberry Pi Imager.
Choose OS: Raspberry Pi OS Lite (64-bit).
In the settings dialog, pre-configure:
- Hostname: gateway-host
- Enable SSH
- Set username and password
- Configure WiFi (if not using Ethernet)
Flash to your SD card or USB drive, insert it, and boot the Pi.

Connect via SSH

ssh user@gateway-host

Update the system

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential

# Set timezone (important for cron and reminders)
sudo timedatectl set-timezone America/Chicago

Install Node.js 24

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version

Add swap (important for 2 GB or less)

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Reduce swappiness for low-RAM devices
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Install Velaclaw

curl -fsSL https://velaclaw.ai/install.sh | bash

Run onboarding

velaclaw onboard --install-daemon

Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with.

Verify

velaclaw status
systemctl --user status velaclaw-gateway.service
journalctl --user -u velaclaw-gateway.service -f

Access the Control UI

On your computer, get a dashboard URL from the Pi:

ssh user@gateway-host 'velaclaw dashboard --no-open'

Then create an SSH tunnel in another terminal:

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Open the printed URL in your local browser. For always-on remote access, see Tailscale integration.

Performance tips

Use a USB SSD — SD cards are slow and wear out. A USB SSD dramatically improves performance. See the Pi USB boot guide. Enable module compile cache — Speeds up repeated CLI invocations on lower-power Pi hosts:

grep -q 'NODE_COMPILE_CACHE=/var/tmp/velaclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
export NODE_COMPILE_CACHE=/var/tmp/velaclaw-compile-cache
mkdir -p /var/tmp/velaclaw-compile-cache
export VELACLAW_NO_RESPAWN=1
EOF
source ~/.bashrc

Reduce memory usage — For headless setups, free GPU memory and disable unused services:

echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
sudo systemctl disable bluetooth

Troubleshooting

Out of memory — Verify swap is active with free -h. Disable unused services (sudo systemctl disable cups bluetooth avahi-daemon). Use API-based models only. Slow performance — Use a USB SSD instead of an SD card. Check for CPU throttling with vcgencmd get_throttled (should return 0x0). Service will not start — Check logs with journalctl --user -u velaclaw-gateway.service --no-pager -n 100 and run velaclaw doctor --non-interactive. If this is a headless Pi, also verify lingering is enabled: sudo loginctl enable-linger "$(whoami)". ARM binary issues — If a skill fails with “exec format error”, check whether the binary has an ARM64 build. Verify architecture with uname -m (should show aarch64). WiFi drops — Disable WiFi power management: sudo iwconfig wlan0 power off.

Next steps

Channels — connect Telegram, WhatsApp, Discord, and more
Gateway configuration — all config options
Updating — keep Velaclaw up to date

Install overview

Containers

Hosting

Maintenance

Raspberry Pi

Raspberry Pi

Prerequisites

Setup

Performance tips

Troubleshooting

Next steps

​Raspberry Pi

​Prerequisites

​Setup

​Performance tips

​Troubleshooting

​Next steps

Raspberry Pi

Prerequisites

Setup

Performance tips

Troubleshooting

Next steps