Skip to content
The Gateway

Installation

The Gateway ships as a single static binary plus an installer script. The installer is profile-driven: it knows the difference between a Raspberry Pi running an embedded WiFi AP and a remote VPS acting as a federation peer.

System requirements

Section titled “System requirements”
Component Minimum Notes
OS Debian 12+ or Ubuntu 22.04+ apt-based distributions only
Kernel Linux 5.15+ In-kernel WireGuard and nftables required
Architecture amd64 or arm64 No 32-bit support
RAM 1 GB (node) / 2 GB (Pi) More for high-throughput splitting
Storage 2 GB free SQLite + logs + TLS state in /var/lib/gateway/
NICs 1 (VPS) / 2 (Pi embedded) WAN + LAN for embedded mode
Privilege root Required for nftables, ip rule, systemd unit installation

Install profiles

Section titled “Install profiles”

The installer accepts a --profile flag that controls which packages and subsystems get provisioned.

Profile Use it for Includes
rpi Raspberry Pi 4 home gateway WiFi AP (hostapd + dnsmasq), Tailscale, redsocks, SD hardening, build deps
vps Remote Linux VPS Mesh, redsocks, no WiFi, no SD tweaks
node Federation peer / minimal node Bare gatewayd + base packages only
full Maximal install Everything above + Gitea + Ollama + Go toolchain
custom Operator-defined component set Interactive prompts for each subsystem

Quick install

Section titled “Quick install”
Terminal window
git clone https://example.invalid/gateway.git
cd gateway
sudo ./scripts/install-gateway.sh --profile rpi

The rpi profile additionally:

  • installs hostapd and dnsmasq for the integrated WiFi AP

  • enables the wlan0 regulatory domain

  • tunes SD card mount options (noatime, log to tmpfs)

  • pins CPU governor to ondemand

  • pre-pulls the ARM64 build chain for in-place rebuilds

Terminal window
curl -fsSL https://thegateway.pro/install.sh | sudo bash

The bootstrap honours these environment variables:

Variable Default Effect
GATEWAY_PROFILE vps Install profile (see table above)
GATEWAY_VERSION latest Pin a specific release tag
GATEWAY_FROM_SOURCE 0 Set to 1 to compile from source
GATEWAY_BASE_URL CDN Override download mirror
GATEWAY_UPDATE 0 Set to 1 to upgrade an existing installation

What the installer does

Section titled “What the installer does”

  1. Installs OS packages for the selected profile: nftables, wireguard-tools, iproute2, redsocks, unbound-anchor, optionally hostapd, dnsmasq, tailscale, headscale.

  2. Creates the runtime layout:

    /usr/local/bin/gatewayd            ← daemon binary
    /usr/local/bin/gwctl               ← CLI tool
    /etc/gateway/tls/{ca,server}.crt   ← internal CA + server cert (ECDSA P-256)
    /etc/gateway/tls/{ca,server}.key
    /var/lib/gateway/config.yaml       ← bootstrap config (YAML)
    /var/lib/gateway/gateway.db        ← SQLite store
    /etc/systemd/system/gatewayd.service

  3. Generates a self-signed internal CA and a server certificate so the API listens over TLS from the first boot.

  4. Writes the bootstrap config based on profile defaults. You can edit it before enabling the service.

  5. Enables the systemd unit but does not auto-start it — review the config first.

Network modes

Section titled “Network modes”

Choose a network.mode in your bootstrap config:

Mode NICs Use it for
primary Manages WAN + LAN, runs DHCP Dedicated home or office gateway
embedded Sits inline between router + LAN Adding The Gateway to an existing home network without replacing the ISP router
portable Single NIC Travel router, laptop, ad-hoc deployments

Start the daemon

Section titled “Start the daemon”
Terminal window
sudo systemctl enable gatewayd
sudo systemctl start gatewayd
systemctl status gatewayd
journalctl -u gatewayd -f

Health check:

Terminal window
curl -k https://127.0.0.1:8080/health
# → {"status":"ok"}

Open the web UI

Section titled “Open the web UI”
https://<gateway-ip>:8080

The first hit lands on the setup wizard, which creates the admin account and walks you through:

  1. Admin username + password (stored as bcrypt hash)
  2. Network mode confirmation (primary / embedded / portable)
  3. WiFi AP SSID + WPA2 passphrase (Pi only)
  4. First WireGuard tunnel (paste or generate)
  5. Default privacy class

After setup the wizard hands you off to the dashboard.

Updating

Section titled “Updating”
Terminal window
GATEWAY_UPDATE=1 curl -fsSL https://thegateway.pro/install.sh | sudo bash

The update procedure:

  1. Sends SIGTERM to gatewayd and waits for a clean SQLite WAL flush (never SIGKILL).
  2. Snapshots the old binary to /usr/local/bin/gatewayd.bak.<timestamp>.
  3. Installs the new binary.
  4. Starts the daemon and waits up to 4 seconds for /health to return ok.
  5. Rolls back to the snapshot if the health check fails.

Uninstall

Section titled “Uninstall”
Terminal window
sudo systemctl stop gatewayd
sudo systemctl disable gatewayd
sudo rm /etc/systemd/system/gatewayd.service
sudo rm -rf /etc/gateway /var/lib/gateway /usr/local/bin/gatewayd /usr/local/bin/gwctl
sudo nft delete table inet gateway   # remove the firewall table

Next steps

Section titled “Next steps”

The daemon is up. In order of what most operators do first:

  1. Run the quick start. Add one tunnel, one policy, one device, and verify the kill-switch works. 10 minutes.
  2. Set the secrets passphrase. The daemon auto-generated one on first boot — override it with one you control and store a copy off-box.
  3. Pick a posture. Skim the threat model so the next decisions you make match the protections you actually need.
  4. Take a baseline backup. gwctl backup export > /var/backups/gateway-init.json — sanitized plaintext, useful when comparing against future state. For the encrypted-with-secrets variant see Backup.
Section titled “Related”
  • Configuration — what each section of config.yaml controls.
  • Sizing & performance — capacity expectations for the hardware you just installed on.
  • FAQ — common pre-install questions.