Deploy a Gateway on NixOS

Firezone ships a first-party flake with a NixOS module for the Gateway, so you can manage it declaratively alongside the rest of your system configuration. The module wires the Gateway up as a hardened systemd service, configures the packet forwarding and NAT masquerading it needs, and reads its token via systemd credentials so it never enters the Nix store.

Before you start, open Sites → <your Site> → Deploy a Gateway in the admin portal and copy the token. Review the sizing guidelines to choose a host first.

Add the flake as an input, pinning the release tag of the Gateway:

# flake.nix
{
inputs.firezone.url = "github:firezone/firezone/gateway-1.5.2";
}

Then import the module and enable the service in your system configuration:

# configuration.nix
{ inputs, ... }:
{
  imports = [ inputs.firezone.nixosModules.gateway ];

  # Substitute pre-built, Firezone-signed binaries instead of compiling the
  # Gateway from source. Optional, but strongly recommended.
  nix.settings = {
    extra-substituters = [ "https://artifacts.firezone.dev/nix" ];
    extra-trusted-public-keys = [
      "artifacts.firezone.dev/nix-1:T4LHdL1HeA6LE9qgu0Po0j3RIlelKZz8pzqnzEAIRfI="
    ];
  };

  services.firezone.gateway = {
    enable = true;

    # Path to a file containing the Gateway token from the admin portal. Keep
    # this out of the Nix store — point it at a secret managed outside of your
    # configuration (e.g. with sops-nix or agenix), or place it manually.
    tokenFile = "/var/lib/secrets/firezone-gateway-token";

    # The interface tunnel traffic is masqueraded out of. Required unless
    # networking.nat.externalInterface is already set.
    nat.externalInterface = "eth0";

    # Optional. Defaults to the system hostname.
    name = "my-nixos-gateway";
  };
}

Rebuild to start the Gateway:

sudo nixos-rebuild switch

The service runs as firezone-gateway. Check its status and logs with:

systemctl status firezone-gateway
journalctl -u firezone-gateway -f

Module options

The options for services.firezone.gateway:

Option	Default	Description
`enable`	`false`	Install the Gateway and enable the service.
`tokenFile`	(required)	Path to a file containing the Gateway token. Passed via systemd credentials; must not live in the Nix store.
`name`	`config.networking.hostName`	Friendly name shown in the admin portal.
`id`	`null`	Unique Gateway identifier. When null, a deterministic ID is derived from `/etc/machine-id`.
`apiUrl`	`wss://api.firezone.dev/`	WebSocket URL of the Firezone control plane API.
`logLevel`	`info`	`RUST_LOG` directives for the Gateway.
`enableTelemetry`	`true`	Whether to allow crash reporting and telemetry.
`nat.enable`	`true`	Configure NAT masquerading for tunnel traffic via `networking.nat`. Disable to manage masquerading yourself.
`nat.externalInterface`	`null`	Interface tunnel traffic is masqueraded out of. May be null if `networking.nat.externalInterface` is set.
`extraEnvironment`	`{ }`	Extra `FIREZONE_*` environment variables for the Gateway.

The Gateway requires IP forwarding to route at all, so the module sets the net.ipv4.ip_forward and IPv6 forwarding sysctls unconditionally (as mkDefault, so you can override them via boot.kernel.sysctl if you manage forwarding yourself).

Substituter changes only take effect after a rebuild, so the very first build with the cache configured may still compile from source. If the cache is unreachable, Nix falls back to building from source — slower, but never broken.

Need help? See all support options.