Environment variables

The Flowstate Agent reads its configuration from environment variables on Linux and Windows. The same names work whether they're set via shell env, /etc/flowstate.env (Linux), or the Windows registry under HKLM\SOFTWARE\Flowstate\Agent — the agent normalises them all.

macOS reads managed preferences, not env vars

The macOS NETransparentProxy agent reads its configuration from managed preferences (domain inc.flowstate.agent), delivered by an MDM configuration profile — not from the environment variables below. The key names differ (Tenant, ProxyUrl, UserEmail, UserToken, …). See macOS managed configuration for that table and the MDM deployment guide for delivery.

Precedence (highest wins):

1. Local env var — FLOWSTATE_LOG_LEVEL=debug set inline for a one-off flowstate proxy run invocation while debugging.
2. Per-platform managed config — /etc/flowstate.env (macOS / Linux), Windows registry. This is where flowstate install writes the values it received from the install flags / MDM.
3. Built-in defaults.

flowstate install writes /etc/flowstate.env (or the Windows registry) based on the --key, --user, and --host flags you pass. You typically don't need to set any of these by hand — the installer does it for you.

Required

Variable	Description
FLOWSTATE_API_KEY	The organisation token the agent uses, together with the user email, to authenticate to Flowstate. Issue it in Settings → AI → Cloud Proxy. On a managed Mac it arrives as the UserToken preference. The agent waits for it rather than starting unconfigured.
FLOWSTATE_USER_EMAIL	The email the agent authenticates as, and the attribution key in Flowstate. On macOS this is the managed-pref UserEmail.

Cloud proxy

Variable	Type	Default	Description
FLOWSTATE_ENDPOINT	URL	https://proxy.flowstate.inc	The cloud proxy origin the agent forwards captured exchanges to over HTTPS, authenticating as the device's user. Override for a regional EU endpoint, staging, or an on-prem mirror. Must be HTTPS. On macOS this is the managed-pref ProxyUrl.

Networking

Variable	Type	Default	Description
FLOWSTATE_UPSTREAM_PROXY	URL	unset	Corporate proxy for the agent's own outbound traffic (the connection to the cloud proxy, update downloads). Format: http://user:pass@proxy.example.com:8080. See corporate proxies.
FLOWSTATE_PROXY_PORT	int	47813	Local TCP port the agent's PAC daemon listens on for AI traffic. Change only if you have a conflict.
FLOWSTATE_PROXY_BIND	string	127.0.0.1	Bind address. Loopback by default; do not change unless you know exactly what you're doing.

Enforcement

Variable	Type	Default	Description
FLOWSTATE_ENFORCEMENT_MODE	enum	observe	observe (default — capture-only) or enforce (apply AI policy at request time). See enforcement. The same setting lives in Settings → AI → Agent Policy → Enforcement.

Diagnostics

Variable	Type	Default	Description
FLOWSTATE_LOG_LEVEL	enum	info	One of debug, info, warn, error.
FLOWSTATE_LOG_PATH	path	OS-specific	Override the log file location. macOS: /var/log/flowstate.proxy.log. Linux: stdout (journald). Windows: C:\ProgramData\Flowstate\logs\agent.log.

macOS managed configuration

The macOS agent does not read the environment variables above. It reads managed preferences from its domain inc.flowstate.agent, delivered by an MDM configuration profile (see the MDM deployment guide). Every key defaults to today's behaviour, so an empty or partial profile reproduces the current behaviour exactly.

Key	Type	Default	Purpose
Tenant	string	required	Tenant host, e.g. acme.flowstate.inc. Base for the token and allowlist URLs.
ProxyUrl	string	https://proxy.flowstate.inc	Cloud proxy endpoint. Override only for a regional or dedicated endpoint.
UserEmail	string	required	The email the agent authenticates as — the attribution key. In production this is the MDM $EMAIL placeholder, expanded per device.
UserToken	string (secret)	required	The organisation token the agent authenticates with (together with UserEmail). Promoted into the Keychain on first read.
HiddenMode	bool	false	Hide the menubar icon.
UserCannotDisable	bool	false	Always-on lockdown: hidden UI, no disable/quit affordance, enforced keep-alive. Engages only when delivered as a forced MDM value.
AutoUpdate	bool	true	Enable silent background auto-update. false opts the fleet out.
UpdateChannel	string	beta	Update channel the agent pulls from.

Per-platform notes

macOS — Configuration is delivered as an MDM managed-preferences payload (domain inc.flowstate.agent), not an env file; see the table above and the MDM deployment guide. A forced profile value is required to engage UserCannotDisable; a value written locally by the installer stays overridable for debugging.

Linux — Same /etc/flowstate.env file, loaded by systemd via EnvironmentFile=. Standard KEY=value syntax, no quotes needed for simple strings. Reload with sudo systemctl restart flowstate-agent.

Windows — Values live under HKLM\SOFTWARE\Flowstate\Agent. The MSI

• flowstate install write them; Settings Catalog / GPO can overwrite them. Names are identical to the env-var names on the other platforms (no CamelCasing). The service reads (in order): machine env → registry → defaults. Boolean values are REG_DWORD 1/0; everything else is REG_SZ.

Deprecated / removed

These were present in earlier builds and have been removed. The agent ignores them if it sees them — no error, no warning. Most have a direct replacement in the table above.

Variable	Status	Replacement
FLOWSTATE_OTLP_KEY	renamed	Use FLOWSTATE_API_KEY (still accepted as an alias — see telemetry keys).
FLOWSTATE_USER	renamed	Use FLOWSTATE_USER_EMAIL (still accepted as an alias).
FLOWSTATE_MODE	removed	There is one forwarding path — the cloud proxy. No mode selector.
FLOWSTATE_CLOUD_PROXY	renamed	Use FLOWSTATE_ENDPOINT.
FLOWSTATE_TELEMETRY_KEY	replaced	Use FLOWSTATE_API_KEY (the organisation key — see telemetry keys).
FLOWSTATE_OTLP_ENDPOINT	replaced	Use FLOWSTATE_ENDPOINT.
FLOWSTATE_CLOUD_PROXY_EMAIL	replaced	Use FLOWSTATE_USER_EMAIL.
FLOWSTATE_CLOUD_PROXY_KEY	replaced	The organisation key supplies both tenant routing and authentication, so a separate value is no longer needed. Set FLOWSTATE_API_KEY instead.
FLOWSTATE_CAPTURE_PROMPTS	removed	Prompt capture is per-tool and configured by flowstate install's per-tool config writer. Pass --prompts at install time to opt in.
FLOWSTATE_UPDATE_*	removed	macOS auto-updates silently; control it with the AutoUpdate / UpdateChannel managed-pref keys. See auto-updates.
FLOWSTATE_REDACT_BODIES	removed	Not a posture under the current design.
FLOWSTATE_REDACT_HEADERS	removed	Headers are always forwarded — they're how the cloud proxy attributes calls to users.