diff --git a/docs/advanced/configuration.mdx b/docs/advanced/configuration.mdx index 5148d616..59d0bcaf 100644 --- a/docs/advanced/configuration.mdx +++ b/docs/advanced/configuration.mdx @@ -1,17 +1,176 @@ -r^fئ{[rݰ뭦KKKB]NۙY\][ۈ\ܚ\[ێ[\ۛY[\XX\܈^KKBۙY\H^\[[\ۛY[\XX\܈HۙY[KHۙY\][ۂ\[QY[]HVH\OH[Ȉ\]Z\Y[[H[]SHܛX] -Kˋ[ZK MK [X]YK\ۛ] M M -K \[QY[\[QY[]HWTWVH\OH[ȏTH^H܈[\HݚY\\]Z\Y܈[[[܈YݚY\]] -\^RKUYK \[QY[\[QY[]HWTWАTH\OH[ȏ\HTH\HT [X\SRWTWАTX USWАTWT ܈SPWTWАTX \[QY[\[QY[]HWVWPQTȈ\OH[ȏ^HXY\[ۈ]\HH\]Y\ \HӈؚX -K˂Ȗ QX]\KR^H[YH U[[XYHX -K\Y[܈[RKX\]XB]]^\]\]Z\H]X][ۈ܈][XY\[Y][ۈHX\\[HX\\[][[Y\HWTWVX \Y\H]SH[]]H[RH][]˂ \[QY[\[QY[]HWSQSUY][H \OH[Y\\]Y\[Y[][Xۙ܈H[˂ \[QY[\[QY[]HVWPVԑUQTȈY][HH\OH[Y\X^[][H\و]Y\܈HTH[ۈ[Y[Z[\\˂ \[QY[\[QY[]HVԑPTӒSQԕY][HY\OH[ȏ۝[[Yܝ܈X\ۚ[[[ˈ[Y[Y\ΈۙX Z[[X[  YY][X Y Y X^ Y][YY][X܈]ZX[[K \[QY[\[QY[]HVQSSԖWTTԗSQSUY][H\OH[Y\[Y[][Xۙ܈Y[[ܞH\\[ۈ\][ۜ -۝^[[X\^][ۊK \[QY[YX]YY\X][ۈ[[[[Y\X][ۈ\HX\ X\Y\YX][ۈ\ˈHY][][ۈHXZ[[[ ][H[]H]HX[\X\\[[]]YX[HY[]HXX[\[˂\[QY[]HVQTWSS\OH[ȏ[[\YYH]\H[Y]H[[\X]\[^\[\ܝ [XVX[[] \[QY[\[QY[]HQTWWTWVH\OH[ȏ[ۘ[ݚY\^H܈HY\X][ۈ[[ \[QY[\[QY[]HQTWWTWАTH\OH[ȏ[ۘ[\HTH\HT܈HY\X][ۈ[[ \H[HY\B[[[ۈHY\[[[[HXZ[[[ \[QY[\[QY[]HQTWWVWPQTȈ\OH[ȏ[ۘ[ӈؚXو^HXY\[ۈ]\HY\X][ۋ[[[\]Y\ KˈȖ QX]\KR^H[YHX HYX]YY\H[[]\[\]WVWPQT]\[][[YY\HXY\˂ \[QY[\[QY[]HVQTWԑPTӒSQԕ\OH[ȏX\ۚ[Yܝ܈HY\X][ۈ[[ Y][H[[ ۂ\[[H[[] \[QY[[ۘ[X]\\‚\[QY[]HTVUWTWVH\OH[ȏTH^H܈\^]HRK[X\X[ ][YHXX\\[[܈S[[\X[]H\X\ \[QY[\[QY[]HPSTWVH\OH[ȏX[TH^H -PRx) -K[X\][X[X[ۜHY\H\] -X[X[ۋ]ZY -K[X[[\ۛY[ -X[X[ۋ]ZY[O[\ۛY[ ]ZY -H\HX[ۈ\XX\ˈYYY[\[H[X[ۈ^ܝ[K \[QY[\[QY[]HVSSQUHY][HH\OH[ȏ[[Y]HK]  [X  ܈ٙ\XH[[Y]H -\S -K \[QY[\[QY[]HPSАTWT\OH[ȏ X[\HT܈[[H[[[Y]H^ܝ Y[] ^Y\X\[ۛK \[QY[\[QY[]HPSTWVH\OH[ȏTH^H\Y܈[[HXH^ܝ [[H^ܝ\[XYۛH[PSАTWT[PSTWVX\H] \[QY[\[QY[]HPSPQTȈ\OH[ȏ[ۘ[\HSXY\ -ӈؚX܈^O][YK^L][YL -K\Y[܈[ٝ\H܈\K[ZY]]^\˂ \[QY[[[[HS\\H] ^[ܚ]\\]H[[[Y]H[H΂\^ܝ[[ۘ[YO][˚ۛ[[[H\\H] ^X[ ]ܚ]\[[Y]H[ӓ[H[[HS[[ \ۙY\][ۂ\[QY[]HVSPQHY][H܋[\\^ ^ \[Kˌ\OH[ȏ\[XYH\H܈H[۝Z[\ \[QY[\[QY[]HVSPQWSPHY][H]]Ȉ\OH[ȏ۝[[XYHX]Z\][ۋ\H]\\]Z\HH[YY[XYB[Z[]][[[]\[]Z[XN]]\\\HY][\ \[[Z][܋\\\X]ܚX\HH[[ˆ[ \[QY[\[QY[]HT\OH[ȏ\Y[[ۈ]] \H܈[[H\܈\HۙY\][ۜ˂ \[QY[\[QY[]HVԕSSQWАPSY][H\\OH[ȏ[[YHX[܈H[[\ۛY[ \[QY[\[QY[]HVRQГRUȈY][H \OH[Y\X^[][H[YH[XۙZ]܈H[\[ZYHXYHXYK[ܙX\H\ۈ܈X][HYY۝Z[\˂ \[QY[[ۙY\][ۂ\[QY[]HVSVPUSӗSQSUY][HL\OH[Y\X^[][H^X][ۈ[YH[Xۙ܈[\][ۜ˂ \[QY[\[QY[]HVSӓPSQSUY][HL\OH[Y\[Y[][Xۙ܈ۛX[H[۝Z[\ \[QY[ۙY[B^ܙ\ۙY\][ۈ[˜^ KXۙY˚ۘ [H[[XYHH\HۙY[N\^ K]\] \ KXۙY ] ۙY˚ۂۙY[HܛX]ۂˆ[ˆVH[ZK MKWTWVHKVԑPTӒSQԕYBB^[\H]\\\]Z\Y^ܝVOH[ZK MK^ܝWTWVOHK[ۘ[[XHXX\^ܝTVUWTWVOH K[ۘ[\H[Y[]™^ܝWSQSUH ^ܝVSVPUSӗSQSUH  \ No newline at end of file +--- +title: "Configuration" +description: "Environment variables for Strix" +--- + +Configure Strix using environment variables or a config file. + +## LLM Configuration + + + Model name in LiteLLM format (e.g., `openai/gpt-5.4`, `anthropic/claude-sonnet-4-6`). + + + + API key for your LLM provider. Not required for local models or cloud provider auth (Vertex AI, AWS Bedrock). + + + + Custom API base URL. Also accepts `OPENAI_API_BASE`, `LITELLM_BASE_URL`, or `OLLAMA_API_BASE`. + + + + 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. + + + + Request timeout in seconds for LLM calls. + + + + Maximum number of retries for LLM API calls on transient failures. + + + + Control thinking effort for reasoning models. Valid values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Defaults to `medium` for quick scan mode. + + + + Timeout in seconds for memory compression operations (context summarization). + + +### 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. + + + Model used to judge whether a candidate finding duplicates an existing report. + Falls back to `STRIX_LLM` when unset. + + + + Optional provider key for the deduplication model. + + + + Optional custom API base URL for the deduplication model. Use when the dedupe + model runs on a different endpoint than the main model. + + + + 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. + + + + Reasoning effort for the deduplication model. Defaults to the model's own + baseline when unset. + + +## Optional Features + + + API key for Perplexity AI. Enables real-time web search during scans for OSINT and vulnerability research. + + + + Postman API key (`PMAK-…`). Enables fetching Postman collections by id as a target (`postman://`), and Postman environments (`postman://?env=`) to resolve collection variables. Not needed when passing a local collection export file. + + + + Telemetry toggle. Set to `0`, `false`, `no`, or `off` to disable telemetry (PostHog, Scarf, OTEL). + + + + OTLP/Traceloop base URL for remote OpenTelemetry export. If unset, Strix keeps traces local only. + + + + API key used for remote trace export. Remote export is enabled only when both `TRACELOOP_BASE_URL` and `TRACELOOP_API_KEY` are set. + + + + Optional custom OTEL headers (JSON object or `key=value,key2=value2`). Useful for Langfuse or custom/self-hosted OTLP gateways. + + +When remote OTEL vars are not set, Strix still writes complete run telemetry locally to: + +```bash +strix_runs//events.jsonl +``` + +When remote vars are set, Strix dual-writes telemetry to both local JSONL and the remote OTEL endpoint. + +## Docker Configuration + + + Docker image to use for the sandbox container. + + + + Controls sandbox image acquisition. Use `never` to require a preloaded image + and fail without pulling when it is unavailable; `auto` preserves the default + first-run pull behavior. This does not restrict network access from a running + sandbox. + + + + Docker daemon socket path. Use for remote Docker hosts or custom configurations. + + + + Runtime backend for the sandbox environment. + + +## Sandbox Configuration + + + Maximum execution time in seconds for sandbox operations. + + + + Timeout in seconds for connecting to the sandbox container. + + +## 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": "openai/gpt-5.4", + "LLM_API_KEY": "sk-...", + "STRIX_REASONING_EFFORT": "high" + } +} +``` + +## Example Setup + +```bash +# Required +export STRIX_LLM="openai/gpt-5.4" +export LLM_API_KEY="sk-..." + +# Optional: Enable web search +export PERPLEXITY_API_KEY="pplx-..." + +# Optional: Custom timeouts +export LLM_TIMEOUT="600" +export STRIX_SANDBOX_EXECUTION_TIMEOUT="300" + +``` diff --git a/strix/config/settings.py b/strix/config/settings.py index 78bcec9d..321f2a26 100644 --- a/strix/config/settings.py +++ b/strix/config/settings.py @@ -1,60 +1,160 @@ -r^fئ{[rݰ뭦H^\X][ۈ][8%Y[X\][\Y Hٝ]\W[\ܝ[][ۜ‚H\[[\ܝ]\[HY[X[\ܝ[X\X\Y[HY[X][[\ܝ\T][][ۙYXX\ۚ[YܝH]\[țۙHZ[[X[ȋYY][HYYX^BQUSPVTH L АTWӑQH][ۙYX -\W[]]OQ[K[]W؞Wۘ[YOUYK^OHYۛܙHB\T][\T][N[[ۙYHАTWӑQ‚[[ۙHHY[ -Y][SۙK[X\HVHB\W^NۙHHY[ -Y][SۙK[Y][ۗ[X\P[X\X\WTWVHSRWTWVHK\Q[K -B\Wؘ\NۙHHY[ -Y][SۙK[Y][ۗ[X\P[X\X\WTWАTHSRWTWАTHSRWАTWTUSWАTWTSPWTWАTH -K -B^WXY\ΈXHۙHHY[ -Y][SۙK[X\HWVWPQTȋ\Q[K -BX\ۚ[YܝX\ۚ[YܝHY[ -Y][HY[X\HVԑPTӒSQԕBܘWܙ\]Z\YXNHY[ -Y][Q[K[X\HVѓԐWԑTURTQPH -B\XNHY[ -Y][UYK[X\HVTPH -B\XWX[Z[ΈHY[ -Y][Q[K[X\HWTPWPSRSȋ -B[Y[][HY[ -Y][L [X\HWSQSUBX[WYW[Y[][HY[ -Y][L OL [X\HWPSWQWSQSUBX^[\\[HY[ -Y][L̋OL [X\HWPVSTT -B\Y\T][\T][N[[ۙYHАTWӑQ‚[[ۙHHY[ -Y][SۙK[X\HVQTWSSBX\ۚ[YܝX\ۚ[YܝۙHHY[ -Y][SۙK[X\HVQTWԑPTӒSQԕ -B\W^NۙHHY[ -Y][SۙK[X\HQTWWTWVH\Q[JB\Wؘ\NۙHHY[ -Y][SۙK[X\HQTWWTWАTHB^WXY\ΈXHۙHHY[ -Y][SۙK[X\HQTWWVWPQTȋ\Q[K -B\۝^][\T][N۝^ ][X[Y[Y[\] []]\[\ܞH\X[ۋ[[ۙYHАTWӑQ‚]]\XHY[ -Y][UYK[X\HVӕVUUTPB\X؝Y\[Έ[HY[ -Y][L L [X\HVӕVЕQTSȊBY\[Έ[HY[ -Y][N L [X\HVӕVQTSȊB[X۝^[Έ[HY[ -Y][L  L [X\HVӕVѐSPSȂ -B[[X\WX^[Έ[HY[ -Y][MML [X\HVӕVSSPTWSȊB]]X^[Έ[HY[ -Y][N L [X\HVUUPVSȊB]]X^[\Έ[HY[ -Y][L L [X\HVUUPVSTȊB܈XݙHH[][ۋ[XH^HH]Y][^\]˂]]X^؞]\Έ[HY[ -Y][ML - L OLL [X\HVUUPVЖUTȂ -B\[[YT][\T][N[[ۙYHАTWӑQ‚[XYNHY[ -Y][H܋[\\^ ^ \[Kˌ[X\HVSPQH -B[XYW[XN]\[Ș]]ȋ]\HHY[ -Y][H]]ȋ[X\HVSPQWSPH -BX[HY[ -Y][H\[X\HVԕSSQWАPSBZY؛Z]Έ[HY[ -Y][L L [X\HVRQГRUȊBX^ܙY[ [XYH]]\]H\Y[۝^ - HۙJKX^۝^[XY\Έ[HY[ -Y][LOL [X\HVPVӕVSPQTȊB\[[Y]T][\T][N[[ۙYHАTWӑQ‚[XYHY[ -Y][UYK[X\HVSSQUHB\[Yܘ][۔][\T][N[[ۙYHАTWӑQ‚\^]W\W^NۙHHY[ -Y][SۙK[X\HTVUWTWVH\Q[K -BX[\W^NۙHHY[ -Y][SۙK[X\HPSTWVH\Q[K -B\Y]\][\T][N[[ۙYHАTWӑQ‚\HTوH^[^HH[Y]\Y\܈[XZ[\YX][ۈ[[ܞ\Y\ܝ[]\KH\]\[ˆH[^H\XNH[\\\HۛH[\\\HY[ -Y][H΋\ ^ ZH[X\HVTTB\][\T][N[[ۙYHАTWӑQ‚NT][HY[ -Y][٘XܞOST][BY\NY\T][HY[ -Y][٘XܞOQY\T][B[[YN[[YT][HY[ -Y][٘XܞOT[[YT][B۝^۝^][HY[ -Y][٘XܞOP۝^][B[[Y]N[[Y]T][HY[ -Y][٘XܞOU[[Y]T][B[Yܘ][ۜΈ[Yܘ][۔][HY[ -Y][٘XܞOR[Yܘ][۔][BY]\Y]\][HY[ -Y][٘XܞOUY]\][B \ No newline at end of file +"""Strix application settings — pydantic-settings powered.""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import AliasChoices, Field +from pydantic_settings import BaseSettings, SettingsConfigDict + + +ReasoningEffort = Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"] + +DEFAULT_MAX_TURNS = 500 + +_BASE_CONFIG = SettingsConfigDict( + case_sensitive=False, + populate_by_name=True, + extra="ignore", +) + + +class LlmSettings(BaseSettings): + model_config = _BASE_CONFIG + + model: str | None = Field(default=None, alias="STRIX_LLM") + api_key: str | None = Field( + default=None, + validation_alias=AliasChoices("LLM_API_KEY", "OPENAI_API_KEY"), + repr=False, + ) + api_base: str | None = Field( + default=None, + validation_alias=AliasChoices( + "LLM_API_BASE", + "OPENAI_API_BASE", + "OPENAI_BASE_URL", + "LITELLM_BASE_URL", + "OLLAMA_API_BASE", + ), + ) + extra_headers: dict[str, str] | None = Field( + default=None, + alias="LLM_EXTRA_HEADERS", + repr=False, + ) + reasoning_effort: ReasoningEffort = Field(default="high", alias="STRIX_REASONING_EFFORT") + force_required_tool_choice: bool = Field( + default=False, + alias="STRIX_FORCE_REQUIRED_TOOL_CHOICE", + ) + prompt_cache: bool = Field( + default=True, + alias="STRIX_PROMPT_CACHE", + ) + disable_streaming: bool = Field( + default=False, + alias="LLM_DISABLE_STREAMING", + ) + timeout: int = Field(default=300, alias="LLM_TIMEOUT") + stream_idle_timeout: int = Field(default=300, ge=0, alias="LLM_STREAM_IDLE_TIMEOUT") + max_tool_calls_per_turn: int = Field( + default=32, + ge=0, + alias="LLM_MAX_TOOL_CALLS_PER_TURN", + ) + + +class DedupeSettings(BaseSettings): + model_config = _BASE_CONFIG + + model: str | None = Field(default=None, alias="STRIX_DEDUPE_MODEL") + reasoning_effort: ReasoningEffort | None = Field( + default=None, + alias="STRIX_DEDUPE_REASONING_EFFORT", + ) + api_key: str | None = Field(default=None, alias="DEDUPE_LLM_API_KEY", repr=False) + api_base: str | None = Field(default=None, alias="DEDUPE_LLM_API_BASE") + extra_headers: dict[str, str] | None = Field( + default=None, + alias="DEDUPE_LLM_EXTRA_HEADERS", + repr=False, + ) + + +class ContextSettings(BaseSettings): + """Context-window management: per-tool-output caps and history compaction.""" + + model_config = _BASE_CONFIG + + auto_compact: bool = Field(default=True, alias="STRIX_CONTEXT_AUTO_COMPACT") + compact_buffer_tokens: int = Field(default=20_000, gt=0, alias="STRIX_CONTEXT_BUFFER_TOKENS") + keep_tokens: int = Field(default=8_000, gt=0, alias="STRIX_CONTEXT_KEEP_TOKENS") + fallback_context_tokens: int = Field( + default=200_000, gt=0, alias="STRIX_CONTEXT_FALLBACK_TOKENS" + ) + summary_max_tokens: int = Field(default=4_096, gt=0, alias="STRIX_CONTEXT_SUMMARY_TOKENS") + tool_output_max_tokens: int = Field(default=8_000, gt=0, alias="STRIX_TOOL_OUTPUT_MAX_TOKENS") + tool_output_max_lines: int = Field(default=2_000, gt=0, alias="STRIX_TOOL_OUTPUT_MAX_LINES") + # Floor above the truncation-notice size so a preview always fits. + tool_output_max_bytes: int = Field( + default=50 * 1024, ge=1024, alias="STRIX_TOOL_OUTPUT_MAX_BYTES" + ) + + +class RuntimeSettings(BaseSettings): + model_config = _BASE_CONFIG + + image: str = Field( + default="ghcr.io/usestrix/strix-sandbox:1.3.0", + alias="STRIX_IMAGE", + ) + image_pull_policy: Literal["auto", "never"] = Field( + default="auto", + alias="STRIX_IMAGE_PULL_POLICY", + ) + backend: str = Field(default="docker", alias="STRIX_RUNTIME_BACKEND") + # Max screenshot/image tool outputs kept live per agent context (0 = none). + max_context_images: int = Field(default=3, ge=0, alias="STRIX_MAX_CONTEXT_IMAGES") + + +class TelemetrySettings(BaseSettings): + model_config = _BASE_CONFIG + + enabled: bool = Field(default=True, alias="STRIX_TELEMETRY") + + +class IntegrationSettings(BaseSettings): + model_config = _BASE_CONFIG + + perplexity_api_key: str | None = Field( + default=None, + alias="PERPLEXITY_API_KEY", + repr=False, + ) + postman_api_key: str | None = Field( + default=None, + alias="POSTMAN_API_KEY", + repr=False, + ) + + +class ViewerSettings(BaseSettings): + model_config = _BASE_CONFIG + + # Base URL of the Strix relay the local viewer proxies to for email + # verification and encrypted report delivery. The browser never talks to + # the relay directly; the local server is the only caller. + app_url: str = Field(default="https://app.strix.ai", alias="STRIX_APP_URL") + + +class Settings(BaseSettings): + model_config = _BASE_CONFIG + + llm: LlmSettings = Field(default_factory=LlmSettings) + dedupe: DedupeSettings = Field(default_factory=DedupeSettings) + runtime: RuntimeSettings = Field(default_factory=RuntimeSettings) + context: ContextSettings = Field(default_factory=ContextSettings) + telemetry: TelemetrySettings = Field(default_factory=TelemetrySettings) + integrations: IntegrationSettings = Field(default_factory=IntegrationSettings) + viewer: ViewerSettings = Field(default_factory=ViewerSettings) diff --git a/strix/interface/environment.py b/strix/interface/environment.py index 8f6b3a03..208e103e 100644 --- a/strix/interface/environment.py +++ b/strix/interface/environment.py @@ -1,4 +1,4 @@ -r^fئ{O,y'vî"""Startup environment validation and Docker image management.""" +"""Startup environment validation and Docker image management.""" import logging import shutil diff --git a/strix/runtime/backends.py b/strix/runtime/backends.py index 7bc9b9e2..d1e3c2d1 100644 --- a/strix/runtime/backends.py +++ b/strix/runtime/backends.py @@ -1,31 +1,107 @@ -r^fئ{[rݰ뭦H[X[Y\H8%[XYXHVԕSSQWАPS -Y][\KHٝ]\W[\ܝ[][ۜ‚[\ܝ[™HX[ۜ˘X[\ܝ]Z]XK[XBH\[[\ܝTWPS[BYTWPS΂HY[˜[ X[Y\[\ܝX[Y\\H[˙]\ۘ[YWB[X[H[XVˋ]Z]XV\V[K[WWWB\[Y\ؘX[ - -[XYNX[Y\X[Y\ ^YܝΈ\V[  K[[[Έ\X[WWHۙHHۙKH O\V[K[WN[\H\[ۈXYHH[\Y[[ۋ\\\Θ^\[Y[[XUQRS ˆUԐU\ - \[\[ Y]]^K[\ܝˆ\^[H\[]\]HۋQ\X[ۉYYH\\HX\H[[Y \[ۋ\ +"""Sandbox backend registry — selected via STRIX_RUNTIME_BACKEND (default: docker).""" -X\]X]\X[^\HX[Y\[H[[ˆ۝Z[\8%HY[ ܙX]J -XۛHZ[H[\\[ۂؚX]]\Z[] \[]\[ێ[[]]^X[Y\\[ۈY][YH^X]HXHY[ []J -XBY\\ +from __future__ import annotations -X\[\˂[\ܝ\HY[˜[ [\˙\[\ܝ\[Y[[ۜ‚H^ ۙY˛Y\[\ܝY][ˆH^ [[YK\Y[[\ܝ^\[Y[Y[H^\[Y[ -\W[ -JBY[ ^ؚ[[[H[[[܈BY[ [XYW[XHHY][ -K[[YK[XYW[XB[ۜH\[Y[[ۜ[XYOZ[XYK^YܝY^YܝB\[ۈH]Z]Y[ ܙX]J[ۜ[[ۜX[Y\[X[Y\ -B]Z]\[ۋ\ +import logging +from collections.abc import Awaitable, Callable +from typing import TYPE_CHECKING, Any -B]\Y[ \[ۂАPSΈX[X[HHˆ\\ؘX[ BВSSSАPSΈ]HHș\BY]ؘX[ -NH O[X[]\HX[XܞH܈X܈Z\K\΂NX[Y[YY\ -Kˈ\ -KX]\^Xˆ[Xˈ[ۛۈ[Y\Z\HۙY\\XB[[YYX][H[XYو[[HX[HY][ X[HАPS˙] -JBYX[\ۙN\ܝYH[ܝY -АPSJBZ\H[YQ\܊[ۛۈVԕSSQWАPSۘ[YH\H -\ܝY\ܝYJH -B\XY[XY[X[ \ȋJB]\X[YY\\ؘX[ -NX[[X[  -\ܝؚ[[[ΈH[KH OۙNY\\H\HX[[\X [[Y܈ۜX[H\\\Z\ۈ[[YH8%Y\\YܙH[H\[ۗX[Y\ܙX]Wܗܙ]\X[ K\Y\\[ˆ[^\[Hݙ\ܚ]\H[܈[K\ܝؚ[[[Y][[NH[[H[[YH[YHH[\[\\[Kˆ]\[Y[\\\X[Y\[Y\\Y[XY АPSۘ[YWHHX[Y\ܝؚ[[[΂ВSSSАPS˘Y -JB[NВSSSАPS˙\\ -JB\[Y\\Y[X[ \ -[[[Έ \HK\ܝؚ[[[BYX[\ܝؚ[[[NH O]\H[ВSSSАPS‚Y\ܝYؘX[ -H O\N]\ܝY -АPSB \ No newline at end of file + +if TYPE_CHECKING: + from agents.sandbox.manifest import Manifest + + +logger = logging.getLogger(__name__) + + +SandboxBackend = Callable[..., Awaitable[tuple[Any, Any]]] + + +async def _docker_backend( + *, + image: str, + manifest: Manifest, + exposed_ports: tuple[int, ...], + bind_mounts: list[dict[str, Any]] | None = None, +) -> tuple[Any, Any]: + """Bring up a session backed by the local Docker daemon. + + Uses :class:`StrixDockerSandboxClient` to inject NET_ADMIN / + NET_RAW caps + ``host.docker.internal`` host-gateway. Imports + ``docker`` lazily so deployments that target a non-Docker + backend don't need the docker-py library installed. + + ``session.start()`` is what materializes the manifest into the running + container — the SDK's ``client.create()`` only builds the inner session + object without applying it. ``async with session:`` would call it too, but + Strix manages session lifetime explicitly via ``client.delete()`` so we + trigger ``start()`` ourselves. + """ + import docker + from agents.sandbox.sandboxes.docker import DockerSandboxClientOptions + + from strix.config.loader import load_settings + from strix.runtime.docker_client import StrixDockerSandboxClient + + client = StrixDockerSandboxClient(docker.from_env()) + client.strix_bind_mounts = bind_mounts or [] + client.image_pull_policy = load_settings().runtime.image_pull_policy + options = DockerSandboxClientOptions(image=image, exposed_ports=exposed_ports) + session = await client.create(options=options, manifest=manifest) + await session.start() + return client, session + + +_BACKENDS: dict[str, SandboxBackend] = { + "docker": _docker_backend, +} + +_BIND_MOUNT_BACKENDS: set[str] = {"docker"} + + +def get_backend(name: str) -> SandboxBackend: + """Return the backend factory for ``name`` or raise. + + Args: + name: Backend identifier (e.g. ``"docker"``). Match is exact; + no fallback. Unknown values raise so config typos surface + immediately instead of silently picking a default. + """ + backend = _BACKENDS.get(name) + if backend is None: + supported = ", ".join(sorted(_BACKENDS)) + raise ValueError( + f"Unknown STRIX_RUNTIME_BACKEND: {name!r} (supported: {supported})", + ) + logger.debug("Selected sandbox backend: %s", name) + return backend + + +def register_backend( + name: str, + backend: SandboxBackend, + *, + supports_bind_mounts: bool = False, +) -> None: + """Register a custom backend under ``name``. + + Intended for downstream users who ship their own runtime — register + before any ``session_manager.create_or_reuse`` call. Re-registering + an existing name overwrites the prior entry. ``supports_bind_mounts`` + defaults to False: a remote runtime cannot see the caller's filesystem, so + it is handed local sources as manifest entries to upload instead. + """ + _BACKENDS[name] = backend + if supports_bind_mounts: + _BIND_MOUNT_BACKENDS.add(name) + else: + _BIND_MOUNT_BACKENDS.discard(name) + logger.info("Registered sandbox backend: %s (bind mounts: %s)", name, supports_bind_mounts) + + +def backend_supports_bind_mounts(name: str) -> bool: + return name in _BIND_MOUNT_BACKENDS + + +def supported_backends() -> list[str]: + return sorted(_BACKENDS) diff --git a/strix/runtime/docker_client.py b/strix/runtime/docker_client.py index fc3a56e5..c1ff251c 100644 --- a/strix/runtime/docker_client.py +++ b/strix/runtime/docker_client.py @@ -1,4 +1,4 @@ -r^fئ{O,y'vî"""StrixDockerSandboxClient — preserves the image's ENTRYPOINT and adds +"""StrixDockerSandboxClient — preserves the image's ENTRYPOINT and adds NET_ADMIN/NET_RAW capabilities + host-gateway. The SDK's ``DockerSandboxClient._create_container`` does not expose a hook for diff --git a/tests/test_config_loader.py b/tests/test_config_loader.py index 6a3a3a84..7848592b 100644 --- a/tests/test_config_loader.py +++ b/tests/test_config_loader.py @@ -1,66 +1,225 @@ -r^fئ{[rݰ뭦H\܈^ ۙY˛Y\ӈݙ\Y\[X\\][ۋ\\[KHٝ]\W[\ܝ[][ۜ‚[\ܝۂH\[[\ܝTWPS‚[\ܝ]\HY[X[\ܝ[X\X\Y[ [Y][ۑ\܂HY[X˙Y[[\ܝY[[‚H^ ۙY[\ܝY\H^ ۙY˜][[\ܝ۝^][‚YTWPS΂H]X[\ܝ]WSVTHˆVHWTWVHSRWTWVHWTWАTHSRWTWАTHSRWАTWTUSWАTWTSPWTWАTHVԑPTӒSQԕVѓԐWԑTURTQPHWSQSUTVUWTWVH[[YT][ˆVSPQHVSPQWSPHVԕSSQWАPSVRQГRUȋ[[Y]T][ˆVSSQUHB]\ ^\J]]\OUYJBYܙ\]Y\]J[ۚ^\]]\ [ۚ^T] -H OۙN\][[Hؘ[[X\ۛۈ[\܈]\Z[\X[ˈ܈^H[WSVT΂[ۚ^\] [[^KZ\[Q[JB[ۚ^\] ]]Y\XYۙJB[ۚ^\] ]]Y\ݙ\YHۙJB KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKHˆܙXYڜۗݙ\Y\ˆ KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKH‚Y\ܙXYڜۗݙ\Y\Z\[ٚ[J\]] -H OۙN\\Y\ܙXYڜۗݙ\Y\\] KۈHOHBY\ܙXYڜۗݙ\Y\ܜ\ڜۊ\]] -H OۙN]H\] KXۙY˚ۈ] ܚ]W^ -ۛ[Yۈ[[H]NB\\Y\ܙXYڜۗݙ\Y\] -HOHBY\ܙXYڜۗݙ\Y\ۛۗX[\]] -H OۙN]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[țHX_JK[[H]NB\\Y\ܙXYڜۗݙ\Y\] -HOHBY\ܙXYڜۗݙ\Y\X\ۙ\Y][\]] -H OۙN]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[ȔVH^K[[[TVUWTWVHȟ_JK[[H]N -B\\Y\ܙXYڜۗݙ\Y\] -HOHˆHț[[^K[[[K[Yܘ][ۜȎȜ\^]W\W^HȟKBY\ܙXYڜۗݙ\Y\\^\[XYW[[\ۊ\]] [ۚ^\]]\ [ۚ^T]H OۙN[ۚ^\] ][VHKY[B]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[ȔVHKY[H_JK[[H]NB[[ OHӈ[YH\\XY\[[]\˂\\Y\ܙXYڜۗݙ\Y\] -HOHBY\ܙXYڜۗݙ\Y\[[XܛٚY[[X\\\]] [ۚ^\]]\ [ۚ^T]H OۙN\W^H\\H[X\X\WTWVHSRWTWVHKH[]ۙH[X\[HH\\Y[H[\[]\[[ˆH[H[H[YH]\H\XY\[[]\ -X][[K[ۚ^\] ][SRWTWVHY[B]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[ȓWTWVHY[H_JK[[H]NB\\Y\ܙXYڜۗݙ\Y\] -HOHBY\ܙXYڜۗݙ\Y\[[\W[[]][J\]] [ۚ^\]]\ [ۚ^T]H OۙN][\H\W[]]OQ[KH\\H[\[[\] [ۚ^\] ][^HKY[B]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[ȔVHKY[H_JK[[H]NB\\Y\ܙXYڜۗݙ\Y\] -HOHBY\ܙXYڜۗݙ\Y\\\ڜۗ[ۛ[X\[[\ۊ\]] -H OۙN[X\و\W^H\][H[\ۛY[ OH[H[YH\\Y ][[]\ܙY[\HۋY\[X\˂]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[ȓSRWTWVHY[H_JK[[H]NB\\Y\ܙXYڜۗݙ\Y\] -HOHțHȘ\W^HY[H_BY\]]X^؞]\ܙZXXۛXWݘ[Y\ -H OۙN]]\ Z\\[Y][ۑ\܊N۝^][VUUPVЖUTM -BY\]]X^؞]\X\ٛ܊ -H OۙN\\۝^][VUUPVЖUTLL -K]]X^؞]\OH L Y\ܝ[[YWZY؛Z]ٜW[[ۚ^\]]\ [ۚ^T] -H OۙN[ۚ^\] ][VRQГRUȋL B\\Y\Y][ -K[[YKZY؛Z]OHL Y\ܝ[[YW[XYW[XWٜW[[ۚ^\]]\ [ۚ^T] -H OۙN[ۚ^\] ][VSPQWSPH]\B\\Y\Y][ -K[[YK[XYW[XHOH]\ KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKHˆ[X\\ٛ܂ KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKH‚Y\[X\\ٛܗ[\W[X\ -H OۙN[HY[[[X\HSTWSPTȊB\\Y\[X\\ٛ܊[HOHȔSTWSPTȗBY\[X\\ٛܗ[X\X\ -H OۙN[ΈY[[HY[ -\NYۛܙV\YۛY[BY][SۙK[Y][ۗ[X\P[X\X\TPӑK -B\\Y\[X\\ٛ܊[HOHȑTPӑBY\[X\\ٛܗ[ݘ[Y][ۗ[X\ -H OۙN[ΈY[[HY[ -Y][SۙK[Y][ۗ[X\HSPTȊH\NYۛܙV\YۛY[B\\Y\[X\\ٛ܊[HOHȔSPTȗBY\[X\\ٛܗۛ[X\ -H OۙN\\Y\[X\\ٛ܊Y[[ -JHOHB KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKHˆ\WۙYݙ\YH -Y][[ ]\ KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKH‚Y\\Wݙ\YW[Y][ܛ[\ -\]] -H OۙN]H\] KXۙY˚ۈ] ܚ]W^ -ۋ[\ș[ȔVH[ ]\ [[[TVUWTWVHȟ_JK[[H]N -BY\\WۙYݙ\YJ] -B][HY\Y][ -B\\][˛K[[OH[ ]\ [[[\\][˚[Yܘ][ۜ˜\^]W\W^HOHȂXۙ[\Y[[^Y O[YHؚX \\Y\Y][ -H\][‚Y\\WۙYݙ\YW[[Y]\XJ\]] -H OۙN\H\] \ ۈ\ ܚ]W^ -ۋ[\ș[ȔVH\ [[[_JK[[H]NBXۙH\] Xۙ ۈXۙ ܚ]W^ -ۋ[\ș[ȔVHXۙ [[[_JK[[H]NBY\\WۙYݙ\YJ\ -B\\Y\Y][ -KK[[OH\ [[[Y\\WۙYݙ\YJXۙ -B\\Y\Y][ -KK[[OHXۙ [[[ KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKHˆ\\\[ KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKH‚Y\\\\[ܚ]\[؛\]] [ۚ^\]]\ [ۚ^T] -H OۙN[ۚ^\] ][VH\\Y [[[B\]H\] X KXۙY˚ۈY\\WۙYݙ\YJ\] -BY\\\\[ +"""Tests for strix.config.loader: JSON overrides, alias resolution, persistence.""" -B\\\] ^\ -B\\ۋY\] XY^ -[[H]NJHOHˆ[ȔVH\\Y [[[BBY\\\\[] [J\]] [ۚ^\]]\ [ۚ^T] -H OۙN[ۚ^\] ][VH\\Y [[[B\]H\] KXۙY˚ۈY\\WۙYݙ\YJ\] -BY\\\\[ +from __future__ import annotations -B\\\] ] +import json +from typing import TYPE_CHECKING -K[H OH ͌  \ No newline at end of file +import pytest +from pydantic import AliasChoices, Field, ValidationError +from pydantic.fields import FieldInfo + +from strix.config import loader +from strix.config.settings import ContextSettings + + +if TYPE_CHECKING: + from pathlib import Path + + +_LLM_ENV_KEYS = [ + "STRIX_LLM", + "LLM_API_KEY", + "OPENAI_API_KEY", + "LLM_API_BASE", + "OPENAI_API_BASE", + "OPENAI_BASE_URL", + "LITELLM_BASE_URL", + "OLLAMA_API_BASE", + "STRIX_REASONING_EFFORT", + "STRIX_FORCE_REQUIRED_TOOL_CHOICE", + "LLM_TIMEOUT", + "PERPLEXITY_API_KEY", + # RuntimeSettings + "STRIX_IMAGE", + "STRIX_IMAGE_PULL_POLICY", + "STRIX_RUNTIME_BACKEND", + # TelemetrySettings + "STRIX_TELEMETRY", +] + + +@pytest.fixture(autouse=True) +def _reset_loader_state(monkeypatch: pytest.MonkeyPatch) -> None: + """Reset module globals and clear known env vars for deterministic runs.""" + for key in _LLM_ENV_KEYS: + monkeypatch.delenv(key, raising=False) + monkeypatch.setattr(loader, "_cached", None) + monkeypatch.setattr(loader, "_override", None) + + +# --------------------------------------------------------------------------- # +# _read_json_overrides +# --------------------------------------------------------------------------- # + + +def test_read_json_overrides_missing_file(tmp_path: Path) -> None: + assert loader._read_json_overrides(tmp_path / "nope.json") == {} + + +def test_read_json_overrides_corrupt_json(tmp_path: Path) -> None: + path = tmp_path / "cli-config.json" + path.write_text("{not valid json", encoding="utf-8") + assert loader._read_json_overrides(path) == {} + + +def test_read_json_overrides_non_dict_env(tmp_path: Path) -> None: + path = tmp_path / "cli-config.json" + path.write_text(json.dumps({"env": ["not", "a", "dict"]}), encoding="utf-8") + assert loader._read_json_overrides(path) == {} + + +def test_read_json_overrides_maps_to_nested_settings(tmp_path: Path) -> None: + path = tmp_path / "cli-config.json" + path.write_text( + json.dumps({"env": {"STRIX_LLM": "my-model", "PERPLEXITY_API_KEY": "pk"}}), + encoding="utf-8", + ) + assert loader._read_json_overrides(path) == { + "llm": {"model": "my-model"}, + "integrations": {"perplexity_api_key": "pk"}, + } + + +def test_read_json_overrides_skips_keys_already_in_environ( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setenv("STRIX_LLM", "from-env") + path = tmp_path / "cli-config.json" + path.write_text(json.dumps({"env": {"STRIX_LLM": "from-file"}}), encoding="utf-8") + # env wins -> the JSON value is not surfaced as an init kwarg. + assert loader._read_json_overrides(path) == {} + + +def test_read_json_overrides_env_wins_across_field_aliases( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + # api_key resolves from AliasChoices("LLM_API_KEY", "OPENAI_API_KEY"). The env + # sets one alias while the persisted file holds another. Env must still win, so + # the stale file value must not be surfaced as an init kwarg (which outranks env). + monkeypatch.setenv("OPENAI_API_KEY", "sk-env") + path = tmp_path / "cli-config.json" + path.write_text(json.dumps({"env": {"LLM_API_KEY": "sk-file"}}), encoding="utf-8") + assert loader._read_json_overrides(path) == {} + + +def test_read_json_overrides_env_wins_case_insensitively( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + # Settings use case_sensitive=False, so a lowercase env var also counts as set. + monkeypatch.setenv("strix_llm", "from-env") + path = tmp_path / "cli-config.json" + path.write_text(json.dumps({"env": {"STRIX_LLM": "from-file"}}), encoding="utf-8") + assert loader._read_json_overrides(path) == {} + + +def test_read_json_overrides_uses_json_when_no_alias_in_environ(tmp_path: Path) -> None: + # No alias of api_key is set in the environment -> the file value is used, even + # when it is stored under a non-first alias. + path = tmp_path / "cli-config.json" + path.write_text(json.dumps({"env": {"OPENAI_API_KEY": "sk-file"}}), encoding="utf-8") + assert loader._read_json_overrides(path) == {"llm": {"api_key": "sk-file"}} + + +def test_tool_output_max_bytes_rejects_sub_notice_values() -> None: + with pytest.raises(ValidationError): + ContextSettings(STRIX_TOOL_OUTPUT_MAX_BYTES=64) + + +def test_tool_output_max_bytes_accepts_floor() -> None: + assert ContextSettings(STRIX_TOOL_OUTPUT_MAX_BYTES=1024).tool_output_max_bytes == 1024 + + +def test_runtime_image_pull_policy_from_env(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("STRIX_IMAGE_PULL_POLICY", "never") + + assert loader.load_settings().runtime.image_pull_policy == "never" + + +# --------------------------------------------------------------------------- # +# _aliases_for +# --------------------------------------------------------------------------- # + + +def test_aliases_for_simple_alias() -> None: + finfo = FieldInfo(alias="SIMPLE_ALIAS") + assert loader._aliases_for(finfo) == ["SIMPLE_ALIAS"] + + +def test_aliases_for_alias_choices() -> None: + finfo: FieldInfo = Field( # type: ignore[assignment] + default=None, + validation_alias=AliasChoices("FIRST", "SECOND"), + ) + assert loader._aliases_for(finfo) == ["FIRST", "SECOND"] + + +def test_aliases_for_string_validation_alias() -> None: + finfo: FieldInfo = Field(default=None, validation_alias="STR_ALIAS") # type: ignore[assignment] + assert loader._aliases_for(finfo) == ["STR_ALIAS"] + + +def test_aliases_for_no_alias() -> None: + assert loader._aliases_for(FieldInfo()) == [] + + +# --------------------------------------------------------------------------- # +# apply_config_override + load_settings round-trip +# --------------------------------------------------------------------------- # + + +def test_apply_override_and_load_settings_round_trip(tmp_path: Path) -> None: + path = tmp_path / "cli-config.json" + path.write_text( + json.dumps({"env": {"STRIX_LLM": "round-trip-model", "PERPLEXITY_API_KEY": "pk"}}), + encoding="utf-8", + ) + + loader.apply_config_override(path) + settings = loader.load_settings() + + assert settings.llm.model == "round-trip-model" + assert settings.integrations.perplexity_api_key == "pk" + # Second call is memoized -> same object. + assert loader.load_settings() is settings + + +def test_apply_config_override_invalidates_cache(tmp_path: Path) -> None: + first = tmp_path / "first.json" + first.write_text(json.dumps({"env": {"STRIX_LLM": "first-model"}}), encoding="utf-8") + second = tmp_path / "second.json" + second.write_text(json.dumps({"env": {"STRIX_LLM": "second-model"}}), encoding="utf-8") + + loader.apply_config_override(first) + assert loader.load_settings().llm.model == "first-model" + + loader.apply_config_override(second) + assert loader.load_settings().llm.model == "second-model" + + +# --------------------------------------------------------------------------- # +# persist_current +# --------------------------------------------------------------------------- # + + +def test_persist_current_writes_env_block(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("STRIX_LLM", "persisted-model") + target = tmp_path / "sub" / "cli-config.json" + loader.apply_config_override(target) + + loader.persist_current() + + assert target.exists() + assert json.loads(target.read_text(encoding="utf-8")) == { + "env": {"STRIX_LLM": "persisted-model"} + } + + +def test_persist_current_sets_0600_mode(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("STRIX_LLM", "persisted-model") + target = tmp_path / "cli-config.json" + loader.apply_config_override(target) + + loader.persist_current() + + assert target.stat().st_mode & 0o777 == 0o600 diff --git a/tests/test_image_pull_policy.py b/tests/test_image_pull_policy.py index a9184833..3c46d46f 100644 --- a/tests/test_image_pull_policy.py +++ b/tests/test_image_pull_policy.py @@ -1,4 +1,4 @@ -r^fئ{O,y'vî"""Regression tests for sandbox image acquisition policy.""" +"""Regression tests for sandbox image acquisition policy.""" from __future__ import annotations