How Secret Brew Configurations stay secret

A regular Brew Configuration is written to /etc/homebrew/brew.env on each Device. That file is world-readable, which is fine for a flag like HOMEBREW_NO_UPDATE_REPORT_NEW but wrong for a credential. A Secret Brew Configuration exists to carry a sensitive value, such as a token, without putting it in that file or in any user's shell. This page explains how that guarantee holds and where a secret value is and is not available.

Secret Brew Configurations are available on Workbrew Enterprise.

Not written to disk#

A secret value is never written to /etc/homebrew/brew.env, or to any other file on the Device. The Workbrew Agent keeps it in the memory of its daemon process and nowhere else. Because it is never persisted, it does not survive a daemon restart on its own; the Agent receives it again on its next check-in with the Workbrew Console.

This is the central difference from a regular Brew Configuration, which is persisted to brew.env so that it applies to every brew invocation, including ones a user runs in their own terminal.

Injected only when the Agent runs brew#

The Agent adds secret values to the environment of the brew process only when it is the one running brew. Specifically, they are set for:

• Console-pushed install, upgrade, and reinstall operations
• Brew Commands run through the Agent
• Default Packages applied through the Agent

They are not available to brew run directly in a user's terminal. When a user runs brew themselves, it executes with their normal shell environment, which never contains the secret. A user on the Device cannot read the value by inspecting their environment, by reading brew.env, or by running a command that prints it.

Kept out of logs#

Secret values are passed to brew through the process environment, not as command-line arguments, so they do not appear in the Agent's command logs or in error reports.

What an administrator can see#

In the Workbrew Console, secret values are masked in the Brew Configurations list. A Workspace administrator who opens a Secret Brew Configuration to edit it can still see and change its value, since editing requires reading the current value. The masking protects the value at a glance and in the list; it is not a barrier against an administrator who is already permitted to manage the configuration.

The value travels to each Device over the same authenticated, encrypted connection the Agent already uses to check in with the Console.

Why it works this way#

The goal is to let you hand brew a credential it needs while the Agent installs or upgrades software, without that credential leaking into a world-readable file or into the environment of every user on the machine. Holding the value in memory and injecting it only for Agent-run brew operations keeps it scoped to exactly the moment it is needed.

To set one up, see Set a Secret Brew Configuration.

Related docs#

• Set a Secret Brew Configuration — the steps to create one and provision a token.
• How Workbrew uses elevated privileges — the broader Agent security model these guarantees sit within.
• How policies apply to devices in multiple groups — how a secret value resolves when a Device is in several groups.
• Glossary — definitions of Brew Configurations, Brew Commands, and Default Packages.