Configuration reference
Generated by scripts/docgen/config-ref. Do not edit by hand — run make docs-regen after changing internal/config/config.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.
| 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. |
[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". |
[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. |
[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 risk-increasing (opening/adding/flipping) equity/ETF order notional before broker WhatIf; reduce-only orders are exempt, bounded by the position itself; default 10000 in account currency. |
[trading] | max_option_contracts | int | MaxOptionContracts caps risk-increasing single-leg option quantity; reduce-only orders are exempt, bounded by the position itself; default 5. |
[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. |
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). |