Configuration reference

Generated by scripts/docgen/config-ref. Do not edit by hand — run make docs-regen after changing internal/config/config.go, internal/daemon/protection_policy.go, internal/daemon/opportunity_policy.go or adding/removing a // docgen:env comment.

TOML config

Config file is loaded from $IBKR_CONFIG, else $XDG_CONFIG_HOME/ibkr/config.toml, else $HOME/.config/ibkr/config.toml. Every field is optional; absent fields take their documented default. Unknown keys fail the load with a targeted error. Note: defining any [scans.<name>] preset replaces the built-in preset set — the scans table is replace-not-merge.

Section	Field	Type	Description
`[auto_trade]`	`fast_path_enabled`	`*bool`	FastPathEnabled allows manual proposal preview/submit to use the immediate revalidation path; default true so paper protection stops remain usable.
`[auto_trade]`	`hot_reload`	`*bool`	HotReload controls whether policy changes are reloaded while the daemon runs; default true.
`[auto_trade]`	`policy_file`	`string`	PolicyFile points to the local protection-policy TOML; default ~/.config/ibkr/policies/protection-policy.toml.
`[auto_trade]`	`proposal_cadence`	`duration`	ProposalCadence controls how often the daemon refreshes protection proposals; default 30s.
`[auto_trade]`	`proposals_enabled`	`*bool`	ProposalsEnabled controls whether the daemon may produce advisory protection proposals; default true, and proposals are not broker orders unless separately submitted by an explicitly enabled trading path — the `[auto_trade]` section name is historical: nothing auto-trades, and the policy's auto_submit stays false.
`[auto_trade]`	`reload_interval`	`duration`	ReloadInterval controls how often the daemon checks policy-file changes; default 30s.
`[daemon]`	`idle_timeout`	`duration`	IdleTimeout is how long the auto-spawned daemon stays alive between CLI calls (default 15m, accepts any Go duration string like "1h" or "0s"); set "0s" to disable idle-shutdown when running long cold-start jobs such as the first breadth fan-out under `ibkr daemon --foreground`.
`[daemon]`	`log_level`	`string`	LogLevel is the daemon's log verbosity — one of "debug", "info" (default), "warn", or "error".
`[flex]`	`enabled`	`bool`	Enabled turns the daily Flex statement fetch on; default false.
`[flex]`	`query_id`	`string`	QueryID is the IBKR Flex query id to fetch (create the query in Account Management with cash transactions, transfers, and equity summary sections); required when enabled.
`[flex]`	`token_path`	`string`	TokenPath points to a file holding only the Flex Web Service token; default ~/.config/ibkr/flex-token (mode 0600).
`[gateway]`	`account`	`string`	Account pins the IBKR account ID like "U1234567"; empty (default) defers to the gateway's managedAccounts list — fine for single-account logins, required disambiguator when the login carries multiple accounts.
`[gateway]`	`breadth_client_id`	`*int`	BreadthClientID is the IBKR clientID used by the dedicated historical-bar connector that backs the SPX breadth refresh.
`[gateway]`	`client_id`	`*int`	ClientID pins the IBKR API clientID for the primary connection (default 15); collisions are treated as a stale-client/operator issue and are not auto-walked to neighboring reserved IDs.
`[gateway]`	`host`	`string`	Host pins the IB Gateway / TWS host; empty (the default) defers to auto-discovery on loopback (127.0.0.1), any non-empty value skips probing.
`[gateway]`	`port`	`*int`	Port pins the IB Gateway / TWS API port (typically 4001/4002 for IB Gateway live/paper, 7496/7497 for TWS live/paper); absent (nil) defers to port-probing during discovery.
`[gateway]`	`tls`	`*bool`	TLS pins TLS mode for the API socket: absent (nil) auto-tries plain first then TLS, `true` forces TLS-only with no plain fallback, `false` forces plain — setting the field disables fallback in either direction.
`[opportunities]`	`enabled`	`*bool`	Enabled controls whether the daemon may produce advisory opportunities; default true, and opportunities are not broker writes unless separately submitted by an explicitly enabled trading path.
`[opportunities]`	`hot_reload`	`*bool`	HotReload controls whether opportunity policy changes are reloaded while the daemon runs; default true.
`[opportunities]`	`policy_file`	`string`	PolicyFile points to the local opportunity-policy TOML; default ~/.config/ibkr/policies/opportunity-policy.toml.
`[opportunities]`	`refresh_cadence`	`duration`	RefreshCadence controls how often the daemon refreshes opportunities; default 2m.
`[opportunities]`	`reload_interval`	`duration`	ReloadInterval controls how often the daemon checks the opportunity policy file for changes; default 30s.
`[rulebook]`	`terminal_evidence_file`	`string`	TerminalEvidenceFile points to an optional JSON document of reviewed, exact-contract terminal/non-reporting issuer evidence for rules 6-8.
`[scans.<name>]`	`exchange`	`string`	Exchange is the IBKR scanner locationCode, such as STK.US.MAJOR or STK.NASDAQ.
`[scans.<name>]`	`instrument`	`string`	Instrument is the IBKR scanner instrument token, such as STK for US stocks or STOCK.EU for European stocks; empty defaults to STK.
`[scans.<name>]`	`limit`	`int`	Limit caps returned rows for this preset.
`[scans.<name>]`	`timeout`	`duration`	Timeout is the per-preset scan timeout; <=0 falls back to the daemon default (20s).
`[scans.<name>]`	`type`	`string`	Type is the IBKR scanner code, such as TOP_PERC_GAIN; dump your gateway's catalog with `ibkr scan params`.
`[spx]`	`members_auto_refresh`	`*bool`	MembersAutoRefresh controls whether the daemon refreshes the S&P 500 constituent list from Wikipedia daily at 02:30 ET (default true; set false to pin the embedded baseline) — overridden symmetrically by the `IBKR_SPX_MEMBERS_AUTO_REFRESH` env var (`1` force-on, `0` force-off).
`[trading]`	`allow_option_sell_to_open`	`bool`	AllowOptionSellToOpen permits option sell-to-open previews when true.
`[trading]`	`allow_stock_short`	`bool`	AllowStockShort permits stock short/opening flip previews when true.
`[trading]`	`max_notional`	`float64`	MaxNotional caps every equity/ETF order before broker WhatIf; apparent close/reduce orders are not exempt because this client cannot prove that a manual TWS order has not already consumed the exit capacity.
`[trading]`	`max_option_contracts`	`int`	MaxOptionContracts caps every single-leg option order; apparent close/reduce orders are not exempt because account-global working-order authority is incomplete.
`[trading]`	`mode`	`string`	Mode selects the local order-entry state: "disabled" (default), "paper", or "live".
`[trading]`	`paper_smoke_max_age`	`duration`	PaperSmokeMaxAge is how long a paper trading smoke remains acceptable for live enablement.

