scriptoriumadmin/strix
1
0
Fork 0
mirror of https://github.com/usestrix/strix.git synced 2026-10-16 04:28:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
strix/docs/advanced/configuration.mdx
Matthew Flanagan 4aaab2f82b
feat(auth): Entra ID user sign-in and token commands for Anthropic WIF 
Add identity token sources for Anthropic Workload Identity Federation
beyond a token file:

- ANTHROPIC_IDENTITY_TOKEN_COMMAND: a command run on every exchange whose
  stdout is the JWT (run without a shell; errors never include stdout).
  Saved to the Strix config like the other ANTHROPIC_* settings.
- `strix auth login entra [--manual] [--tenant ID] [--app ID]`: PKCE
  sign-in as a Microsoft Entra ID user, using the audience app as its own
  public client so the stored refresh token only reaches that audience.
  Tokens are refreshed automatically; defaults come from
  STRIX_ENTRA_TENANT_ID / STRIX_ENTRA_APP_ID.

Source order: token file, command, literal token, Entra sign-in, GitHub
Actions OIDC. `strix auth status` and `logout` now cover both ChatGPT and
Entra, and `strix auth test [--config PATH]` runs one exchange with the
source a scan would use, reporting the source, claims and result without
printing any token.

Docs: new "Anthropic via Microsoft Entra ID" guide (Entra and Console
setup, Entra users on any host, Azure VM managed identities, everyday
use, security, troubleshooting), plus the WIF settings in the
configuration reference and `strix auth` in the CLI reference.
2026-10-12 22:22:41 +11:00

245 lines
10 KiB
Text
Raw Blame History

