Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / configuration-and-provider-settings

Configuration and provider settings

Strix turns environment values and a small JSON file into one validated settings object. These settings select the model route, provide access data, shape model requests, and set limits for each model turn.

Configuration sources and validation

The configuration system resolves process environment values, the active JSON file, and field defaults into one settings object. The normal file is ~/…/cli-config.json. A command-line config path replaces it for the current process. The file stores values inside an env object so the same names work in both places. load_settings() caches the resolved object, while a new config override clears that cache. Settings groups values for the main model, finding deduplication, runtime, context, telemetry, integrations, and viewer behavior. Model requests can also receive user-defined extra headers and body fields through the model settings.

model, api_key, and api_base form one provider connection. If the shell changes one of these values, Strix drops the stored values for the linked connection instead of combining old and new connection data. This prevents a model from silently using a key or endpoint that belongs to another provider.

References: strix/…/loader.py• L26-60 strix/…/loader.py• L140-168 strix/…/settings.py• L229-238

Configuration precedence

Environment values win even when the file uses another accepted alias for the same field. A missing, malformed, or wrongly shaped file does not replace the environment or defaults. When Strix persists settings, it writes only environment values that are currently set and uses a restricted file mode. It does not serialize every default or resolved value.

Stored provider connection values are treated as a unit. A changed environment value causes the stored model, key, and base URL to be removed before the file is read or written. An unset environment value leaves the existing file value in place, while an empty environment value clears that field during persistence.

References: strix/…/loader.py• L63-90 strix/…/loader.py• L106-154 strix/…/settings.py• L29-56

Validation boundaries

Pydantic validates types and allowed ranges before consumers use the settings. Reasoning effort accepts a fixed set of names and normalizes those names to lower case. API type accepts responses or chat_completions. Preflight and stream limits reject invalid values. Context limits and the per-turn tool-call limit also reject invalid values. The model preflight timeout must be at least one second. The first-event, stream-idle, whole-stream, cache-block, and tool-call limits cannot be negative or zero where a positive value is required. A missing model is a startup error for a normal API-key route. A chatgpt/<model> route instead requires a valid ChatGPT subscription sign-in.

References: strix/…/settings.py• L11-14 strix/…/settings.py• L29-114 strix/…/settings.py• L143-160 strix/…/codex.py• L394-405

Model and provider selection

The selected model name controls both the provider path and the request shape. A scan may pass a model directly, which takes priority over STRIX_LLM; otherwise Strix uses the configured model. The provider keeps known prefixes for native OpenAI routes and sends other provider names through the compatible provider layer. The SDK-native API path is selected by an explicit API type when one is set. Otherwise Strix uses the model catalog to choose Responses when the model lists that endpoint and uses Chat Completions for other models. A secondary model such as the report-deduplication judge can bind its own API key and base URL, so it does not reuse the main model's process-wide provider credentials.

The following flow shows how configuration becomes a provider request.

flowchart LR
    A[Environment or config file] --> B[Validated settings]
    B --> C[Resolved model name and API type]
    C --> D{Model route}
    D -->|OpenAI or compatible API| E[SDK or LiteLLM provider]
    D -->|chatgpt prefix| F[Codex subscription client]
    E --> G[Guarded model turn]
    F --> G
    G --> H[Provider request]

Request controls

The main LLM settings become per-request model settings at scan start. They affect the model turn without changing the scan’s tool set or task.

SettingProvider-facing effect
STRIX_API_TYPE or STRIX_FORCE_APIForces the Responses or Chat Completions request path when the selected route supports both.
STRIX_REASONING_EFFORTRequests the chosen reasoning level when the model route supports reasoning. none leaves reasoning unset.
LLM_TIMEOUTSets the request timeout.
LLM_PREFLIGHT_TIMEOUTBounds the startup model check separately from normal model turns.
LLM_STREAM_FIRST_EVENT_TIMEOUTFails a stream when its first event does not arrive within the configured time. A value of 0 disables this bound.
LLM_STREAM_IDLE_TIMEOUTFails a streamed turn when no event arrives within the configured gap. A value of 0 disables this idle check.
LLM_STREAM_TOTAL_TIMEOUTFails a streamed turn when it exceeds the configured whole-stream time. A value of 0 disables this bound.
LLM_DISABLE_STREAMINGUses one completed request for normal compatible routes that do not support reliable streams. It does not change the always-streamed Codex route.
STRIX_PROMPT_CACHE and STRIX_CACHE_BLOCK_TOKENSEnable prompt-cache request fields when supported and set the token block size used to shape cacheable prompt content.
STRIX_FORCE_REQUIRED_TOOL_CHOICERequests a required tool choice only when the selected route accepts that mode.
STRIX_PARALLEL_TOOL_CALLSAllows the provider request to opt in to parallel tool calls when the selected route supports that mode.
LLM_EXTRA_HEADERSAdds user headers to requests on the LiteLLM and native OpenAI paths.
LLM_EXTRA_BODYAdds user request fields to model calls that support extra body data.
STRIX_OPENROUTER_STICKY_SESSIONSAdds a stable per-agent OpenRouter session ID when enabled, so related calls can remain on one upstream provider and retain its prompt cache. The default is disabled.