Protection policy file

Loaded from the path in [auto_trade].policy_file (default ~/.config/ibkr/policies/protection-policy.toml). No file is required or shipped: when absent, the daemon runs the embedded default — print it with ibkr policy default protection. Edits apply only when policy_version is bumped (an edited file at an unchanged version reports drift), and unknown keys fail the load. This policy shapes advisory protection proposals only; proposals never place broker orders by themselves.

Section	Field	Type	Description
(top level)	`kind`	`string`	Kind must be "ibkr.protection_policy"; any other value fails the load.
(top level)	`policy_id`	`string`	PolicyID is the required identity string for this policy (embedded default "protection-mvp").
(top level)	`policy_version`	`int`	PolicyVersion is the monotonic policy revision; bump it to make the daemon adopt file edits — an edited file at an unchanged version reports drift instead.
(top level)	`profile`	`string`	Profile is a human-readable label for the parameter set (embedded default "theta-priority-mvp"); falls back to policy_id when empty.
(top level)	`schema_version`	`int`	SchemaVersion is the policy schema revision; only 1 is supported.
`[authority]`	`auto_submit`	`bool`	AutoSubmit would let proposals submit themselves; must be false — proposals are advisory and every broker write stays behind the gated order path.
`[authority]`	`close_reduce_only`	`bool`	CloseReduceOnly restricts proposals to reducing or closing existing positions; must be true in the MVP schema.
`[buckets.risk_reduction]`	`enabled`	`bool`	Enabled turns the single-name concentration-reduction bucket on (default true).
`[buckets.risk_reduction]`	`max_order_notional`	`float64`	MaxOrderNotional caps the notional of a single generated reduction order (default 10000).
`[buckets.risk_reduction]`	`single_name_target_pct_nlv`	`float64`	SingleNameTargetPctNLV is the target ceiling for one name's exposure as a percent of net liquidation value (default 25).
`[buckets.theta_hygiene]`	`enabled`	`bool`	Enabled turns the near-dated time-decay hygiene bucket on (default true).
`[buckets.theta_hygiene]`	`max_dte`	`int`	MaxDTE only considers options expiring within this many days (default 21).
`[buckets.theta_hygiene]`	`max_spread_pct_of_mid`	`float64`	MaxSpreadPctOfMid skips quotes whose bid/ask spread exceeds this percent of mid — too wide to act on (default 25).
`[buckets.theta_hygiene]`	`min_abs_theta_per_day`	`float64`	MinAbsThetaPerDay is a dust floor that cheaply skips trivially small positions before the extrinsic decomposition (default 5.0 per day).
`[buckets.theta_hygiene]`	`min_extrinsic_pct_of_mark`	`float64`	MinExtrinsicPctOfMark is the materiality gate: below this percent of mark the option is intrinsic-dominated and a theta-saving close is suppressed (default 40).
`[buckets.trailing_stop]`	`enabled`	`bool`	Enabled turns the trailing-stop bucket on (default true).
`[buckets.trailing_stop]`	`tif`	`string`	TIF applies to every trailing-stop proposal in this bucket: DAY or GTC, empty means DAY.
`[buckets.trailing_stop.options]`	`allow_short_profit_trail`	`bool`	AllowShortProfitTrail permits trailing profit stops on short option positions (default false).
`[buckets.trailing_stop.options]`	`default_pct`	`float64`	DefaultPct is the standard trailing distance in percent (default 30).
`[buckets.trailing_stop.options]`	`enabled`	`bool`	Enabled turns trailing-stop proposals for option positions on (default false).
`[buckets.trailing_stop.options]`	`limit_offset_abs`	`float64`	LimitOffsetAbs is the absolute limit offset for the stop; required positive when order_type is TRAIL LIMIT (default 0.05).
`[buckets.trailing_stop.options]`	`max_pct`	`float64`	MaxPct is the upper bound on the trailing distance (default 50).
`[buckets.trailing_stop.options]`	`max_spread_pct_of_mid`	`float64`	MaxSpreadPctOfMid skips option quotes wider than this percent of mid (default 25).
`[buckets.trailing_stop.options]`	`min_pct`	`float64`	MinPct is the lower bound on the trailing distance (default 20).
`[buckets.trailing_stop.options]`	`min_trail_abs`	`float64`	MinTrailAbs is the minimum absolute trailing amount in dollars (default 0.10).
`[buckets.trailing_stop.options]`	`order_type`	`string`	OrderType is TRAIL or TRAIL LIMIT (default TRAIL LIMIT).
`[buckets.trailing_stop.options]`	`spread_multiple`	`float64`	SpreadMultiple sizes the trailing amount as a multiple of the observed spread (default 2).
`[buckets.trailing_stop.stock_etf]`	`default_pct`	`float64`	DefaultPct is the standard trailing distance in percent (default 8).
`[buckets.trailing_stop.stock_etf]`	`enabled`	`bool`	Enabled turns trailing-stop proposals for stock/ETF positions on (default true).
`[buckets.trailing_stop.stock_etf]`	`fallback_pct`	`float64`	FallbackPct is the trailing distance used when the default cannot be applied; must lie within [min_pct, max_pct] (default 10).
`[buckets.trailing_stop.stock_etf]`	`limit_offset_abs`	`float64`	LimitOffsetAbs is the absolute limit offset for the stop; required positive when order_type is TRAIL LIMIT.
`[buckets.trailing_stop.stock_etf]`	`max_pct`	`float64`	MaxPct is the upper bound on the trailing distance (default 15).
`[buckets.trailing_stop.stock_etf]`	`max_spread_pct_of_mid`	`float64`	MaxSpreadPctOfMid skips stock/ETF quotes wider than this percent of mid (default 2).
`[buckets.trailing_stop.stock_etf]`	`min_pct`	`float64`	MinPct is the lower bound on the trailing distance (default 2).
`[buckets.trailing_stop.stock_etf]`	`order_type`	`string`	OrderType is TRAIL or TRAIL LIMIT (default TRAIL).

