Skip to content

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.

The current application release is v2.19.0. It embeds release-signing keys for server management, the shared release cache and built-in self-update checks. Server management is admin-only, requires sign-in and remains off until enabled. Migrations 061–077 run after v2.17.0; upgrading from v2.16.0 also includes migration 060. See release notes and Updates and release trust.

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

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

Profile Use it for Includes
rpi Raspberry Pi home gateway WiFi AP (hostapd + dnsmasq), Bluetooth (bluez), 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
Terminal window
curl -fsSL https://thegateway.pro/install.sh | sudo env GATEWAY_PROFILE=rpi bash

The rpi profile additionally:

  • installs hostapd and dnsmasq for the integrated WiFi AP

  • installs bluez and enables Bluetooth for PAN/NAP tethering and scanning

  • 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
GATEWAY_REFRESH 0 Refresh service unit/helper scripts; no packages, config rewrite or restart
GATEWAY_AUTH on Require sign-in; server management requires it
GATEWAY_SERVER_MGMT off Opt into managed servers
GATEWAY_UPDATE_POLICY notify notify, manual, or opt-in auto; only built-in-key signed releases qualify for auto
GATEWAY_HEADSCALE off Run a local mesh control plane
GATEWAY_RELAY_MODE none none, tls, or public; a relay mode requires Headscale
  1. Installs runtime packages on every profile: firewall and routing tools (nftables, iptables, iproute2, conntrack), WireGuard and OpenVPN, a distro-supported dhcpcd package, TLS and SSH clients, SQLite, tcpdump, ethtool, cryptsetup, system utilities, and Python with YAML support. Optional steps add WiFi, Bluetooth, mesh networking, or other selected components.

  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 and offers to start it. Non-interactive installations start it when a binary is available. Review the intended network changes before running the installer.

The 7 October installer maintenance added runtime dependencies previously missing from a base installation, notably openvpn. These remain part of the upstream v2.19.0 installer.

  • Bluetooth (bluez plus dnsmasq for NAP DHCP) is included in the rpi and full profiles, offered by custom, and available through the full installer’s --with-bluetooth flag.
  • The DHCP client package is selected from dhcpcd-base, dhcpcd5, or dhcpcd according to availability. Raspberry Pi installations also try raspi-utils or libraspberrypi-bin when vcgencmd is missing.
  • network-manager is not installed: adding it could take over existing interfaces. AmneziaWG is not installed from distro repositories; it requires its module and awg to be provisioned separately.
  • The distro openvpn service is disabled by a fresh install (or when update mode adds OpenVPN); gatewayd manages tunnel instances itself.

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
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"}
https://<gateway-ip>:8080

The installer supports creating the administrator during installation and writes a private installation summary. If an administrator has not been created yet, use the one-time setup token shown by the installer (or sudo gatewayd setup-token) in the web UI. The setup flow covers:

  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.

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

To pin the current release explicitly:

Terminal window
curl -fsSL https://thegateway.pro/install.sh | sudo env GATEWAY_UPDATE=1 GATEWAY_VERSION=v2.19.0 bash

The update procedure:

  1. Downloads and checksum-verifies the selected binary and refuses a version downgrade unless explicitly requested. It simulates installing missing runtime packages with apt-get --no-upgrade; if existing packages would be upgraded, it skips that package repair and warns. Failed package installation also warns and continues; affected features remain unavailable.
  2. Compares the current and downloaded binary versions. Missing packages are repaired before this check, even when the binary is already current. Matching versions skip the binary replacement and daemon restart.
  3. If the version differs, snapshots the old binary to /usr/local/bin/gatewayd.bak.<timestamp> and gracefully stops the service with systemctl stop.
  4. Replaces the binary, starts the service, waits 4 seconds, and checks systemctl is-active gatewayd.
  5. Rolls back to the snapshot if the service is not active. This is a service-state check, not an HTTP /health probe.

Configuration, database, certificates, and the systemd unit are kept in place. Update mode repairs base dependencies; it does not add optional Bluetooth or WiFi components. GATEWAY_REFRESH=1 separately refreshes the release’s unit and helper scripts without package installation, configuration replacement or restart; they take effect on the next start. The built-in updater in System → Updates has a different confirmation and rollback process, described in Updates and release trust.

Terminal window
curl -fsSLO https://thegateway.pro/releases/latest/SHA256SUMS
curl -fsSLO https://thegateway.pro/releases/latest/gatewayd-linux-amd64
shasum -a 256 -c SHA256SUMS --ignore-missing

Require the downloaded file to report OK. A checksum match alone does not authenticate the publisher if the manifest came from the same compromised source. Read the release notes and release-trust limitation before updating a production gateway. Keep a backup and recovery path available.

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

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.
  • Configuration — what each section of config.yaml controls.
  • Release notes — what changed in v2.19.0 and what to check before upgrading.
  • Sizing & performance — capacity expectations for the hardware you just installed on.
  • FAQ — common pre-install questions.