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 public download is v2.16.0. It adds managed user accounts, static DHCP reservations and role-aware controls, and fixes live DHCP changes and policy enforcement after restart. No configuration change is required; migration 059 creates the reservations table. Nodes with reconciliation disabled now apply initial enforcement once at startup. WAN balancing remains optional and off by default. See release verification for test scope and limits.

Latest binaries are served from the site

The bootstrap now selects the original upstream gatewayd-linux-amd64.gz or gatewayd-linux-arm64.gz archive, checks its SHA256, decompresses it, and checks the upstream uncompressed SHA256 before installation. A pinned copy is available at https://thegateway.pro/releases/v2.16.0/.

The existing raw binary URLs remain available as stripped compatibility builds from the same tag. Those use the hosted SHA256SUMS; the decompressed originals use UPSTREAM_SHA256SUMS. Do not mix the manifests. See artifact details.

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

Don't run on production traffic on first install

The installer creates an nftables table that takes over packet handling. Test on a spare device or VM before pointing real clients at it.

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), 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

Quick install

Raspberry Pi 4

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

• 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

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

From a prebuilt binary

sudo ./scripts/install-gateway.sh \
  --profile vps \
  --binary /tmp/gatewayd-linux-arm64

Use this when you’ve cross-compiled the daemon elsewhere and want to skip the download.

From source

git clone https://example.invalid/gateway.git
cd gateway
go build -o gatewayd ./cmd/gatewayd/
sudo install -m 0755 gatewayd /usr/local/bin/
sudo ./scripts/install-gateway.sh --profile node

Cross-compilation for the Pi from x86 dev box:

GOOS=linux GOARCH=arm64 go build -o gatewayd-arm64 ./cmd/gatewayd/

What the installer does

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 but does not auto-start it — review the config first.

Installer update — 7 October 2026

The hosted installers now include runtime dependencies previously missing from a base installation, notably openvpn. The daemon download remains v2.16.0; this is an installer update, not a new binary release.

• 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.

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

sudo systemctl enable gatewayd
sudo systemctl start gatewayd
systemctl status gatewayd
journalctl -u gatewayd -f

Health check:

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

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

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

To pin the current release explicitly:

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

The update procedure:

1. Downloads and verifies the selected binary, then installs missing base runtime packages with apt-get --no-upgrade. This does not request upgrades of already-installed packages; the package manager may install dependencies. If package installation fails, the script 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.

Verify the hosted release

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

The latest manifest currently points to v2.16.0. Read the release notes before updating production gateways or enabling automatic WAN failover or balancing. Start with manual monitoring and keep a recovery path available.

Uninstall

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

Tip

Take a backup before uninstalling. The export is a single AES-256-GCM-encrypted JSON that round-trips all your policies, devices and tunnels.

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.

Related

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