Client configuration

Use this page to change how the client behaves on a machine: where it keeps its state, how it reaches the platform, and which of its parts run.

openlatch init writes the configuration for you. Edit it by hand only for a setting no command covers, then run openlatch restart to apply it: the daemon reads its configuration once, when it starts.

Where settings come from

The client reads each setting from the first source that sets it, in this order:

1. A flag on the command line.
2. An environment variable (OPENLATCH_*).
3. The configuration file, config.toml in the state directory: ~/.openlatch on macOS and Linux, %APPDATA%\openlatch on Windows.
4. The built-in default.

The proxy route is the one exception: it resolves key by key, and below the configuration file it also honours the standard https_proxy family of variables, then the operating system’s own proxy settings, before it goes direct.

The supervised daemon does not inherit your shell’s variables. Anything it needs, such as the platform address, openlatch init writes into config.toml so the daemon uses it too.

Environment variables

State and connection

Variable	What it sets	Default
OPENLATCH_DIR	The state directory: configuration, credential, logs and outbox	~/.openlatch on macOS and Linux, %APPDATA%\openlatch on Windows
OPENLATCH_PORT	The daemon’s port. Set, openlatch init uses exactly this port; unset, it looks for a free one from 7443 to 7543	7443
OPENLATCH_API_URL	The platform address the client sends events to and fetches policy from	https://app.openlatch.ai
OPENLATCH_API_KEY	The enrolment credential. openlatch init stores it in the operating system’s keychain, or in an encrypted file when no keychain is usable	—
OPENLATCH_SKIP_KEYRING	Treats the keychain as unavailable, so the environment variable wins	unset
OPENLATCH_LOG	Log level: error, warn, info, debug or trace	info

Proxy

Variable	What it sets	Default
OPENLATCH_PROXY	The proxy URL for every outbound request. It is the one setting that may carry a credential; openlatch init moves the password to the keychain instead of writing it to disk	unset
OPENLATCH_NO_PROXY	Extra destinations that skip the proxy. Loopback addresses always skip it	unset
OPENLATCH_PROXY_MODE	auto, manual or direct	auto
OPENLATCH_PROXY_AUTH	auto, none, basic or negotiate (Kerberos). NTLM is not supported	auto
OPENLATCH_PROXY_PAC_URL	An explicit proxy auto-config URL, used on macOS and Windows. Refused on Linux with OL-1225	unset
OPENLATCH_PROXY_SPN	The Kerberos service name of the proxy	HTTP/<proxy-host>
OPENLATCH_CA_BUNDLE	A PEM bundle added to the operating system’s trusted certificates, for a proxy that inspects TLS traffic	unset

Parts of the client

Variable	What it sets	Default
OPENLATCH_POLICY_ENABLED	Local policy evaluation. false turns enforcement off completely on this machine; it is not a Monitor mode (OL-1215)	true
OPENLATCH_MODEL_RELAY_ENABLED	The model relay, the local listener that records each agent’s model calls. The daemon points an agent at it only once a test request proves it reaches the provider	true
OPENLATCH_MODEL_RELAY_PORT	The model relay’s port	7600
OPENLATCH_INVENTORY_ENABLED	Watching agent configuration files (the configuration plane)	true
OPENLATCH_CLINE_PLUGIN_DELIVERY	Delivering the OpenLatch plugin to Cline.app and the VS Code Cline extension. The same as plugin_delivery in [cline]	true

Delivery to the platform

Variable	What it sets	Default
OPENLATCH_CLOUD_BATCH_MAX_EVENTS	Events sent per batch, from 1 to 100	50
OPENLATCH_CLOUD_BATCH_MAX_WAIT_MS	How long the first event of a batch waits before the batch is sent, in milliseconds	5000
OPENLATCH_CLOUD_OUTBOX_MAX_BYTES	The most unsent events the outbox holds, in bytes, before the oldest are dropped. 0 removes the cap	104857600
OPENLATCH_CLOUD_FALLBACK_MAX_BYTES	The most unreplayed events the fallback log holds, in bytes, before the oldest are skipped. It caps that window, not the file: during a long outage the file on disk keeps growing until the daemon replays it. Read by the daemon only; the hook keeps its own 50 MB limit. 0 removes the cap	52428800

