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`, `cursor`, or `devin`. 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`.

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 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. See Transparent Mode 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 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`

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.

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

MDM overrides (macOS)

Require a password to uninstall

Next Steps

Formal Endpoint

Linux

MDM Integration

​Overview

​config.toml settings

​Configuring Transparent Mode on Startup

​MDM overrides (macOS)

​Require a password to uninstall

​Next Steps

Formal Endpoint

Linux

MDM Integration

Overview

`config.toml` settings

Configuring Transparent Mode on Startup

MDM overrides (macOS)

Require a password to uninstall

Next Steps