Run a persistent, always-on Apus 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 -- typical hardware cost is $35-80 one-time, no monthly fees.

Hardware compatibility

Pi model RAM Works? Notes
Pi 5 4/8 GB Best Fastest, recommended.
Pi 4 4 GB Good Sweet spot for most users.
Pi 4 2 GB OK Add swap.
Pi 4 1 GB Tight Possible with swap, minimal config.
Pi 3B+ 1 GB Slow Works but sluggish.
Pi Zero 2 W 512 MB No Not recommended.

Minimum: 1 GB RAM, 1 core, 500 MB free disk, 64-bit OS. Recommended: 2 GB+ RAM, 16 GB+ SD card (or USB SSD), Ethernet.

Prerequisites

Setup

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.

Connect via SSH

```bash
ssh user@gateway-host
```

Update the system

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

# Set your timezone (important for cron and reminders).
# Replace America/Chicago with your own IANA zone (`timedatectl list-timezones`).
sudo timedatectl set-timezone America/Chicago
```

Install Node.js 24 LTS

```bash
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)

```bash
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 Apus

```bash
curl -fsSL https://ami-docs.dev.apuscorp.com/install.sh | bash -s -- --no-onboard
```

Run onboarding

```bash
apus onboard --install-daemon
```

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

Verify

```bash
apus status
systemctl --user status apus-gateway.service
journalctl --user -u apus-gateway.service -f
```

Access the Control UI

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

```bash
ssh user@gateway-host 'apus dashboard --no-open'
```

Then create an SSH tunnel in another terminal:

```bash
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](/gateway/tailscale).

Performance tips

Use a USB SSD -- SD cards are slow and wear out. A USB SSD dramatically improves performance and survives more write cycles; use it for APUS_STATE_DIR if you keep the OS on SD. See the Pi USB boot guide.

Enable module compile cache -- Speeds up repeated CLI invocations on lower-power Pi hosts. APUS_NO_RESPAWN=1 keeps routine Gateway restarts in-process, avoiding extra process handoffs and keeping PID tracking simple on small hosts:

grep -q 'NODE_COMPILE_CACHE=/var/tmp/apus-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/apus-compile-cache
mkdir -p /var/tmp/apus-compile-cache
export APUS_NO_RESPAWN=1
EOF
source ~/.bashrc

Use /var/tmp, not /tmp -- some distros clear /tmp on boot, which drops the warmed cache.

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

systemd drop-in for host-specific startup tuning -- The managed unit owns the generic restart policy (Restart=always, RestartSec=5). If this Pi is mostly running Apus, add a service drop-in for host-specific startup settings only:

systemctl --user edit apus-gateway.service

[Service]
Environment=APUS_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/apus-compile-cache
TimeoutStartSec=90

Then systemctl --user daemon-reload && systemctl --user restart apus-gateway.service. On a headless Pi, also enable lingering once so the user service survives logout: sudo loginctl enable-linger "$(whoami)".

Recommended model setup

Since the Pi only runs the gateway, use cloud-hosted API models -- do not run local LLMs on a Pi, even small models are too slow to be useful:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["openai/gpt-5.4-mini"]
      }
    }
  }
}

ARM binary notes

Most Apus features work on ARM64 without changes (Node.js, Telegram, WhatsApp/Baileys, Chromium). The binaries that occasionally lack ARM builds are typically optional Go/Rust CLI tools shipped by skills. Verify architecture with uname -m (should show aarch64), then check a missing binary's release page for linux-arm64 / aarch64 artifacts before falling back to building from source.

Persistence and backups

Apus state lives under:

These survive reboots and benefit from SSD over SD card for both performance and longevity. Create a backup archive with:

apus backup create
apus backup restore <archive.tar.gz> --target <fresh-directory>

Absolute symbolic links keep their original target locations, including links to separately backed-up config or credentials. Review these links before activating state on another host or at another path; see the backup symbolic-link caveat. Restore verifies and extracts into a fresh staging directory; activation is a separate offline step. See Restore a full archive for the rollback warnings and activation sequence.

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 apus-gateway.service --no-pager -n 100 and run apus 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

Related