Opportunity policy file

Loaded from the path in [opportunities].policy_file (default ~/.config/ibkr/policies/opportunity-policy.toml). Same envelope and reload discipline as the protection policy; print the embedded default with ibkr policy default opportunity. Governs advisory option-exercise opportunity detection only.

Section	Field	Type	Description
(top level)	`kind`	`string`	Kind must be "ibkr.opportunity_policy"; any other value fails the load.
(top level)	`policy_id`	`string`	PolicyID is the required identity string for this policy (embedded default "opportunity-option-exercise-mvp").
(top level)	`policy_version`	`int`	PolicyVersion is the monotonic policy revision; bump it to make the daemon adopt file edits — an edited file at an unchanged version reports drift instead.
(top level)	`profile`	`string`	Profile is a human-readable label for the parameter set (embedded default "conservative-exercise-mvp"); falls back to policy_id when empty.
(top level)	`schema_version`	`int`	SchemaVersion is the policy schema revision; only 1 is supported.
`[authority]`	`auto_submit`	`bool`	AutoSubmit would let exercise opportunities submit themselves; must be false — opportunities are advisory and every broker write stays behind the gated order path.
`[authority]`	`exercise_reduce_only`	`bool`	ExerciseReduceOnly is retained for schema compatibility.
`[buckets.option_exercise]`	`allow_no_option_bid`	`bool`	AllowNoOptionBid is retained for schema compatibility.
`[buckets.option_exercise]`	`enabled`	`bool`	Enabled turns the early-exercise opportunity detector on (default true).
`[buckets.option_exercise]`	`max_quote_age`	`string`	MaxQuoteAge is the oldest quote still considered fresh, as a Go duration string (default "30s").
`[buckets.option_exercise]`	`min_gain_pct_intrinsic`	`float64`	MinGainPctIntrinsic is the minimum gain as a percent of intrinsic value (default 0.5).
`[buckets.option_exercise]`	`min_total_gain`	`float64`	MinTotalGain is the minimum total dollar gain required to flag an exercise opportunity (default 25).
`[buckets.option_exercise]`	`require_american_style`	`bool`	RequireAmericanStyle limits detection to American-style options, the only style that can be exercised early (default true).
`[buckets.option_exercise]`	`require_rth`	`bool`	RequireRTH only flags opportunities during regular trading hours (default true).