The scan passes these controls to the model provider after it resolves the final model. Provider-specific checks can change tool schema strictness and the tool protocol, so one request shape is not forced onto every provider.

References: strix/…/settings.py• L29-114 strix/…/models.py• L249-268 strix/…/models.py• L370-375 strix/…/models.py• L602-656 strix/…/models.py• L713-740

Provider defaults and attribution

Strix applies the configured key and base URL to the SDK and compatible provider layer. It disables model tracing, sends extra headers on both routing paths, and adds app attribution headers for Vercel AI Gateway models. OpenRouter models receive the same app headers plus OpenRouter category attribution. Provider cost callbacks remain active so usage can be accounted for. OpenRouter calls can optionally use a stable session per agent when STRIX_OPENROUTER_STICKY_SESSIONS is enabled; otherwise Strix does not add a session ID. These defaults prepare the client before the scan or model preflight sends a request.

A provider created for a dedicated secondary model keeps that model's key and base URL on its own route rather than changing the main model's defaults. This lets a secondary request use a different account or endpoint without changing the active scan.

References: strix/…/models.py• L530-600 strix/…/models.py• L693-717 strix/…/models.py• L777-876

Codex subscription settings

The chatgpt/<model> model prefix selects the ChatGPT subscription route instead of an API-key route. The access record is kept apart from the normal config file in ~/…/subscription-auth.json. It contains OAuth data and the account identity needed by the backend. The client refreshes near-expiry access tokens under a process and cross-process guard. It stamps a fresh bearer token and account header onto each request, which lets a long scan continue across token expiry.

The subscription client checks for a usable sign-in before it starts. A missing or invalid record therefore fails during model setup rather than after the scan has begun.

References: strix/…/codex.py• L54-85 strix/…/codex.py• L106-127 strix/…/codex.py• L318-405

Codex request behavior

The ChatGPT backend requires streamed Responses requests. Strix enforces streaming even when the caller asks for a complete response, then collects the stream into the result expected by the scan loop. It also sends store=false and encrypted reasoning content. Configured reasoning levels are mapped to levels accepted by this backend, so minimal maps to low and xhigh or max map to high. A content-guardrail rejection is terminal for that model and is not treated as a transient retry.

References: strix/…/models.py• L85-160 strix/…/models.py• L602-623 strix/…/codex.py• L130-160

Tool-call identity and turn limits

The model layer protects the conversation before it gives model output to the run loop. Some providers restart tool-call numbering on every turn, which can create duplicate IDs in one conversation. Other providers omit IDs or return empty IDs. Strix repairs duplicate and blank IDs, keeps each new turn’s replacements stable across streamed events, repairs malformed tool arguments before the history is reused, and preserves the pairing between a tool call and its result.

The turn limit protects the scan from one response that queues an unsafe number of tool calls. Stream bounds protect it from a provider that never sends its first event, goes silent between events, or does not finish within the whole-stream limit.

sequenceDiagram
    participant M as Model provider
    participant G as Turn guard
    participant R as Scan run loop
    M->>G: Stream response with tool calls
    G->>G: Enforce first-event, idle, and total bounds
    G->>G: Repair blank and duplicate IDs
    G->>G: Repair malformed arguments
    G->>G: Keep up to configured calls
    G-->>R: Valid events and completed response
    R->>M: Tool results on the next turn

Tool-call limit semantics

LLM_MAX_TOOL_CALLS_PER_TURN counts tool calls in one assistant response. The default keeps at most 32 calls. A value above zero keeps the first calls up to that value and drops later calls from both streamed events and the completed response. A value of zero disables this limit. Dropped calls are logged so an operator can see that the model response was shortened.

References: strix/…/settings.py• L93-108 strix/…/models.py• L249-389

Provider failure handling

Provider choice also affects how Strix interprets failures. Normal model calls use a retry policy for provider-suggested failures, network errors, and selected server or rate-limit responses. A stream that misses its first event, exceeds its idle gap, or exceeds its total time fails through the timeout path so the existing retry path can replay the turn. Codex content-guardrail errors are excluded because repeating the same request does not clear the block.

