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.
- 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). - 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. - Agents (
strix/agents/) —factory.py(build_strix_agent()— assembles one agent's tools + model config),prompt.py(render_system_prompt()— Jinja2 rendering ofprompts/system_prompt.jinjaagainst a resolved skill list). - 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-nativeShell/Filesystemcapabilities (exec_command,apply_patch,view_image) configured infactory.py. - 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,dockerby default),status.py. - 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). - Config & model routing (
strix/config/) —settings.py/loader.py(env-var-first settings, cached;~/.strix/cli-config.jsonas a persisted cache of resolved env values, not a hand-authored config),models.py(StrixProvider, a LiteLLM-backedMultiProviderplus customModelwrappers 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.