Sending events to the platform cannot be turned off. To send them elsewhere, change OPENLATCH_API_URL.

Updates and telemetry

Variable	What it sets	Default
OPENLATCH_AUTO_UPDATE	Automatic updates: the daemon checks for a release regularly and installs it once no hook is running. true or 1 turns it on; any other value turns it off. The same as auto_update in [update]	true
OPENLATCH_UPDATE_CHECK	The version check at start-up. false or 0 turns it off. The same as check in [update]	true
OPENLATCH_NPM_REGISTRY	The registry openlatch update downloads from	https://registry.npmjs.org
OPENLATCH_TELEMETRY_DISABLED	1 turns usage telemetry off	unset
DO_NOT_TRACK	1 turns usage telemetry off, as in other tools that follow this convention	unset
OPENLATCH_CRASH_REPORTING	0, false, no or off stops crash reports, independently of usage telemetry	on

Automatic updates never run on CI runners.

Configuration file

config.toml in the state directory holds the settings the commands write, grouped in sections. The sections you are most likely to read or edit:

Section	Key	What it sets
[policy]	enabled	Local policy evaluation, as OPENLATCH_POLICY_ENABLED
[model_relay]	enabled	The model relay, as OPENLATCH_MODEL_RELAY_ENABLED. openlatch system model-relay enable and disable write it
[cline]	plugin_delivery	Delivering the OpenLatch plugin to Cline hosts
[update]	auto_update · check	Automatic updates and the start-up version check
[proxy]	see below	The route every outbound request takes

The [proxy] section

openlatch init finds the route on its own where it can and writes it here. openlatch system proxy set, discover and clear change it; prefer them to editing the file.

[proxy]
mode = "auto"
url = "http://proxy.corp:8080"
auth = "auto"
no_proxy = ".corp.example,10.0.0.0/8"
ca_bundle = "/etc/ssl/corp-root.pem"
allow_direct = true

Key	What it sets
mode	auto looks for a working route, manual uses exactly what is set and is never replaced, direct never uses a proxy
url	The proxy, as http://, https://, socks5:// or socks5h://. It never holds a username or password
username	The account to authenticate as. The password lives in the keychain, never in this file
auth	auto picks a scheme when the daemon starts; basic, negotiate and none are explicit
no_proxy	Extra destinations that skip the proxy, such as example.com, .example.com or 10.0.0.0/8
ca_bundle	A PEM bundle added to the trusted certificates, never a replacement for them
allow_direct	false refuses a direct connection when no proxy can be used (OL-1227)
spn	The Kerberos service name of the proxy
http1_only	Forces HTTP/1.1, for an inspecting proxy that mishandles HTTP/2
pac_url	An explicit proxy auto-config URL. Refused on Linux (OL-1225)

Run openlatch system proxy test after any change to check the route.

What the client writes into agent settings

While the model relay is on, the daemon points each detected agent’s model calls at it, and removes that wiring when you stop the daemon, switch the relay off or uninstall. A value you set yourself is never overwritten: openlatch doctor reports it instead (OL-RELAY-SETTINGS).

Agent	Where the wiring goes
Claude Code	Environment keys in its settings: the relay address, an install identifier, and loopback entries in NO_PROXY
Codex CLI	An openlatch provider entry in ~/.codex/config.toml
Cursor	The relay address in the IDE’s user settings, and a shell wrapper for the Cursor CLI that a new terminal picks up
Cline	One local relay endpoint per configured provider, in Cline’s own settings files

Wiring Claude Code to the model relay sets its ANTHROPIC_BASE_URL, which turns off Claude Code Remote Control while the relay is on. On a machine behind a proxy, also export NO_PROXY=127.0.0.1,localhost in the shell that starts Codex CLI, so its model calls reach the local relay rather than the corporate proxy.

Run openlatch system model-relay status to see which agents’ model calls go through the relay.