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

# Raspberry Pi

# Raspberry Pi

Run a persistent, always-on Agdi 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

**1. Flash the OS**

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

1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/).
2. Choose OS: **Raspberry Pi OS Lite (64-bit)**.
3. In the settings dialog, pre-configure:
   * Hostname: `gateway-host`
   * Enable SSH
   * Set username and password
   * Configure WiFi (if not using Ethernet)
4. Flash to your SD card or USB drive, insert it, and boot the Pi.

**2. Connect via SSH**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ssh user@gateway-host
```

**3. Update the system**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

**4. Install Node.js 24**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version
```

**5. Add swap (important for 2 GB or less)**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

**6. Install Agdi**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL https://agdi.ai/install.sh | bash
```

**7. Run onboarding**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi onboard --install-daemon
```

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

**8. Verify**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi status
sudo systemctl status agdi
journalctl -u agdi -f
```

**9. Access the Control UI**

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ssh user@gateway-host 'agdi dashboard --no-open'
```

Then create an SSH tunnel in another terminal:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](https://agdiai-597e782f.mintlify.site/gateway/tailscale.md).

## 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](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot).

**Enable module compile cache** -- Speeds up repeated CLI invocations on lower-power Pi hosts:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
grep -q 'NODE_COMPILE_CACHE=/var/tmp/agdi-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
export NODE_COMPILE_CACHE=/var/tmp/agdi-compile-cache
mkdir -p /var/tmp/agdi-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 -u agdi --no-pager -n 100` and run `agdi doctor --non-interactive`.

**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](https://agdiai-597e782f.mintlify.site/channels.md) -- connect Telegram, WhatsApp, Discord, and more
* [Gateway configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md) -- all config options
* [Updating](https://agdiai-597e782f.mintlify.site/install/updating.md) -- keep Agdi up to date


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