Linux GUI Client
The Linux GUI Client is designed for Linux desktop environments where a user is present to authenticate with your identity provider interactively.
If you're looking for a headless Client suitable for server or container-based installs, see the Linux headless Client user guide instead.
Prerequisites
- Ubuntu 20.04 or 22.04. Other distributions may work, but are not officially supported.
- x86-64 CPU architecture
- systemd-resolved. Ubuntu already uses this by default.
Installation
Download the .deb
package from our
releases page,
or from the direct link below:
Run these commands:
# Install the package
sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb
# Add yourself to the `firezone-client` group so you can use the tunnel service
sudo usermod -aG firezone-client "$USER"
# Reboot to finish adding yourself to the group
reboot
Usage
Signing in
- Start the GUI from your desktop environment's application
menu or by running
firezone-client-gui
from an interactive shell. - At the Welcome screen, click "Sign in". This will open the Firezone sign-in page in your default web browser.
- Sign in using your account slug and identity provider
- On the first run, check "Always allow" to allow your web browser to sign in to Firezone, then click "Open"
- Unlock your desktop's keyring, or create one if needed. Most desktops, including GNOME, encrypt the keyring with your login password, so your Firezone token is encrypted at rest.
- When you see the "Firezone connected" notification, the tunnel is ready.
The Welcome screen only appears for your first sign-in. After that, you can use the tray menu to sign in.
Accessing a Resource
When Firezone is signed in, web browsers and other programs will automatically use it to securely connect to Resources.
To copy-paste the address of a Resource you have access to:
- Click on the Firezone tray icon to open the menu.
- Open a Resource's submenu and click on its address to copy it.
Quitting
When you quit the Firezone GUI, your token is still stored on the disk, so it will sign in automatically next time you open the GUI.
Signing out
- Click on the Firezone tray icon to open the menu.
- Click "Sign out".
The tunnel is now stopped until you sign in again.
Upgrading
- Quit
firezone-client-gui
if it's running. - Install the new package:
sudo apt-get install ./firezone-client-gui-linux_<VERSION>_<ARCH>.deb
- Restart
firezone-client-gui
.
Diagnostic logs
Firezone writes log files to disk. These logs stay on your computer and are not transmitted anywhere. If you encounter a bug, sending us a zip archive of your logs may help us fix the bug.
To export your logs as a zip archive, or clear your log directory:
- Click on the Firezone tray icon to open the menu.
- Click "Settings".
- Click "Diagnostic Logs".
Uninstalling
- Quit
firezone-client-gui
if it's running. - Remove the package:
sudo apt-get remove firezone-client-gui
Troubleshooting
TODO (reverting DNS, check if DNS is controlled)
Known issues
- Web browsers that use DNS-over-HTTPS by default may not work with Firezone. See this guide to disable DNS-over-HTTPS if you're experiencing issues connecting to DNS Resources within your browser.
- After clearing diagnostic logs, no more logs are written until the GUI and tunnel service each restart. #4764
- The GUI Client does not run on Ubuntu 24.04 yet #4883
- If Firezone is signed in, then closed and re-opened, and you cancel unlocking your keyring, Firezone won't start. #5016
Need additional help?
Try asking on one of our community-powered support channels:
- Discussion forums: Ask questions, report bugs, and suggest features.
- Discord server: Join discussions, meet other users, and chat with the Firezone team
- Email us: We read every message.