Headmaster by GCAP Labs

The egress proxy is an optional safeguard for agents that run commands inside a Docker sandbox. Normally that sandbox holds your real provider keys, so a command that went wrong could print them. With the proxy on, the sandbox holds only proxy tokens. A small program on your computer swaps each token for the real key as the request leaves, so the real keys never enter the sandbox.

It is off by default and only matters if you use the Docker terminal backend. See Tools and toolsets.

What it covers

It protects the sandbox. Headmaster itself keeps using your keys directly.
It works with the Docker backend only. Other backends do not get the proxy yet.
It handles keys sent in a header or a query string for the major model providers, including OpenAI, Anthropic, Google, xAI, Mistral, Groq, Together, DeepSeek, OpenRouter and Azure OpenAI.
It does not cover providers that sign each request or mint their own sign-in, such as AWS and Google Cloud credentials. If those are set on your computer, the sandbox still holds real values for them. headmaster egress status warns you.
It is outbound only. It is not related to any proxy that lets other tools reach Headmaster.

Turn it on

headmaster egress install
headmaster egress setup
headmaster egress start
headmaster egress status

install downloads the proxy program. The version is pinned and its checksum is verified.
setup creates a local certificate authority, makes a token for each provider key it finds, and writes the proxy config. It reads keys from your environment and from the settings file in your Headmaster home folder.
start runs the proxy in the background.
status shows the program, config, process, whether it is listening, and the token mappings.

Once it is running, the Docker sandbox is set up automatically: the certificate is mounted in, all web traffic is routed through the proxy, and each provider key is replaced by a token.

If you run setup again later, for example to add a host, it stops the running proxy and offers to restart it. Pass --restart to always restart, or --no-restart to leave it stopped.

Commands

Command	What it does
`install`	Download the pinned proxy program. `--force` re-checks and repairs it.
`setup`	Guided setup. See the options below.
`start`	Start the proxy.
`stop`	Stop it.
`restart`	Stop and start. Use it when real keys change, for example after rotating one or adding a provider.
`reload`	Re-read the allowed hosts from the config without a restart or dropped connections.
`status`	Show the state. `--show-tokens` prints tokens in full. By default only part of each is shown.
`disable`	Turn the integration off. It does not stop a running proxy.
`config`	Print the path of the generated proxy config file.

Each is run as headmaster egress <command>.

Options for setup:

Option	What it does
`--tunnel-port N`	Use a different port.
`--from-bitwarden`	Take real keys from Bitwarden. See Secrets.
`--no-bitwarden`	Switch back to reading keys from your environment.
`--rotate-tokens`	Make new tokens for every provider.
`--restart` / `--no-restart`	Restart a running proxy afterwards, or leave it stopped.

Settings

In the proxy section of your config file (headmaster config path prints its location):

proxy:
  enabled: false
  tunnel_port: 9090
  auto_install: true
  credential_source: env
  enforce_on_docker: true
  allow_env_fallback: false
  extra_allowed_hosts: []

Setting	What it does
`enabled`	The master switch. When `false`, nothing is downloaded, mounted or started.
`tunnel_port`	The port the sandbox uses to reach the proxy.
`auto_install`	Download the pinned program the first time it is needed.
`credential_source`	Where real keys come from: `env` or `bitwarden`.
`enforce_on_docker`	If `true`, a Docker sandbox refuses to start while the proxy is enabled but not running. Set `false` to fall back to real keys in the sandbox.
`allow_env_fallback`	With Bitwarden as the source, whether to fall back to local keys when Bitwarden cannot be reached. Off by default.
`extra_allowed_hosts`	More hosts the sandbox may reach, such as a private model server. Wildcards like `*.example.com` work, but do not match `example.com` itself.

Only hosts on the allow list can be reached through the proxy. The major model providers are included by default.

Safety limits

The proxy refuses requests to your own machine and private networks, including loopback, the usual cloud metadata addresses, private ranges and carrier-grade ranges. This stops an allowed hostname from being turned against your internal network.
It never listens on every network interface. On Linux it binds to the Docker bridge address. On macOS and Windows it binds to loopback. Other devices on your network cannot use it.
A token only works through your proxy, and only for allowed hosts.

Rotating tokens and keys

setup keeps existing tokens when you re-run it, so running sandboxes keep working. Adding a provider makes a token only for the new one.

headmaster egress setup --rotate-tokens replaces every token. Running sandboxes start getting errors until they are restarted, so it asks you to type rotate to confirm. A backup of the old mappings is saved next to them first.

With Bitwarden as the source, the proxy reads your keys again each time it starts. To pick up a rotated key, run headmaster egress restart. If Bitwarden cannot be reached, the proxy refuses to start instead of using stale local keys, unless you set allow_env_fallback.

Files

Everything lives in the proxy folder inside your Headmaster home folder, readable only by you:

File	What it holds
`ca.crt`	The public certificate that sandboxes trust.
`ca.key`	The signing key. Never leaves your computer. Treat it as sensitive.
`proxy.yaml`	The proxy config. It is rewritten by every `setup`.
`mappings.json`	Which token stands for which provider key.
`iron-proxy.log`	The proxy log, including one record per request. Use this one for troubleshooting and review.

Limits

A program in the sandbox that ignores the standard proxy and certificate settings will not work through it. Node.js is set up for this automatically, but some tools may need a closer look.
Anyone who holds ca.key, or who can redirect the sandbox to a different proxy, can read traffic. Keep the key private.

Egress proxy