@quantumclaw/quantumclaw 2026.3.22

package/docs/install/northflank.mdx

@@ -0,0 +1,54 @@
+---
+summary: "Deploy OpenClaw on Northflank with one-click template"
+read_when:
+  - Deploying OpenClaw to Northflank
+  - You want a one-click cloud deploy with browser-based setup
+title: "Northflank"
+---
+
+Deploy OpenClaw on Northflank with a one-click template and finish setup in your browser.
+This is the easiest “no terminal on the server” path: Northflank runs the Gateway for you,
+and you configure everything via the `/setup` web wizard.
+
+## How to get started
+
+1. Click [Deploy OpenClaw](https://northflank.com/stacks/deploy-openclaw) to open the template.
+2. Create an [account on Northflank](https://app.northflank.com/signup) if you don’t already have one.
+3. Click **Deploy OpenClaw now**.
+4. Set the required environment variable: `SETUP_PASSWORD`.
+5. Click **Deploy stack** to build and run the OpenClaw template.
+6. Wait for the deployment to complete, then click **View resources**.
+7. Open the OpenClaw service.
+8. Open the public OpenClaw URL and complete setup at `/setup`.
+9. Open the Control UI at `/openclaw`.
+
+## What you get
+
+- Hosted OpenClaw Gateway + Control UI
+- Web setup at `/setup` (no terminal commands)
+- Persistent storage via Northflank Volume (`/data`) so config/credentials/workspace survive redeploys
+
+## Setup flow
+
+1. Visit `https://<your-northflank-domain>/setup` and enter your `SETUP_PASSWORD`.
+2. Choose a model/auth provider and paste your key.
+3. (Optional) Add Telegram/Discord/Slack tokens.
+4. Click **Run setup**.
+5. Open the Control UI at `https://<your-northflank-domain>/openclaw`
+
+If Telegram DMs are set to pairing, web setup can approve the pairing code.
+
+## Connect a channel
+
+Paste your Telegram or Discord token into the `/setup` wizard. For setup
+instructions, see the channel docs:
+
+- [Telegram](/channels/telegram) (fastest — just a bot token)
+- [Discord](/channels/discord)
+- [All channels](/channels)
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)
+- Keep OpenClaw up to date: [Updating](/install/updating)

package/docs/install/oracle.md

@@ -0,0 +1,156 @@
+---
+summary: "Host QuantumClaw on Oracle Cloud's Always Free ARM tier"
+read_when:
+  - Setting up QuantumClaw on Oracle Cloud
+  - Looking for free VPS hosting for QuantumClaw
+  - Want 24/7 QuantumClaw on a small server
+title: "Oracle Cloud"
+---
+
+# Oracle Cloud
+
+Run a persistent QuantumClaw Gateway on Oracle Cloud's **Always Free** ARM tier (up to 4 OCPU, 24 GB RAM, 200 GB storage) at no cost.
+
+## Prerequisites
+
+- Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) -- see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues
+- Tailscale account (free at [tailscale.com](https://tailscale.com))
+- An SSH key pair
+- About 30 minutes
+
+## Setup
+
+<Steps>
+  <Step title="Create an OCI instance">
+    1. Log into [Oracle Cloud Console](https://cloud.oracle.com/).
+    2. Navigate to **Compute > Instances > Create Instance**.
+    3. Configure:
+       - **Name:** `quantumclaw`
+       - **Image:** Ubuntu 24.04 (aarch64)
+       - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
+       - **OCPUs:** 2 (or up to 4)
+       - **Memory:** 12 GB (or up to 24 GB)
+       - **Boot volume:** 50 GB (up to 200 GB free)
+       - **SSH key:** Add your public key
+    4. Click **Create** and note the public IP address.
+
+    <Tip>
+    If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited.
+    </Tip>
+
+  </Step>
+
+  <Step title="Connect and update the system">
+    ```bash
+    ssh ubuntu@YOUR_PUBLIC_IP
+
+    sudo apt update && sudo apt upgrade -y
+    sudo apt install -y build-essential
+    ```
+
+    `build-essential` is required for ARM compilation of some dependencies.
+
+  </Step>
+
+  <Step title="Configure user and hostname">
+    ```bash
+    sudo hostnamectl set-hostname quantumclaw
+    sudo passwd ubuntu
+    sudo loginctl enable-linger ubuntu
+    ```
+
+    Enabling linger keeps user services running after logout.
+
+  </Step>
+
+  <Step title="Install Tailscale">
+    ```bash
+    curl -fsSL https://tailscale.com/install.sh | sh
+    sudo tailscale up --ssh --hostname=quantumclaw
+    ```
+
+    From now on, connect via Tailscale: `ssh ubuntu@quantumclaw`.
+
+  </Step>
+
+  <Step title="Install QuantumClaw">
+    ```bash
+    curl -fsSL https://quantumclaw.ai/install.sh | bash
+    source ~/.bashrc
+    ```
+
+    When prompted "How do you want to hatch your bot?", select **Do this later**.
+
+  </Step>
+
+  <Step title="Configure the gateway">
+    Use token auth with Tailscale Serve for secure remote access.
+
+    ```bash
+    quantumclaw config set gateway.bind loopback
+    quantumclaw config set gateway.auth.mode token
+    quantumclaw doctor --generate-gateway-token
+    quantumclaw config set gateway.tailscale.mode serve
+    quantumclaw config set gateway.trustedProxies '["127.0.0.1"]'
+
+    systemctl --user restart quantumclaw-gateway
+    ```
+
+  </Step>
+
+  <Step title="Lock down VCN security">
+    Block all traffic except Tailscale at the network edge:
+
+    1. Go to **Networking > Virtual Cloud Networks** in the OCI Console.
+    2. Click your VCN, then **Security Lists > Default Security List**.
+    3. **Remove** all ingress rules except `0.0.0.0/0 UDP 41641` (Tailscale).
+    4. Keep default egress rules (allow all outbound).
+
+    This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. You can only connect via Tailscale from this point on.
+
+  </Step>
+
+  <Step title="Verify">
+    ```bash
+    quantumclaw --version
+    systemctl --user status quantumclaw-gateway
+    tailscale serve status
+    curl http://localhost:18789
+    ```
+
+    Access the Control UI from any device on your tailnet:
+
+    ```
+    https://quantumclaw.<tailnet-name>.ts.net/
+    ```
+
+    Replace `<tailnet-name>` with your tailnet name (visible in `tailscale status`).
+
+  </Step>
+</Steps>
+
+## Fallback: SSH tunnel
+
+If Tailscale Serve is not working, use an SSH tunnel from your local machine:
+
+```bash
+ssh -L 18789:127.0.0.1:18789 ubuntu@quantumclaw
+```
+
+Then open `http://localhost:18789`.
+
+## Troubleshooting
+
+**Instance creation fails ("Out of capacity")** -- Free tier ARM instances are popular. Try a different availability domain or retry during off-peak hours.
+
+**Tailscale will not connect** -- Run `sudo tailscale up --ssh --hostname=quantumclaw --reset` to re-authenticate.
+
+**Gateway will not start** -- Run `quantumclaw doctor --non-interactive` and check logs with `journalctl --user -u quantumclaw-gateway -n 50`.
+
+**ARM binary issues** -- Most npm packages work on ARM64. For native binaries, look for `linux-arm64` or `aarch64` releases. Verify architecture with `uname -m`.
+
+## Next steps
+
+- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more
+- [Gateway configuration](/gateway/configuration) -- all config options
+- [Updating](/install/updating) -- keep QuantumClaw up to date

package/docs/install/podman.md

@@ -0,0 +1,133 @@
+---
+summary: "Run QuantumClaw in a rootless Podman container"
+read_when:
+  - You want a containerized gateway with Podman instead of Docker
+title: "Podman"
+---
+
+# Podman
+
+Run the QuantumClaw Gateway in a **rootless** Podman container. Uses the same image as Docker (built from the repo [Dockerfile](https://github.com/quantumclaw/quantumclaw/blob/main/Dockerfile)).
+
+## Prerequisites
+
+- **Podman** (rootless mode)
+- **sudo** access for one-time setup (creating the dedicated user and building the image)
+
+## Quick start
+
+<Steps>
+  <Step title="One-time setup">
+    From the repo root, run the setup script. It creates a dedicated `quantumclaw` user, builds the container image, and installs the launch script:
+
+    ```bash
+    ./scripts/podman/setup.sh
+    ```
+
+    This also creates a minimal config at `~quantumclaw/.quantumclaw/quantumclaw.json` (sets `gateway.mode` to `"local"`) so the Gateway can start without running the wizard.
+
+    By default the container is **not** installed as a systemd service -- you start it manually in the next step. For a production-style setup with auto-start and restarts, pass `--quadlet` instead:
+
+    ```bash
+    ./scripts/podman/setup.sh --quadlet
+    ```
+
+    (Or set `QUANTUMCLAW_PODMAN_QUADLET=1`. Use `--container` to install only the container and launch script.)
+
+    **Optional build-time env vars** (set before running `scripts/podman/setup.sh`):
+
+    - `QUANTUMCLAW_DOCKER_APT_PACKAGES` -- install extra apt packages during image build.
+    - `QUANTUMCLAW_EXTENSIONS` -- pre-install extension dependencies (space-separated names, e.g. `diagnostics-otel matrix`).
+
+  </Step>
+
+  <Step title="Start the Gateway">
+    For a quick manual launch:
+
+    ```bash
+    ./scripts/run-quantumclaw-podman.sh launch
+    ```
+
+  </Step>
+
+  <Step title="Run the onboarding wizard">
+    To add channels or providers interactively:
+
+    ```bash
+    ./scripts/run-quantumclaw-podman.sh launch setup
+    ```
+
+    Then open `http://127.0.0.1:18789/` and use the token from `~quantumclaw/.quantumclaw/.env` (or the value printed by setup).
+
+  </Step>
+</Steps>
+
+## Systemd (Quadlet, optional)
+
+If you ran `./scripts/podman/setup.sh --quadlet` (or `QUANTUMCLAW_PODMAN_QUADLET=1`), a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit is installed so the gateway runs as a systemd user service for the quantumclaw user. The service is enabled and started at the end of setup.
+
+- **Start:** `sudo systemctl --machine quantumclaw@ --user start quantumclaw.service`
+- **Stop:** `sudo systemctl --machine quantumclaw@ --user stop quantumclaw.service`
+- **Status:** `sudo systemctl --machine quantumclaw@ --user status quantumclaw.service`
+- **Logs:** `sudo journalctl --machine quantumclaw@ --user -u quantumclaw.service -f`
+
+The quadlet file lives at `~quantumclaw/.config/containers/systemd/quantumclaw.container`. To change ports or env, edit that file (or the `.env` it sources), then `sudo systemctl --machine quantumclaw@ --user daemon-reload` and restart the service. On boot, the service starts automatically if lingering is enabled for quantumclaw (setup does this when loginctl is available).
+
+To add quadlet **after** an initial setup that did not use it, re-run: `./scripts/podman/setup.sh --quadlet`.
+
+## The quantumclaw user (non-login)
+
+`scripts/podman/setup.sh` creates a dedicated system user `quantumclaw`:
+
+- **Shell:** `nologin` — no interactive login; reduces attack surface.
+- **Home:** e.g. `/home/quantumclaw` — holds `~/.quantumclaw` (config, workspace) and the launch script `run-quantumclaw-podman.sh`.
+- **Rootless Podman:** The user must have a **subuid** and **subgid** range. Many distros assign these automatically when the user is created. If setup prints a warning, add lines to `/etc/subuid` and `/etc/subgid`:
+
+  ```text
+  quantumclaw:100000:65536
+  ```
+
+  Then start the gateway as that user (e.g. from cron or systemd):
+
+  ```bash
+  sudo -u quantumclaw /home/quantumclaw/run-quantumclaw-podman.sh
+  sudo -u quantumclaw /home/quantumclaw/run-quantumclaw-podman.sh setup
+  ```
+
+- **Config:** Only `quantumclaw` and root can access `/home/quantumclaw/.quantumclaw`. To edit config: use the Control UI once the gateway is running, or `sudo -u quantumclaw $EDITOR /home/quantumclaw/.quantumclaw/quantumclaw.json`.
+
+## Environment and config
+
+- **Token:** Stored in `~quantumclaw/.quantumclaw/.env` as `QUANTUMCLAW_GATEWAY_TOKEN`. `scripts/podman/setup.sh` and `run-quantumclaw-podman.sh` generate it if missing (uses `openssl`, `python3`, or `od`).
+- **Optional:** In that `.env` you can set provider keys (e.g. `GROQ_API_KEY`, `OLLAMA_API_KEY`) and other QuantumClaw env vars.
+- **Host ports:** By default the script maps `18789` (gateway) and `18790` (bridge). Override the **host** port mapping with `QUANTUMCLAW_PODMAN_GATEWAY_HOST_PORT` and `QUANTUMCLAW_PODMAN_BRIDGE_HOST_PORT` when launching.
+- **Gateway bind:** By default, `run-quantumclaw-podman.sh` starts the gateway with `--bind loopback` for safe local access. To expose on LAN, set `QUANTUMCLAW_GATEWAY_BIND=lan` and configure `gateway.controlUi.allowedOrigins` (or explicitly enable host-header fallback) in `quantumclaw.json`.
+- **Paths:** Host config and workspace default to `~quantumclaw/.quantumclaw` and `~quantumclaw/.quantumclaw/workspace`. Override the host paths used by the launch script with `QUANTUMCLAW_CONFIG_DIR` and `QUANTUMCLAW_WORKSPACE_DIR`.
+
+## Storage model
+
+- **Persistent host data:** `QUANTUMCLAW_CONFIG_DIR` and `QUANTUMCLAW_WORKSPACE_DIR` are bind-mounted into the container and retain state on the host.
+- **Ephemeral sandbox tmpfs:** if you enable `agents.defaults.sandbox`, the tool sandbox containers mount `tmpfs` at `/tmp`, `/var/tmp`, and `/run`. Those paths are memory-backed and disappear with the sandbox container; the top-level Podman container setup does not add its own tmpfs mounts.
+- **Disk growth hotspots:** the main paths to watch are `media/`, `agents/<agentId>/sessions/sessions.json`, transcript JSONL files, `cron/runs/*.jsonl`, and rolling file logs under `/tmp/quantumclaw/` (or your configured `logging.file`).
+
+`scripts/podman/setup.sh` now stages the image tar in a private temp directory and prints the chosen base dir during setup. For non-root runs it accepts `TMPDIR` only when that base is safe to use; otherwise it falls back to `/var/tmp`, then `/tmp`. The saved tar stays owner-only and is streamed into the target user’s `podman load`, so private caller temp dirs do not block setup.
+
+## Useful commands
+
+- **Logs:** With quadlet: `sudo journalctl --machine quantumclaw@ --user -u quantumclaw.service -f`. With script: `sudo -u quantumclaw podman logs -f quantumclaw`
+- **Stop:** With quadlet: `sudo systemctl --machine quantumclaw@ --user stop quantumclaw.service`. With script: `sudo -u quantumclaw podman stop quantumclaw`
+- **Start again:** With quadlet: `sudo systemctl --machine quantumclaw@ --user start quantumclaw.service`. With script: re-run the launch script or `podman start quantumclaw`
+- **Remove container:** `sudo -u quantumclaw podman rm -f quantumclaw` — config and workspace on the host are kept
+
+## Troubleshooting
+
+- **Permission denied (EACCES) on config or auth-profiles:** The container defaults to `--userns=keep-id` and runs as the same uid/gid as the host user running the script. Ensure your host `QUANTUMCLAW_CONFIG_DIR` and `QUANTUMCLAW_WORKSPACE_DIR` are owned by that user.
+- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~quantumclaw/.quantumclaw/quantumclaw.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this file if missing.
+- **Rootless Podman fails for user quantumclaw:** Check `/etc/subuid` and `/etc/subgid` contain a line for `quantumclaw` (e.g. `quantumclaw:100000:65536`). Add it if missing and restart.
+- **Container name in use:** The launch script uses `podman run --replace`, so the existing container is replaced when you start again. To clean up manually: `podman rm -f quantumclaw`.
+- **Script not found when running as quantumclaw:** Ensure `scripts/podman/setup.sh` was run so that `run-quantumclaw-podman.sh` is copied to quantumclaw’s home (e.g. `/home/quantumclaw/run-quantumclaw-podman.sh`).
+- **Quadlet service not found or fails to start:** Run `sudo systemctl --machine quantumclaw@ --user daemon-reload` after editing the `.container` file. Quadlet requires cgroups v2: `podman info --format '{{.Host.CgroupsVersion}}'` should show `2`.
+
+## Optional: run as your own user
+
+To run the gateway as your normal user (no dedicated quantumclaw user): build the image, create `~/.quantumclaw/.env` with `QUANTUMCLAW_GATEWAY_TOKEN`, and run the container with `--userns=keep-id` and mounts to your `~/.quantumclaw`. The launch script is designed for the quantumclaw-user flow; for a single-user setup you can instead run the `podman run` command from the script manually, pointing config and workspace to your home. Recommended for most users: use `scripts/podman/setup.sh` and run as the quantumclaw user so config and process are isolated.

package/docs/install/railway.mdx

@@ -0,0 +1,100 @@
+---
+summary: "Deploy OpenClaw on Railway with one-click template"
+read_when:
+  - Deploying OpenClaw to Railway
+  - You want a one-click cloud deploy with browser-based setup
+title: "Railway"
+---
+
+Deploy OpenClaw on Railway with a one-click template and finish setup in your browser.
+This is the easiest “no terminal on the server” path: Railway runs the Gateway for you,
+and you configure everything via the `/setup` web wizard.
+
+## Quick checklist (new users)
+
+1. Click **Deploy on Railway** (below).
+2. Add a **Volume** mounted at `/data`.
+3. Set the required **Variables** (at least `SETUP_PASSWORD`).
+4. Enable **HTTP Proxy** on port `8080`.
+5. Open `https://<your-railway-domain>/setup` and finish the wizard.
+
+## One-click deploy
+
+<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">
+  Deploy on Railway
+</a>
+
+After deploy, find your public URL in **Railway → your service → Settings → Domains**.
+
+Railway will either:
+
+- give you a generated domain (often `https://<something>.up.railway.app`), or
+- use your custom domain if you attached one.
+
+Then open:
+
+- `https://<your-railway-domain>/setup` — web setup (password protected)
+- `https://<your-railway-domain>/openclaw` — Control UI
+
+## What you get
+
+- Hosted OpenClaw Gateway + Control UI
+- Web setup at `/setup` (no terminal commands)
+- Persistent storage via Railway Volume (`/data`) so config/credentials/workspace survive redeploys
+- Backup export at `/setup/export` to migrate off Railway later
+
+## Required Railway settings
+
+### Public Networking
+
+Enable **HTTP Proxy** for the service.
+
+- Port: `8080`
+
+### Volume (required)
+
+Attach a volume mounted at:
+
+- `/data`
+
+### Variables
+
+Set these variables on the service:
+
+- `SETUP_PASSWORD` (required)
+- `PORT=8080` (required — must match the port in Public Networking)
+- `OPENCLAW_STATE_DIR=/data/.openclaw` (recommended)
+- `OPENCLAW_WORKSPACE_DIR=/data/workspace` (recommended)
+- `OPENCLAW_GATEWAY_TOKEN` (recommended; treat as an admin secret)
+
+## Setup flow
+
+1. Visit `https://<your-railway-domain>/setup` and enter your `SETUP_PASSWORD`.
+2. Choose a model/auth provider and paste your key.
+3. (Optional) Add Telegram/Discord/Slack tokens.
+4. Click **Run setup**.
+
+If Telegram DMs are set to pairing, web setup can approve the pairing code.
+
+## Connect a channel
+
+Paste your Telegram or Discord token into the `/setup` wizard. For setup
+instructions, see the channel docs:
+
+- [Telegram](/channels/telegram) (fastest — just a bot token)
+- [Discord](/channels/discord)
+- [All channels](/channels)
+
+## Backups & migration
+
+Download a backup at:
+
+- `https://<your-railway-domain>/setup/export`
+
+This exports your OpenClaw state + workspace so you can migrate to another host without losing config or memory.
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)
+- Keep OpenClaw up to date: [Updating](/install/updating)

package/docs/install/raspberry-pi.md

@@ -0,0 +1,159 @@
+---
+summary: "Host QuantumClaw on a Raspberry Pi for always-on self-hosting"
+read_when:
+  - Setting up QuantumClaw on a Raspberry Pi
+  - Running QuantumClaw on ARM devices
+  - Building a cheap always-on personal AI
+title: "Raspberry Pi"
+---
+
+# Raspberry Pi
+
+Run a persistent, always-on QuantumClaw 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
+
+<Steps>
+  <Step title="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.
+
+  </Step>
+
+  <Step title="Connect via SSH">
+    ```bash
+    ssh user@gateway-host
+    ```
+  </Step>
+
+  <Step title="Update the system">
+    ```bash
+    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
+    ```
+
+  </Step>
+
+  <Step title="Install Node.js 24">
+    ```bash
+    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+    sudo apt install -y nodejs
+    node --version
+    ```
+  </Step>
+
+  <Step title="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
+    ```
+
+  </Step>
+
+  <Step title="Install QuantumClaw">
+    ```bash
+    curl -fsSL https://quantumclaw.ai/install.sh | bash
+    ```
+  </Step>
+
+  <Step title="Run onboarding">
+    ```bash
+    quantumclaw onboard --install-daemon
+    ```
+
+    Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with.
+
+  </Step>
+
+  <Step title="Verify">
+    ```bash
+    quantumclaw status
+    sudo systemctl status quantumclaw
+    journalctl -u quantumclaw -f
+    ```
+  </Step>
+
+  <Step title="Access the Control UI">
+    On your computer, get a dashboard URL from the Pi:
+
+    ```bash
+    ssh user@gateway-host 'quantumclaw 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).
+
+  </Step>
+</Steps>
+
+## 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
+grep -q 'NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
+export NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache
+mkdir -p /var/tmp/quantumclaw-compile-cache
+export QUANTUMCLAW_NO_RESPAWN=1
+EOF
+source ~/.bashrc
+```
+
+**Reduce memory usage** -- For headless setups, free GPU memory and disable unused services:
+
+```bash
+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 quantumclaw --no-pager -n 100` and run `quantumclaw 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](/channels) -- connect Telegram, WhatsApp, Discord, and more
+- [Gateway configuration](/gateway/configuration) -- all config options
+- [Updating](/install/updating) -- keep QuantumClaw up to date