References: strix/…/models.py• L75-83 strix/…/models.py• L420-479 strix/…/models.py• L687-700

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep every accepted environment alias aligned between Settings fields, JSON-file mapping, and persistence. A mismatch can make a saved value appear to load while an environment value silently wins.
  • Keep the linked LLM connection rule aligned between loading and persistence. Otherwise an updated model can retain an old key or endpoint.
  • Keep chatgpt/ model detection aligned across environment validation, provider construction, and auth-mode reporting. A mismatch can send a subscription model down the API-key path.
  • When changing model request controls, update both the normal request builder and the Codex-specific request rules. The Codex backend has stricter stream and reasoning requirements.
  • When changing API route selection, keep the explicit API type, model catalog lookup, and provider capabilities aligned. Otherwise a model can receive a request protocol that its endpoint does not support.
  • When changing stream limits, keep first-event, idle, and total timeout values aligned between settings validation, the turn guard, and the non-streaming wrapper. Otherwise a disabled or bounded setting can be applied to the wrong request mode.
  • When changing tool-call identity or argument handling, preserve the same decision across history, streamed item events, and the terminal response. Blank or placeholder IDs need a stable per-output replacement, malformed arguments need a valid replay form, and tool results must remain paired with their calls.
  • When adding a provider route, review its tool schema, reasoning, prompt-cache, header, and authentication support instead of assuming the OpenAI route applies.
  • When changing secondary-model credentials, keep the dedicated provider route separate from the main model's process-wide defaults. Otherwise a dedupe request can use the wrong endpoint or credentials.
  • When changing STRIX_API_TYPE or LLM_EXTRA_HEADERS, keep the SDK-native and LiteLLM paths aligned. Otherwise the selected route can ignore the requested API mode or required header.
  • When changing provider attribution or STRIX_OPENROUTER_STICKY_SESSIONS, keep model detection, header cleanup, and request transformation aligned. Otherwise a route can receive stale attribution or unexpected upstream pinning.
  • When changing LLM_EXTRA_BODY or DEDUPE_LLM_EXTRA_BODY, keep the accepted field shape aligned with the request builders for the main and secondary model paths. Otherwise a valid setting can be loaded but never reach the intended provider.
  • When changing STRIX_PARALLEL_TOOL_CALLS, keep the setting aligned with provider capability checks and tool-call result handling. Otherwise a provider can receive an unsupported mode or the run loop can process calls with the wrong assumptions.

Important failure modes

TriggerConsequenceGuard
No model is set for a normal routeThe scan stops before the first model requestEnvironment validation and runner startup require a resolved model
chatgpt/<model> is used without a valid OAuth recordModel setup fails because no subscription token is availableSign in with the ChatGPT auth flow before the scan
The model catalog does not list the selected API endpoint and no explicit API type is setThe SDK can send the model through an incompatible request pathRoute selection uses the catalog and allows an explicit API type override
A provider omits or reuses tool-call IDsStrict providers reject the replayed conversationThe turn guard assigns stable replacements for blank IDs and rewrites collisions while preserving call-result pairing
A tool call has malformed arguments and the history replays the raw valueThe next provider request can fail schema or JSON validationThe turn guard repairs arguments into a valid JSON object before replay
One response emits more calls than the configured limitThe run loop would process an excessive queueThe turn limiter keeps only the allowed prefix
A streamed provider misses its first event, goes silent, or runs past the whole-stream boundThe turn can hang or consume the scan's time budgetThe first-event, idle, and total stream timeouts abort the turn so retry can run
Codex blocks content through its cyber-risk guardrailRepeating the same request continues to failStrix reports a terminal guardrail error and requires a different model or prompt
A dedicated secondary model inherits the main model's endpoint settingsA dedupe request can fail or use the wrong provider accountThe secondary provider binds its own key and base URL when configured
The shell changes one linked provider value while old values remain in the fileThe model can run against a mixed provider connectionThe loader drops the linked stored connection before it resolves or persists settings
A forced API path or required header is applied to only one provider routeRequests can fail or reach the endpoint without the needed protocol or headerThe model setup applies API type and extra headers to the matching SDK and LiteLLM paths
Sticky OpenRouter sessions are enabled without a stable request contextCalls do not receive a session ID and cannot gain session-based upstream pinningStrix adds IDs only when the model call has an agent identity and the setting is enabled
Attribution state from a prior model remains when the model changesA provider can receive headers intended for another routeStrix removes prior app attribution headers before applying the headers for the resolved model
Parallel tool calls are enabled for a route that does not support themThe provider can reject the request or return a tool format the run loop cannot useProvider capability checks must gate the request option

Key files

FileWhy to read it
strix/…/settings.pyDefines the validated settings groups, aliases, model request limits, stream bounds, API path choice, preflight bound, extra request fields, parallel tool-call option, and defaults.
strix/…/loader.pyExplains source precedence, linked connection handling, config overrides, caching, and persistence.
strix/…/models.pyShows model routing, provider defaults, Codex behavior, secondary-provider isolation, request controls, stream bounds, turn guards, attribution, and optional OpenRouter sessions.
strix/…/codex.pyDefines subscription model selection, OAuth storage, token refresh, and request auth.
strix/…/tool_call_ids.pyExplains conversation-wide tool-call ID repair, including missing and duplicate IDs.
strix/…/tool_call_arguments.pyExplains repair of malformed tool-call arguments before conversation replay.
strix/…/tool_call_limits.pyDefines the per-turn tool-call safety boundary.
strix/…/inputs.pyConnects settings to request-level reasoning, timeout, header, cache, and tool-choice controls.
strix/…/runner.pyShows when configuration is loaded and how the resolved model starts a scan.
strix/…/environment.pyShows the user-facing checks for model and authentication readiness.
strix/…/dedupe.pyShows how a dedicated dedupe model receives its own provider credentials.
docs/configuration-and-integrations.mdProvides the parent overview of configuration and external integration concerns.
docs/mcp-integration.mdCovers the related model-tool integration settings.
docs/proxy-and-caido-integration.mdCovers the related proxy and Caido settings and resource flow.