Runtime platform settings

Daemon-owned preferences persisted in $XDG_STATE_HOME/ibkr/daemon.db and changed at runtime without a restart. Feature preferences may be changed via ibkr settings set <key>=<value>, the SPA Settings tab, or PATCH /api/settings. Setting a key to null clears the runtime override, and every response field carries access/source/reason metadata. trading.freeze and trading-limit keys require ibkr settings set from an interactive human terminal; missing, agent, and paired-device origins are rejected in disabled, paper, and live modes. Trading-limit keys additionally require an experimental trading build with [trading].mode set. Ownership and semantics: internal-docs/design/platform-settings.md.

Key	Value	Class	Description
`features.purge_restore.enabled`	`true/false/null`	runtime	Controls the purge/restore workflow/read surface while purge status stays readable; true does not authorize preview or broker submission, which remains unavailable until exact per-leg portfolio and account-global working-order authority exists (default true).
`features.stock_protection.enabled`	`true/false/null`	runtime	Allows stock/ETF protection proposal actions; false blocks them with a stock_protection_disabled blocker while proposal snapshots stay readable (default true).
`features.rulebook.enabled`	`true/false/null`	runtime	Turns the advisory daily trading-rulebook checklist on; false hides the SPA card, empties rules.snapshot, and stops advisory rule_* preview warnings — it can never affect broker-write gating (default true).
`features.rulebook.earnings_overrides.<SYMBOL>`	`YYYY-MM-DD[Tamc/Tbmo]/null`	runtime	Manual SYMBOL → YYYY-MM-DD (optional Tamc/Tbmo suffix) earnings pins, authoritative over fetched dates for rules 6-8; patches merge per symbol.
`trading.freeze`	`true/false/null`	runtime	Runtime trading brake: true blocks every new broker write while cancels stay allowed; human-only by policy, and the write origin is audited (default false).
`trading.limits.max_notional`	`number/null`	trading-limit	Runtime override of [trading].max_notional, the notional cap for every equity/ETF order including apparent exits; null falls back to the TOML value.
`trading.limits.max_option_contracts`	`integer/null`	trading-limit	Runtime override of [trading].max_option_contracts, the quantity cap for every single-leg option order including apparent exits; null falls back to the TOML value.
`trading.limits.allow_stock_short`	`true/false/null`	trading-limit	Runtime override of [trading].allow_stock_short; null falls back to the TOML value.
`trading.limits.allow_option_sell_to_open`	`true/false/null`	trading-limit	Runtime override of [trading].allow_option_sell_to_open; null falls back to the TOML value.
`regime.journal.enabled`	`true/false/null`	runtime	Turns forward regime decision-event collection in daemon.db on (default true).
`canary.journal.enabled`	`true/false/null`	runtime	Turns forward canary decision-event collection in daemon.db on, mirroring regime.journal.enabled (default true).