---
title: "Configuration"
description: "Environment variables for Strix"
---
Configure Strix using environment variables or a config file.
## LLM Configuration
<ParamField path="STRIX_LLM" type="string" required>
Model name in LiteLLM format (e.g., `openrouter/z-ai/glm-5.3`, `openai/gpt-5.4`).
</ParamField>
<ParamField path="LLM_API_KEY" type="string">
API key for your LLM provider. Not required for local models or cloud provider auth (Vertex AI, AWS Bedrock).
</ParamField>
<ParamField path="LLM_API_BASE" type="string">
Custom API base URL. Also accepts `OPENAI_API_BASE`, `LITELLM_BASE_URL`, or `OLLAMA_API_BASE`.
</ParamField>
<ParamField path="STRIX_API_TYPE" type="string">
Select the OpenAI API path for the model: `responses` or `chat_completions`.
By default, a custom `LLM_API_BASE` uses chat completions. Set this variable
when your gateway requires the other API. Also accepts `STRIX_FORCE_API`.
</ParamField>
<ParamField path="LLM_EXTRA_HEADERS" type="string">
Extra HTTP headers sent on every LLM request, as a JSON object (e.g.
`{"X-Feature-Key":"value","X-Tenant":"acme"}`). Useful for OpenAI-compatible
gateways that require attribution or routing headers in addition to the bearer
token. The bearer token itself still comes from `LLM_API_KEY`. Applies to both
the LiteLLM and native OpenAI routing paths.
</ParamField>
<ParamField path="LLM_TIMEOUT" default="300" type="integer">
Request timeout in seconds for LLM calls.
</ParamField>
<ParamField path="LLM_PREFLIGHT_TIMEOUT" default="30" type="integer">
Seconds the startup connection check waits for the model to answer before
failing with `LLM CONNECTION FAILED`. Scan requests use `LLM_TIMEOUT`.
</ParamField>
<ParamField path="STRIX_LLM_MAX_RETRIES" default="5" type="integer">
Maximum number of retries for LLM API calls on transient failures.
</ParamField>
<ParamField path="STRIX_REASONING_EFFORT" default="high" type="string">
Control thinking effort for reasoning models. Valid values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Defaults to `medium` for quick scan mode.
</ParamField>
<ParamField path="STRIX_MEMORY_COMPRESSOR_TIMEOUT" default="30" type="integer">
Timeout in seconds for memory compression operations (context summarization).
</ParamField>
<ParamField path="STRIX_OPENROUTER_STICKY_SESSIONS" default="false" type="boolean">
Send a per-agent `session_id` on OpenRouter requests, so each agent's calls stay on one upstream provider and its prompt cache carries over between turns. When unset, OpenRouter routes every request freely.
</ParamField>
<ParamField path="STRIX_CACHE_BLOCK_TOKENS" default="128" type="integer">
Token block size that providers cache prompts in. A turn counts as a cache miss in the run report only when the cached tokens fall at least this many tokens short of the previous prompt and the prompt did not shrink. Lower it for providers with smaller blocks (DeepSeek and GLM use 64; vLLM defaults to 16).
</ParamField>
### Anthropic Workload Identity Federation
Authenticate to Anthropic with short-lived tokens from your identity provider instead of `LLM_API_KEY`, which must be unset or empty. See [Anthropic](/llm-providers/anthropic#workload-identity-federation-no-api-key) and [Anthropic via Microsoft Entra ID](/llm-providers/anthropic-entra-id).
<ParamField path="ANTHROPIC_FEDERATION_RULE_ID" type="string">
Federation rule to exchange against (`fdrl_…`). Required, with `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, and an identity token source.
</ParamField>
<ParamField path="ANTHROPIC_ORGANIZATION_ID" type="string">
Anthropic organization ID (a UUID).
</ParamField>
<ParamField path="ANTHROPIC_SERVICE_ACCOUNT_ID" type="string">
Service account the rule maps to (`svac_…`).
</ParamField>
<ParamField path="ANTHROPIC_WORKSPACE_ID" type="string">
Workspace to act in (`wrkspc_…`). Required when the rule covers several workspaces.
</ParamField>
<ParamField path="ANTHROPIC_IDENTITY_TOKEN_FILE" type="string">
File holding the identity token (JWT), read again on every exchange. Takes precedence over the other sources.
</ParamField>
<ParamField path="ANTHROPIC_IDENTITY_TOKEN_COMMAND" type="string">
Command run on every exchange whose stdout is the JWT (Strix only). Run without a shell; use `sh -c '…'` for pipelines.
</ParamField>
<ParamField path="ANTHROPIC_IDENTITY_TOKEN" type="string">
A literal JWT, for short runs. Never saved to the config file.
</ParamField>
<ParamField path="STRIX_ENTRA_TENANT_ID" type="string">
Default Entra tenant for `strix auth login entra`.
</ParamField>
<ParamField path="STRIX_ENTRA_APP_ID" type="string">
Default Entra app registration for `strix auth login entra`: the app that is both the OAuth client and the token audience.
</ParamField>
### Dedicated deduplication model
Finding deduplication is a cheap, structured classification task. By default it
runs on the main model, but you can route it to a smaller/cheaper model without
affecting the agents that do the actual testing.
<ParamField path="STRIX_DEDUPE_MODEL" type="string">
Model used to judge whether a candidate finding duplicates an existing report.
Falls back to `STRIX_LLM` when unset.
</ParamField>
<ParamField path="DEDUPE_LLM_API_KEY" type="string">
Optional provider key for the deduplication model.
</ParamField>
<ParamField path="DEDUPE_LLM_API_BASE" type="string">
Optional custom API base URL for the deduplication model. Use when the dedupe
model runs on a different endpoint than the main model.
</ParamField>
<ParamField path="DEDUPE_LLM_EXTRA_HEADERS" type="string">
Optional JSON object of extra HTTP headers sent on every deduplication-model
request, e.g. `{"X-Feature-Key":"value"}`. A dedicated dedupe model never
inherits `LLM_EXTRA_HEADERS`; set this when its endpoint needs custom headers.
</ParamField>
<ParamField path="STRIX_DEDUPE_REASONING_EFFORT" type="string">
Reasoning effort for the deduplication model. Defaults to the model's own
baseline when unset.
</ParamField>
## Optional Features
<ParamField path="PERPLEXITY_API_KEY" type="string">
API key for Perplexity AI. Enables real-time web search during scans for OSINT and vulnerability research.
</ParamField>
<ParamField path="EXA_API_KEY" type="string">
API key for Exa. Enables real-time web search through the Exa `/search` endpoint. Exa also powers the `web_get_contents` tool, which fetches the full text of a page through the Exa `/contents` endpoint. This is the preferred web search provider.
</ParamField>
<ParamField path="STRIX_WEB_SEARCH_PROVIDER" default="auto" type="string">
Web search provider: `auto`, `perplexity`, or `exa`. With `auto`, Strix uses Exa when `EXA_API_KEY` is set, and Perplexity otherwise. Set an explicit provider to pin one when you configure both keys.
</ParamField>
<ParamField path="STRIX_EXA_SEARCH_TYPE" default="auto" type="string">
Exa search mode: `auto`, `fast`, `instant`, `deep-lite`, `deep`, or `deep-reasoning`. Lower modes return results faster. Higher modes plan across more steps and take more time. This setting applies only to the Exa provider.
</ParamField>
<ParamField path="STRIX_EXA_NUM_RESULTS" default="5" type="integer">
Number of Exa results to return, from `1` to `100`. Each result includes a title, a URL, and a short security-focused summary. To read a full page, the agent calls `web_get_contents` with the result URL. This setting applies only to the Exa provider.
</ParamField>
<ParamField path="POSTMAN_API_KEY" type="string">
Postman API key (`PMAK-…`). Enables fetching Postman collections by id as a target (`postman://<collection-uid>`), and Postman environments (`postman://<collection-uid>?env=<environment-uid>`) to resolve collection variables. Not needed when passing a local collection export file.
</ParamField>
<ParamField path="STRIX_TELEMETRY" default="1" type="string">
Telemetry toggle. Set to `0`, `false`, `no`, or `off` to disable telemetry (PostHog, Scarf, OTEL).
</ParamField>
<ParamField path="TRACELOOP_BASE_URL" type="string">
OTLP/Traceloop base URL for remote OpenTelemetry export. If unset, Strix keeps traces local only.
</ParamField>
<ParamField path="TRACELOOP_API_KEY" type="string">
API key used for remote trace export. Remote export is enabled only when both `TRACELOOP_BASE_URL` and `TRACELOOP_API_KEY` are set.
</ParamField>
<ParamField path="TRACELOOP_HEADERS" type="string">
Optional custom OTEL headers (JSON object or `key=value,key2=value2`). Useful for Langfuse or custom/self-hosted OTLP gateways.
</ParamField>
When remote OTEL vars are not set, Strix still writes complete run telemetry locally to:
```bash
strix_runs/<run_name>/events.jsonl
```
When remote vars are set, Strix dual-writes telemetry to both local JSONL and the remote OTEL endpoint.
## Docker Configuration
<ParamField path="STRIX_IMAGE" default="ghcr.io/usestrix/strix-sandbox:1.3.0" type="string">
Docker image to use for the sandbox container.
</ParamField>
<ParamField path="DOCKER_HOST" type="string">
Docker daemon address, for example `unix:///var/run/docker.sock` or `tcp://10.0.0.5:2375`. When not set, Strix connects to the same daemon as the `docker` CLI: the current docker context (`docker context use`), then the default socket. Docker Desktop, OrbStack and Colima register their sockets as contexts, so no extra configuration is needed for them.
</ParamField>
<ParamField path="STRIX_RUNTIME_BACKEND" default="docker" type="string">
Runtime backend for the sandbox environment.
</ParamField>
## Sandbox Configuration
<ParamField path="STRIX_SANDBOX_EXECUTION_TIMEOUT" default="120" type="integer">
Maximum execution time in seconds for sandbox operations.
</ParamField>
<ParamField path="STRIX_SANDBOX_CONNECT_TIMEOUT" default="10" type="integer">
Timeout in seconds for connecting to the sandbox container.
</ParamField>
## Config File
Strix stores configuration in `~/.strix/cli-config.json`. You can also specify a custom config file:
```bash
strix --target ./app --config /path/to/config.json
```
**Config file format:**
```json
{
"env": {
"STRIX_LLM": "openrouter/z-ai/glm-5.3",
"LLM_API_KEY": "sk-...",
"STRIX_REASONING_EFFORT": "high"
}
}
```
## Example Setup
```bash
# Required
export STRIX_LLM="openrouter/z-ai/glm-5.3"
export LLM_API_KEY="sk-..."
# Optional: Enable web search (Exa preferred, Perplexity supported)
export EXA_API_KEY="..."
export PERPLEXITY_API_KEY="pplx-..."
# Optional: Custom timeouts
export LLM_TIMEOUT="600"
export STRIX_SANDBOX_EXECUTION_TIMEOUT="300"
```
Reference in a new issue View git blame Copy permalink