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`, `cursor`, or `devin`. Mutually exclusive with `oidc.env`. Requires `oidc.integration_id`.
`oidc.env`	string	unset	Environment variable that holds an OIDC JWT. Mutually exclusive with `oidc.provider`.
`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 the transparent proxy 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`.

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

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

Configuring the Transparent Proxy on Startup

To avoid toggling the transparent proxy 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 the transparent proxy upon startup. If omitted, enable defaults to false. enforce controls whether you can change transparent proxy 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 the transparent proxy is running. If omitted, fail defaults to open. allow_quic controls whether the transparent proxy 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 the transparent proxy intercepts IPv4 loopback traffic, such as local tunnels on 127.0.0.1. If omitted, intercept_localhost defaults to false. See Transparent Proxy for install and enable steps.

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 Formal console.

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`

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. Enter an Uninstall Password on the Configuration Profile step in Endpoint Rollout. 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.

Overview

`config.toml` settings

Configuring the Transparent Proxy on Startup

MDM overrides (macOS)

Require a password to uninstall

Next Steps

Formal Endpoint

MDM Integration

​Overview

​config.toml settings

​Configuring the Transparent Proxy on Startup

​MDM overrides (macOS)

​Require a password to uninstall

​Next Steps

Formal Endpoint

MDM Integration

Overview

`config.toml` settings

Configuring the Transparent Proxy on Startup

MDM overrides (macOS)

Require a password to uninstall

Next Steps