Configuration

Overview

Formal Endpoint reads ~/.formal/config.toml on startup. Restart Formal Endpoint after you edit the file. On macOS, Forced .mobileconfig keys override ~/.formal/config.toml. See MDM overrides.

`config.toml` settings

Every key the Endpoint reads from ~/.formal/config.toml:

Key	Type	Default	Description
`check_for_updates`	bool	`false`	Notify in the systray when a newer Endpoint version is present. If omitted, the systray does not show an update.
`hide_systray_icon`	bool	`false`	Hide the system tray icon. The agent keeps running in the background.
`postgres_db`	string	unset	Default database name for PostgreSQL connections (`formal connect --launch` and the TUI). If omitted, Formal prompts for a name.
`launch_commands`	bool	unset	Launch the matching CLI after you connect, such as `psql` or `ssh`. If omitted, the TUI asks once and saves the answer.
`auth_mode`	string	unset	Set to `"oidc"` to authenticate with an OIDC token source. `FORMAL_API_KEY` takes precedence.
`oidc.provider`	string	unset	OIDC token source: `aws`, `azure`, `gcp`, `github`, `cursor`, `devin`, or `spiffe`. Mutually exclusive with `oidc.env` and `oidc.file`. Requires `oidc.integration_id`.
`oidc.env`	string	unset	Environment variable that holds an OIDC JWT. Mutually exclusive with `oidc.provider` and `oidc.file`.
`oidc.file`	string	unset	Path to a file that holds an OIDC JWT. The Endpoint reads it on every refresh. Mutually exclusive with `oidc.provider` and `oidc.env`.
`oidc.integration_id`	string	unset	Formal OIDC integration ID. Required with `oidc.provider`. Also set it when the JWT audience is not `oidc.formal.ai/<id>`.
`transparent_proxy.enable`	bool	`false`	Enable Transparent Mode when the Endpoint starts.
`transparent_proxy.enforce`	bool	`false`	Lock `formal transparent-proxy install`, `formal transparent-proxy enable`, and the tray toggle.
`transparent_proxy.fail`	string	`"open"`	If the Endpoint errors: `open` preserves connectivity; `closed` keeps the proxy enforced.
`transparent_proxy.allow_quic`	bool	`false`	Allow QUIC (UDP/443). Default `false` blocks QUIC so clients fall back to TCP/TLS. Blocking QUIC is required to intercept Claude Chat in the Claude Desktop App.
`transparent_proxy.intercept_localhost`	bool	`false`	Intercept IPv4 loopback traffic, such as local tunnels on `127.0.0.1`.
`transparent_proxy.synthetic_ipv4_cidr`	string	`"198.18.0.0/15"`	Linux synthetic DNS address pool. Choose a CIDR that does not overlap upstream destinations.
`transparent_proxy.synthetic_ipv6_cidr`	string	`"2001:2::/48"`	Linux synthetic DNS address pool for IPv6. Choose a CIDR that does not overlap upstream destinations.
`install.ca`	bool	`true`	macOS only. Run `formal ca generate` and `formal ca trust` when the package installs or upgrades. `false` also skips `formal transparent-proxy install`.
`install.transparent_proxy`	bool	`true`	macOS only. Run `formal transparent-proxy install` when the package installs or upgrades.
`transparent_proxy.runtime_ca_env`	string	`"agents_only"`	Which runtimes are pointed at the Formal CA bundle with `SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, and related variables: `none`, `agents_only` (Claude Code), or `all` (also the macOS login session). See Runtime TLS trust.
`telemetry.third_party`	bool	`true`	Send Endpoint errors and crash reports to third-party services. Today this is Sentry only. Set to `false` to opt out. See Third-party telemetry.

check_for_updates = false
hide_systray_icon = false
postgres_db = "postgres"
launch_commands = true
auth_mode = "oidc"

[oidc]
provider = "aws"
integration_id = "integrationoidc_<id>"

[transparent_proxy]
enable = true
enforce = true
fail = "open"
allow_quic = false
intercept_localhost = false
runtime_ca_env = "agents_only"

[telemetry]
third_party = true

Omit [oidc] and auth_mode unless the Endpoint should authenticate with OIDC. Use oidc.env or oidc.file instead of oidc.provider when the JWT comes from an environment variable or a file. See Log In with OIDC.

Configuring Transparent Mode on Startup

To avoid toggling Transparent Mode every time you open Formal Endpoint, configure it in ~/.formal/config.toml.

[transparent_proxy]
enable = true
enforce = true
fail = "open"
allow_quic = false
intercept_localhost = false

enable specifies whether the endpoint agent should try to enable Transparent Mode upon startup. If omitted, enable defaults to false. enforce controls whether you can change Transparent Mode behavior with formal transparent-proxy install, formal transparent-proxy enable, and the tray toggle. If omitted, enforce defaults to false.

Privileged users can still disable the network extension without formal transparent-proxy enable or formal transparent-proxy disable.

fail can be open or closed. If the endpoint agent errors, open preserves network connectivity. closed keeps enforcing that Transparent Mode is running. If omitted, fail defaults to open. allow_quic controls whether Transparent Mode allows QUIC traffic (UDP/443). Blocking QUIC is required to intercept Claude Chat sessions in the Claude Desktop App. If omitted, allow_quic defaults to false. intercept_localhost controls whether Transparent Mode intercepts IPv4 loopback traffic, such as local tunnels on 127.0.0.1. If omitted, intercept_localhost defaults to false. On Linux, restart the Endpoint after changing either synthetic DNS pool. Invalid CIDRs or incorrect address families prevent Transparent Mode from enabling. Restart client applications to clear cached DNS answers from the old pool. runtime_ca_env controls which runtimes the Endpoint points at its CA bundle. none sets no variables and removes the ones the Endpoint wrote to Claude Code’s ~/.claude/settings.json. agents_only sets them only in Claude Code’s settings. all also sets them in the macOS login session. If omitted, runtime_ca_env defaults to agents_only. The legacy values false and true mean agents_only and all. See Runtime TLS trust. See Transparent Mode for install and enable steps.

Third-party telemetry

By default, the Endpoint sends errors and crash reports to Sentry. On macOS, this includes the network extension. To opt out, set third_party = false under [telemetry]:

[telemetry]
third_party = false

This setting covers third-party services only. The Endpoint still sends its own health telemetry to the Formal Control Plane. Restart the Endpoint after you change this setting. On macOS, the network extension picks up the change the next time Transparent Mode starts.

MDM overrides (macOS)

Forced .mobileconfig keys override ~/.formal/config.toml. On macOS, Forced keys in the com.formal.desktop domain take precedence over the file. They apply even when config.toml is absent. Deploy the values as Forced (locked) keys in a com.apple.ManagedClient.preferences payload. Generate the profile from Endpoint Rollout in the Control Plane.

Managed preference key	Type	`config.toml` setting
`checkForUpdates`	bool	`check_for_updates`
`hideSystrayIcon`	bool	`hide_systray_icon`
`transparentProxyEnable`	bool	`transparent_proxy.enable`
`transparentProxyEnforce`	bool	`transparent_proxy.enforce`
`transparentProxyFail`	string	`transparent_proxy.fail` (`open` or `closed`)
`transparentProxyAllowQuic`	bool	`transparent_proxy.allow_quic`
`transparentProxyInterceptLocalhost`	bool	`transparent_proxy.intercept_localhost`
`transparentProxyRuntimeCaEnv`	string or bool	`transparent_proxy.runtime_ca_env`
`installTransparentProxy`	bool	`install.transparent_proxy`
`installCA`	bool	`install.ca`
`telemetryThirdParty`	bool	`telemetry.third_party`

These config.toml keys have no MDM mapping: postgres_db, launch_commands, auth_mode, and [oidc].

Require a password to uninstall

Set the uninstallPasswordHash managed preference to protect formal uninstall. This key exists only in the .mobileconfig profile. It is not a config.toml setting. When the key is present, the CLI prompts for the password. It refuses to remove Formal unless the password matches. Turn on Require uninstall password on the Configuration Profile step in Endpoint Rollout and enter a password. Formal embeds the SHA-256 hex digest in the profile. The plaintext password never leaves your browser.

This is a deterrent, not tamper protection. A user with sudo can still stop processes and delete files manually.

Next Steps

Formal Endpoint

Install the app, log in, and connect to resources

Linux

Install the headless package on Debian or Ubuntu

MDM Integration

Deploy Formal Endpoint with your MDM

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Overview

`config.toml` settings

Configuring Transparent Mode on Startup

Third-party telemetry

MDM overrides (macOS)

Require a password to uninstall

Next Steps

Formal Endpoint

Linux

MDM Integration

​Overview

​config.toml settings

​Configuring Transparent Mode on Startup

​Third-party telemetry

​MDM overrides (macOS)

​Require a password to uninstall

​Next Steps

Formal Endpoint

Linux

MDM Integration

Overview

`config.toml` settings

Configuring Transparent Mode on Startup

Third-party telemetry

MDM overrides (macOS)

Require a password to uninstall

Next Steps