macOS Client

Firezone supports macOS with a native client available in the macOS App Store.

Prerequisites

• macOS 12 or higher
• Intel x86-64 or Apple Silicon CPU architecture

Installation

1. Download the Client from the Apple App Store.
2. Click Open in the App Store. The Welcome to Firezone window will open.
3. Click Grant VPN Permission. macOS will show a dialog saying, "Firezone" Would Like to Add VPN Configurations.
4. Click Allow.

Usage

Signing in

1. In the menu bar, click the crossed-out Firezone icon and click Sign In. macOS will show a dialog saying, “Firezone” Wants to Use “firezone.dev” to Sign In.
2. Click Continue. Firezone will open a sign-in page.
3. Select your account and sign in. The Firezone icon should no longer be crossed out.

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:

1. In the menu bar, click the Firezone icon to open the status menu.
2. Open a Resource's submenu and click on its address to copy it.
3. Paste the address into your browser's URL bar and press Return.

Quitting

1. In the menu bar, click on the Firezone icon to open the status menu.
2. Click Disconnect and Quit or Quit.

When Firezone is not running, you can't access private Resources, and the computer will use its normal DNS and Internet behavior.

If you were signed in, then you will still be signed in the next time you start Firezone.

Signing out

1. In the menu bar, Click on the Firezone icon to open the status menu.
2. Click Sign out.

When you're signed out, you can't access private Resources, and the computer will use its normal DNS and Internet behavior.

Upgrading

Use the App Store to update the Firezone Apple Client. See Apple's documentation "Use the App Store to update apps on Mac" for more information.

Diagnostic logs

Firezone writes log files to disk. These logs stay on your computer and are not transmitted anywhere. If you find a bug, you can send us a .aar archive of your logs to help us fix the bug.

To export or clear your logs:

1. In the menu bar, click on the Firezone icon to open the status menu.
2. Click Settings.
3. Click Diagnostic Logs.
4. Click Export Logs or Clear Log Directory.

Uninstalling

1. Quit the Firezone Client.
2. Open Launchpad and find Firezone.
3. Press and hold the Option key, and click on the "X" button on the Firezone icon.

See Apple's documentation "Uninstall apps on your Mac" for more information.

Troubleshooting

Check if Firezone is controlling DNS

1. Open the Terminal app.
2. Run dig firezone.dev and look for a line starting with ;; SERVER:.

If the Firezone is controlling the system's DNS, then the server will be 100.100.111.1 or some other IP in the 100.100.111.0/24 range or fd00:2021:1111:8000:100:100:111:0/120 range.

Firezone Split DNS:

;; SERVER: 100.100.111.1#53(100.100.111.1)
;; WHEN: Thu May 30 00:00:00 UTC 2024
;; MSG SIZE  rcvd: 57

Normal system DNS:

;; SERVER: fe80::96a6:7eff:fe78:edb7%15#53(fe80::96a6:7eff:fe78:edb7%15)
;; WHEN: Thu May 30 00:00:00 UTC 2024
;; MSG SIZE  rcvd: 57

Known issues

• Authentication will not use Firefox even if it is the default browser: Firezone will not use Firefox for authentication on macOS even if it is the default browser. This is due to Firefox's lack of support for Apple's WebAuthenticationSession API. To work around this issue, use Safari or Chrome for authentication.
• Cloudflare WARP client conflicts with other VPN apps: The Cloudflare WARP client may interfere with Firezone's ability to initialize its tunnel interface or resolve DNS resources. Ensure the Cloudflare WARP client is disabled completely or uninstalled to prevent these issues. See this thread on our forum for more information.
• SentinelOne agent can block DNS queries: The SentinelOne agent for macOS may interfere with Firezone's ability to successfully forward and reply to DNS queries made by applications on macOS. The symptom when this occurs is that all DNS queries on the system will fail, not just those that match the DNS Resources you have in your account. See this issue for more information: #6768.