To install Firezone UI for WireGuard VPN on Debian 12 today, deploy a Firezone Gateway on your VPS and manage it from the Firezone Admin Portal. The current setup takes about 10 minutes and gives approved users access to private servers, apps, or subnets through Firezone’s WireGuard-based client.
The old all-in-one Firezone 0.7 web interface is end-of-life, so this guide uses the supported architecture: Firezone hosts the control plane while your Debian server runs the Gateway.
Prerequisites
- Debian 12 (Bookworm) on a 64-bit VPS with a public or otherwise reachable network connection.
- A root shell or a sudo-enabled user connected over SSH.
- At least 1 vCPU and 1 GB RAM for a small Gateway; choose more CPU, memory, and bandwidth as your client count grows.
- The server must be able to reach the internet and the private resource you want to publish through Firezone.
- A free or paid Firezone account and an end-user device for testing. The current deployment does not require a domain name or a local TLS certificate.
- A fresh VPSLake Linux VPS with Debian 12 is suitable for this Gateway.
Step 1: Update Debian and install prerequisites
Updating the base system and installing the packet-filtering tools gives the Gateway the commands it expects on Debian 12.
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates gnupg iptables wget
Confirm the server is Debian 12 and that both IPv4 and IPv6 firewall commands exist:
. /etc/os-release && printf '%s\n' "$PRETTY_NAME"
iptables --version
ip6tables --version
Expected output includes Debian GNU/Linux 12 and an iptables v1.x version for each command.
Step 2: Create a Firezone Site and Gateway token
The portal creates the Gateway identity and gives this one server a single-owner token; the token is not a replacement for your Debian login password.
- Open the Firezone Admin Portal and create an account or sign in.
- Open Sites → Add Site, give the site a name such as
Debian-12-VPS, and save it. - On the new Site Details page, select Deploy a Gateway.
- Select the Debian/Ubuntu installation method and copy the one-time Gateway token into a password manager.
Do not paste the token into a shared ticket, commit it to a repository, or put it directly in a shell command. Each new Gateway should get its own token.
Step 3: Add the official Firezone APT repository
The Firezone repository supplies the current Gateway package and its systemd service, so you can update it with Debian’s normal package tools.
sudo mkdir --parents /etc/apt/keyrings
wget -qO- https://artifacts.firezone.dev/apt/key.gpg | sudo gpg --dearmor --yes -o /etc/apt/keyrings/firezone.gpg
echo "deb [signed-by=/etc/apt/keyrings/firezone.gpg] https://artifacts.firezone.dev/apt/ stable main" | sudo tee /etc/apt/sources.list.d/firezone.list > /dev/null
sudo apt update
sudo apt install -y firezone-gateway
The package installation should finish without an Unable to locate package error. The repository and package instructions are also documented in the Firezone Debian deployment guide.
Step 4: Authenticate and start the Gateway
Authentication registers this VPS with the Site you created, then systemd keeps the Gateway running after disconnects and reboots.
Run the interactive command and paste the token when prompted:
sudo firezone-gateway authenticate
Now check the service:
sudo systemctl is-enabled firezone-gateway
sudo systemctl is-active firezone-gateway
sudo systemctl status firezone-gateway --no-pager
Expected output includes:
enabled
active
Active: active (running)
Return to Firezone Admin Portal → Sites → Debian-12-VPS. The Gateway should appear as online. If it remains offline, keep the terminal open and inspect the service log in the Troubleshooting section.
Step 5: Keep the VPS firewall narrow
The current architecture does not expose a Firezone web dashboard on the VPS, so you do not need to open ports 80 or 443 or install a local certificate. Keep inbound access limited to SSH and allow outbound connections to the Firezone control plane and your resources.
If UFW is already your firewall, preserve your SSH session before enabling or changing it, then use:
sudo ufw allow OpenSSH
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force enable
sudo ufw status verbose
Expected output shows the firewall active, OpenSSH allowed, incoming traffic denied by default, and outgoing traffic allowed. Do not add broad inbound rules just because older self-hosted Firezone instructions used HTTPS on the server.
Step 6: Add a resource, policy, and client
A Gateway being online only establishes the tunnel; Firezone’s default-deny policy still requires you to name a resource and authorize a user group.
- In Site Details → Add Resource, enter a name such as
Private-Weband the destination address. Use an IP address, FQDN, or CIDR range such as10.20.0.15,db.internal.example, or10.20.0.0/24. - Open Policies → Add Policy, select the resource, and grant access to the intended group. Save the policy.
- Open the Firezone client download page, install the client on a test device, and sign in with your Firezone account slug.
- In the client, select the resource you authorized and connect.
The Gateway must be able to route to the resource from the VPS. A policy cannot make an unreachable private network reachable by itself.
Verify the Gateway and private access
First verify the local service and its recent logs:
sudo systemctl is-active firezone-gateway
sudo journalctl -u firezone-gateway -n 30 --no-pager
Expected output is active followed by recent service entries without repeated authentication or connection failures. The Admin Portal should show the Gateway as online.
Next, test the resource from the Firezone client. For an HTTP resource, substitute its address and port:
curl --connect-timeout 5 http://RESOURCE_IP:PORT/
Replace RESOURCE_IP and PORT with a service that is intentionally allowed by your policy. A response from that service proves the client, policy, Gateway, and resource path are working together. For SSH or RDP, use the same private address in the normal client after the Firezone tunnel reports connected.
Troubleshooting
Unable to locate package firezone-gateway
APT has not loaded the Firezone repository, or the repository file/key was created incorrectly. Re-run the repository commands in Step 3, then run sudo apt update and confirm that sudo apt install firezone-gateway now finds a candidate package.
Authentication failed or the token is already claimed
Current Gateway tokens are single-owner tokens. In Sites → YOUR_SITE → Gateways, remove or rotate the stale Gateway, choose Deploy a Gateway again, and authenticate this VPS with the newly generated token. Never reuse a token on two active servers.
The Gateway stays offline
Check sudo journalctl -u firezone-gateway -n 50 --no-pager for DNS, TLS, or network errors. Confirm the VPS has working DNS and outbound internet access, and check any VPS provider firewall or corporate egress filter; the current Gateway does not need an inbound dashboard port.
The client connects but cannot reach the resource
This is usually a policy or routing problem. Confirm the resource address is correct, the user belongs to the group selected by the policy, and the Debian server can reach the destination directly with a suitable test such as curl or nc; also check that the resource’s own firewall permits traffic from the Gateway path.
Hardening and maintenance
- Treat the Gateway token like a password. Rotate it in the Firezone portal if it was exposed, then restart or re-authenticate the service with the replacement token.
- Restrict SSH to trusted source addresses at the VPS provider firewall when possible, and use SSH keys instead of password authentication.
- Apply Gateway updates through APT and review the service after each upgrade:
sudo apt update
sudo apt install --only-upgrade firezone-gateway
sudo systemctl is-active firezone-gateway
- For production availability, place Gateways in separate hosts and create one token per Gateway rather than cloning this server’s credentials.
FAQ
Can I open the Firezone dashboard at my VPS IP address?
Not with the current Firezone architecture. The admin interface is hosted in the Firezone Admin Portal, while the Debian server runs only the Gateway data-plane service.
Do I need Docker to install Firezone on Debian 12?
No. The native APT method installs firezone-gateway as a systemd service and is the shortest route on Debian. Firezone also documents a Docker Gateway deployment if you already operate Docker on the host.
Does this create a traditional wg0 configuration file?
No. The current Gateway manages the WireGuard-based tunnel and its routing through the Firezone service. You configure Sites, resources, groups, and policies in the portal instead of distributing hand-written wg-quick peer files.
Is a domain required for the Debian 12 Gateway?
No. A domain and local certificate were needed by older self-hosted web UI instructions, but this Gateway connects to the hosted control plane and does not publish a local HTTPS interface.