Strix (STRIX) — High-Level Design

docs / design / HLD

Strix — High-Level Design (HLD)

Technical audience: reviewers, architects, senior engineers.

Seven layers

Strix's strix/ package decomposes into seven layers. Layer numbers reflect call direction under normal operation (top calls into the layer below), not a strict dependency ordering — several packages call back upward (e.g. strix.report and strix.tools both call into strix.interface for live display callbacks), which ../../diagrams/04_module_dependencies.svg shows as real bidirectional edges rather than a clean DAG.

  1. Interface (strix/interface/) — CLI entry (main.py, cli_args.py), the headless runner (cli.py), the Go-based interactive TUI (tui/), and the local read-only web dashboard (viewer/, strix view).
  2. Core orchestration (strix/core/) — runner.py (run_strix_scan(), the single top-level entry point every mode funnels into), agents.py (AgentCoordinator, the sole owner of multi-agent graph state), execution.py (run_agent_loop, spawn_child_agent — the per-agent turn driver), hooks.py (budget/turn enforcement), inputs.py, sessions.py, paths.py.
  3. Agents (strix/agents/) — factory.py (build_strix_agent() — assembles one agent's tools + model config), prompt.py (render_system_prompt() — Jinja2 rendering of prompts/system_prompt.jinja against a resolved skill list).
  4. Tools (strix/tools/) — everything an agent can call: proxy/ (Caido traffic inspection), agents_graph/ (create_agent, wait_for_agents, agent_finish — the actual orchestration primitives), reporting/ (create_vulnerability_report), notes/, todo/, web_search/, thinking/, load_skill/, finish/ (finish_scan), plus SDK-native Shell/Filesystem capabilities (exec_command, apply_patch, view_image) configured in factory.py.
  5. Runtime (strix/runtime/) — session_manager.py (sandbox lifecycle), docker_client.py (StrixDockerSandboxClient, a subclassed Agents-SDK Docker backend), caido_bootstrap.py (proxy sidecar login), backends.py (pluggable backend registry, docker by default), status.py.
  6. Findings (strix/report/) — state.py (ReportState, the in-memory + on-disk source of truth for one run), dedupe.py (LLM-judged duplicate detection), writer.py (Markdown/CSV/JSON artifact writer), sarif.py (SARIF 2.1.0 export), pricing.py / usage.py (cost tracking).
  7. Config & model routing (strix/config/) — settings.py / loader.py (env-var-first settings, cached; ~/.strix/cli-config.json as a persisted cache of resolved env values, not a hand-authored config), models.py (StrixProvider, a LiteLLM-backed MultiProvider plus custom Model wrappers for provider quirks).

Two supporting trees sit alongside these: strix/skills/ (markdown knowledge packs loaded into agent prompts — see STRIX — Backends and tools/graph-intelligence.md for how they differ from the top-level repo skills/), and strix/telemetry/ / strix/llm/ / strix/utils/ (cross-cutting concerns: usage logging, prompt compaction/context-budget management, path/secret-file helpers).

The orchestration core, precisely

run_strix_scan() (core/runner.py) is the one function every entry point (CLI, TUI, and — indirectly — the managed cloud platform's engine) calls to actually run a scan. Per scan it: resolves the LLM model and settings, creates or reuses an AgentCoordinator, brings up one shared Docker sandbox for the whole scan (runtime.session_manager.create_or_reuse), builds the root agent (agents.factory.build_strix_agent(is_root=True, ...)), registers it with the coordinator, and awaits core.execution.run_agent_loop(...) for that root agent. Any create_agent tool call from within a running agent triggers execution.spawn_child_agent(), which builds a new SandboxAgent from a captured child factory and launches its own run_agent_loop() as an independent asyncio.Task — children run fully in parallel, sharing the one sandbox container and its live Caido proxy session.

AgentCoordinator is deliberately the only piece of mutable cross-agent state: parent/child relationships (parent_of), live status per agent, and — critically — a mailbox model for inter-agent communication (coordinator.send() appends to a target's mailbox and wakes it; there is no direct call graph between agent tasks). A child reports results back to its parent by calling agent_finish(), which renders a structured completion report and sends it to the parent's mailbox — the parent typically discovers it via the blocking wait_for_agents tool. This mailbox indirection is what makes the system resumable: the whole coordinator state (including queued, undelivered mailbox messages) is periodically snapshotted to agents.json, so strix --resume <run> can reconstruct the entire agent tree — even mid-conversation — after a crash or an intentional stop (e.g. budget exhausted).

Where the AI is, and where it isn't

Deterministic (no model call) AI-driven
Sandbox creation, Docker container config, Caido proxy bootstrap Every actual testing decision — what to probe, which payload to try, when a finding is "real"
Mailbox routing, coordinator state snapshotting/resume Deduplication judgment (report/dedupe.py — an explicit LLM call, not a hash)
CVSS arithmetic once metrics are supplied, SARIF/Markdown rendering, report file writing Choosing CVSS metric values, writing the vulnerability narrative, PoC scripts
Budget/turn-limit enforcement (core/hooks.py) The root agent's decomposition of the target into specialist tasks
Output truncation/spilling (tools/output_store.py) Everything the web_search tool retrieves and how it's used

Model routing

There is no fixed model hard-coded anywhere in strix/. STRIX_LLM (a LiteLLM-style model id, e.g. anthropic/claude-sonnet-4-6, openai/gpt-5.4, bedrock/..., vertex_ai/...) is resolved once per scan in runner.py via config.load_settings() and threaded through a single RunConfig(model=resolved_model, model_provider=StrixProvider()) shared by the root and every child agent for that scan — i.e. every agent in one scan uses the same model; there is no per-role model selection. strix/config/models.py's StrixProvider subclasses the OpenAI Agents SDK's MultiProvider, which is LiteLLM-backed, so the full LiteLLM provider surface is available (see docs/llm-providers/ in the source repo for the officially documented ones). Separately, report/dedupe.py's duplicate-check LLM call can use a distinct, smaller model via DedupeSettings (STRIX_DEDUPE_MODEL) — the one deliberate exception to "one model per scan," because deduplication is a narrower, cheaper judgment task than the main agent loop.

Third-party agent runtime: the OpenAI Agents SDK

Strix does not implement its own agent-loop primitives from scratch — it builds on the OpenAI Agents SDK (from agents import ...), specifically its sandbox extension (agents.sandbox.SandboxAgent, SandboxRunConfig, Filesystem/Shell capabilities). agents.factory.build_strix_agent() constructs one SandboxAgent per agent instance; core.execution.run_agent_loop() drives it via the SDK's Runner.run_streamed(). Vendor choice is not user-configurable at this layer — it's a hard dependency, not a pluggable adapter (unlike the LLM model, which is fully pluggable via STRIX_LLM). The SDK provides the turn loop, streaming event protocol, tool-calling machinery, and the Filesystem/Shell sandbox capability abstractions that Strix's Docker backend implements against (strix/runtime/docker_client.py). Strix layers its own multi-agent coordination (AgentCoordinator, mailboxes, resume snapshots), budget/turn enforcement (core/hooks.py), and lifecycle-tool stop conditions (_finish_tool_use_behavior in agents/factory.py) on top of the SDK's single-agent primitives — the SDK itself has no native concept of a tree of agents.

Related: STRIX — Architecture (HLD), STRIX — Backends, LLD.md, data-flow.md.