> ## Documentation Index > Fetch the complete documentation index at: https://docs.formal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Configure Formal Endpoint with ~/.formal/config.toml and macOS MDM profiles ## 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](#mdm-overrides-macos). ## `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/`. | | `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`. | ```toml theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}} check_for_updates = false hide_systray_icon = false postgres_db = "postgres" launch_commands = true auth_mode = "oidc" [oidc] provider = "aws" integration_id = "integrationoidc_" [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](/docs/guides/client-apps/desktop-app#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`. ```toml theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}} [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](/docs/guides/client-apps/desktop-app#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. ## Next Steps Install the app, log in, and connect to resources Deploy Formal Endpoint with your MDM