Configure your firewall for Workbrew

This guide walks you through configuring your network firewall to allow Workbrew devices to communicate with the Workbrew Console and download Homebrew packages. For a full list of domains and ports, see Network requirements.

Allow Workbrew Console and CDN traffic#

Add the following FQDN-based allowlist rules for outbound HTTPS traffic on port 443:

console.workbrew.com
cdn.workbrew.com
workbrew-console.nyc3.cdn.digitaloceanspaces.com

console.workbrew.com carries agent check-ins and commands. Agent installer downloads for automatic updates come from cdn.workbrew.com, which redirects to object storage at workbrew-console.nyc3.cdn.digitaloceanspaces.com, so allow the redirect target as well or updates will fail partway through. console.workbrew.com also serves installers as an authenticated fallback when the CDN is unavailable.

Allow Homebrew package traffic#

Add the following FQDN-based allowlist rules for outbound HTTPS traffic on port 443:

formulae.brew.sh
ghcr.io
github.com
gitlab.com
*.githubusercontent.com

These are required for Homebrew to fetch formula and cask metadata, download pre-built bottles, update taps, and download cask artifacts hosted on GitHub Releases. Allow gitlab.com only if your fleet uses GitLab-hosted taps.

Allow cask vendor domains#

Cask downloads come directly from each application's vendor. If your firewall restricts outbound traffic, you will need to allowlist vendor domains for each cask your fleet uses.

For example, to allow Google Chrome and Firefox downloads:

dl.google.com
download.mozilla.org

You can find the download URL for a specific cask by running:

brew info --cask <cask-name>

Use an HTTP proxy instead#

If your organization routes traffic through an HTTP proxy, the Workbrew Agent auto-detects macOS system proxy settings, including PAC (Proxy Auto-Configuration) files. No additional configuration is needed for the Agent's own traffic to the Console.

Homebrew does not use those system settings, so its downloads need the proxy set explicitly. Add these as Brew Configurations in the Console:

• https_proxy, and http_proxy if you proxy plain HTTP as well
• no_proxy for any hosts that should bypass the proxy, such as an internal mirror

Variable names must be lowercase. Set them in the Console rather than in a user's shell profile, because Workbrew runs package installs as its own daemon, which does not inherit a user's environment. A proxy exported in ~/.zshrc applies only when that user runs brew themselves.

Unlike the domain variables below, a proxy set this way also covers cask downloads.

If you run a caching proxy or internal mirror such as Artifactory or Nexus, you can redirect specific traffic to it:

• Set HOMEBREW_ARTIFACT_DOMAIN to route bottle downloads through your proxy. It rewrites only ghcr.io URLs
• Set HOMEBREW_BOTTLE_DOMAIN to redirect bottle downloads to an internal mirror
• Set HOMEBREW_API_DOMAIN to redirect API metadata requests to an internal mirror

These variables cover bottle, metadata, and Git traffic only. They do not affect cask downloads, which still go directly to their vendor domains, so either allowlist those separately as shown in Allow cask vendor domains above, or send them through a proxy with https_proxy.

See Network requirements for the full list of configurable environment variables.

Verify connectivity#

After configuring your firewall, verify that a device can reach all required endpoints:

curl -s -o /dev/null -w "%{http_code}" https://console.workbrew.com
curl -s -o /dev/null -w "%{http_code}" https://cdn.workbrew.com
curl -s -o /dev/null -w "%{http_code}" https://formulae.brew.sh/api/formula.json
curl -s -o /dev/null -w "%{http_code}" https://ghcr.io/v2/
curl -s -o /dev/null -w "%{http_code}" https://github.com

Any HTTP status code confirms the endpoint is reachable, because the server answered. Expect 200 from the Console, formulae.brew.sh and github.com, 401 from ghcr.io since it requires authentication, and 404 from the CDN root since it has no index page. A connection timeout or 000 means the domain is still blocked.