Environment variables

Read at process startup. Override TOML config where applicable; see the per-var description for precedence rules.

Variable	Description
`IBKR_AGENT_CONTEXT`	When set (any value), broker writes from this process are classified as agent-origin for audit and origin-specific policy. The variable can only restrict: no environment variable can claim a human origin.
`IBKR_APP_ADDR`	HTTP listen address for `ibkr app`. Defaults to `0.0.0.0:8765` so a paired phone on the LAN can reach the app.
`IBKR_APP_PUBLIC_URL`	Public trusted HTTPS base URL for the `ibkr app` PWA/relay origin. Defaults to a LAN URL for wildcard listen addresses, falling back to loopback when no LAN address is available.
`IBKR_APP_REMOTE`	Enable the outbound Cloudflare Worker relay for `ibkr app`, making pairing URLs reachable through the public relay origin.
`IBKR_APP_REMOTE_URL`	Cloudflare Worker relay base URL for `ibkr app --remote`. Defaults to `https://remote.osauer.dev`.
`IBKR_APP_STATE_DIR`	Directory for `ibkr app` paired devices, alert settings, VAPID keys, and alert history. Defaults to `$XDG_STATE_HOME/ibkr/app` or `$HOME/.local/state/ibkr/app`.
`IBKR_COLOR`	Force terminal colour on (`always`), off (`never`); any other value defers to NO_COLOR + TTY detection.
`IBKR_CONFIG`	Override the config.toml path. Defaults to `$XDG_CONFIG_HOME/ibkr/config.toml` or `$HOME/.config/ibkr/config.toml`.
`IBKR_INSTALL_DIR`	Override the install directory for `ibkr update`. Defaults to `$HOME/.local/bin`. Phase-2 release pipeline uses this to sandbox dog-food installs to a tmp dir.
`IBKR_LOG`	Override the daemon log file path. Defaults to `$HOME/.local/state/ibkr/ibkr-daemon.log`.
`IBKR_PACKET_LOG_TEMPLATE`	Template path for raw IBKR wire-packet logs. Trailing `/` treats as directory; `%d` placeholder gets the gateway client ID. Unset disables wire logging.
`IBKR_SOCKET`	Override the daemon IPC socket path. Defaults to `$XDG_RUNTIME_DIR/ibkr/ibkr.sock` or `$HOME/.cache/ibkr/ibkr.sock`.
`IBKR_SPX_MEMBERS_AUTO_REFRESH`	Symmetric override of `[spx] members_auto_refresh`. `1` force-enables, `0` force-disables, unset / other defers to TOML.
`IBKR_WIRE_INTERCEPTOR`	Enable the account-sensitive decoded wire-frame recorder. Unset or false disables it.
`IBKR_WIRE_LOG_PATH`	Append decoded account-sensitive wire frames as JSONL at this path. Unset keeps frames in memory only.
`IBKR_WIRE_RING_SIZE`	Maximum decoded wire frames retained in memory when the interceptor is enabled; default 256.
`NO_COLOR`	Standard https://no-color.org/ override. Any non-empty value disables colour regardless of IBKR_COLOR (unless IBKR_COLOR=always).