Interactive terminal and viewer interfaces
Strix gives an operator two connected ways to follow a scan: an interactive terminal interface for setup and live control, and a local browser viewer for richer run inspection. The terminal and viewer use the same run state, so the operator can move from command-line setup to live agent activity and then to stored findings without changing the scan context. The wider command journey is described in Command-line scan experience, and launch preparation is described in CLI launch and scan setup.
Interface roles
The terminal is the control surface for starting work and acting on a live scan. The viewer is the inspection surface for reading the agent graph, findings, reports, and run history.
| Interface | Main purpose | Access to live control |
|---|---|---|
| Interactive terminal | Set up a scan, follow agent activity, send messages, stop agents, and open the viewer. | Always available while the terminal remains connected. |
| Local viewer | Inspect a live or finished run in a browser. | Available only when opened from the live terminal process. |
strix view | Serve the latest or named run as a local viewer. | Read-only for standalone or finished runs. |
Interactive terminal interface
The interactive terminal presents scan setup and scan activity as one continuous workspace. It shows the conversation or tool trace in the main pane, agent state and findings in the side pane when the terminal is wide enough, and a message composer for setup input or agent guidance.
The terminal starts in one of two modes:
- Setup mode accepts a free-form prompt. Target-like words become targets and the remaining text becomes the scan instruction.
- Live mode shows the scan trace and lets the operator work with the selected agent.
Setup interaction
Setup interaction turns one prompt into scan intent without requiring a separate form or slash-command menu. Target-shaped words become targets and the remaining text becomes the scan instruction. A leading slash is ordinary prompt text. The backend verifies the model before launch, so a failed check remains visible on the start screen and can be retried.
A prompt with no target enters the live view and asks whether to mount the current working directory as extra workspace access. Mount gives the agent writable workspace access without making the directory a scan target. Skip starts the scan without that extra workspace. Either answer continues the run, and no scan preparation begins before the answer.
The dedicated start screen keeps the model, budget, targets, and recent feedback near the prompt. Preparation can continue after the terminal is visible, so model and launch failures remain visible without hiding the input needed to correct them. The runtime performs model preflight and scan preparation behind the painted terminal, then starts the scan only after those steps succeed.
References: strix/…/setup.go• L15-63 strix/…/setup.go• L511-521 strix/…/controller.py• L318-389 strix/…/runtime.py• L127-209
Live scan workspace
Live mode joins scan state with the agent conversation. Selecting an agent changes which event stream appears in the trace, while the agent tree shows parent-child work and each agent's status. Findings appear in a separate list when the scan produces them.
Tool output is readable in the trace without allowing one large command result to take over the screen. Output-heavy tools show a short preview and can be expanded. Shell output also reports non-zero exit codes so the trace distinguishes command failure from normal output.
The side pane can show viewer status, the agent tree, findings, usage information, and the status of configured MCP connections. MCP means the Model Context Protocol, which lets the scan use tools from named external connections. Each connection shows its tool count and whether its session is offline. A running MCP call shows activity on its connection.
The sidebar panels can collapse, expand, or zoom. The operator can also hide the sidebar when the terminal is wide enough and restore it from a small rail. The model and usage panel stays available at the bottom while the other panels change size.
The viewer entry opens the browser surface for the same run. Coverage and threat-model tools use structured renderers so the trace shows recorded surfaces, model changes, and their outcomes instead of raw result data. Vulnerability report output also shows evidence that helps the operator judge confidence, severity, and fix verification. A wait_for_user event marks that the agent has handed the turn to the operator; old respond_to_user records still display their message followed by the same waiting state. Runtime callbacks refresh the screen when events, findings, usage, agent state, or MCP connection status changes.
References: strix/…/view.go• L495-639 strix/…/panels.go• L36-81 strix/…/panels.go• L220-310 strix/…/agents.go• L140-203 strix/…/registry.go• L46-122 strix/…/wait_user.go• L9-24 strix/…/report.go• L54-125 strix/…/controller.py• L137-153 strix/…/runtime.py• L254-277
Terminal controls
The controls let the operator move between input, trace, agents, findings, and MCP connections without leaving the scan. Mouse actions support pane selection, scrolling, scrollbar dragging, text selection, panel controls, and tool expansion.
| Control | Result |
|---|---|
Enter | Launch the setup prompt, send a live message, open a selected finding, or expand an agent branch. |
Space | Expand or collapse the selected agent branch. |
Shift+Enter, Alt+Enter, Ctrl+J | Add a new line to the composer. |
Tab / Shift+Tab | Move focus between usable panes. Collapsed, hidden, or squeezed panels are skipped. |
Up / Down | Move through agents, findings, or the MCP roster. |
Page Up / Page Down, Home, End | Move through the trace, findings, or MCP roster. |
Esc | Open the stop prompt for a running, waiting, or budget-paused agent during a scan. In the mount prompt, it selects Skip. |
Ctrl+O | Open the local viewer in a browser. |
F1 | Show the help panel. |
Ctrl+Q or Ctrl+C | Quit, with confirmation during a live scan. |
The terminal follows new trace output while the operator is at the bottom. Manual scrolling turns that behavior off until the operator returns to the bottom. A finding detail view supports previous and next navigation, scrolling, and copying the finding text.
References: strix/…/update.go• L11-153 strix/…/update.go• L156-300 strix/…/panels.go• L226-310 strix/…/vulnerabilities.go• L416-541
Backend protocol
The terminal is a separate client process from the Python scan runtime. The backend owns scan state and command effects. The Go terminal owns layout, focus, rendering, and input handling. A private versioned protocol connects them so neither side needs to share its UI code.
The main exchange is:
sequenceDiagram
participant Runtime as Scan runtime
participant Backend as TUI backend
participant Terminal as Go terminal
Runtime->>Backend: State and event changes
Backend->>Terminal: Versioned state and collection frames
Terminal->>Backend: Setup or live command
Backend->>Runtime: Start, message, stop, or quit action
Backend-->>Terminal: Correlated command result
Connection and handshake
The runtime launches the terminal sidecar and gives the backend a private connected socket. On systems that can pass file descriptors, the terminal uses the inherited connection. On Windows, it uses a one-use loopback connection with a token. The transport does not expose a general listener for the terminal protocol.
Each message is a length-framed JSON envelope. The client and backend must agree on protocol version 3 and on the capability set before the terminal enters its alternate screen. The capability set includes revisioned state, collection deltas, structured command errors, and the agents collection. A mismatch fails before the operator sees a partially active interface. While the alternate screen is active, Python output is redirected away from the real terminal so scan logs do not overwrite the TUI.
References: strix/…/runtime.py• L405-458 strix/…/sidecar.py• L45-57 strix/…/sidecar.py• L72-177 strix/…/model.go• L323-357
State and collection updates
Small control state travels as revisioned snapshots. The snapshot also carries bounded run context such as model use, usage, viewer state, and the non-secret MCP connection roster. Larger histories use three named collections: agents, events, and vulnerabilities. The backend sends an initial collection bootstrap in bounded frames, then sends deltas when items change.
The terminal checks revisions, cursors, item identities, and event versions before applying an update. If the stream is out of order or incomplete, it requests a collection resync instead of displaying a mixed view. This keeps the agent tree, trace, findings, and connection activity aligned while a scan is active.
References: strix/…/controller.py• L175-283 strix/…/model.go• L32-42 strix/…/model.go• L341-368 strix/…/model_test.go• L137-257 strix/…/runtime.py• L254-331
Command lifecycle
Terminal actions use request IDs and return structured command results. The supported command groups cover setup changes, scan start and mount consent, agent messages, agent stop, viewer opening, and application quit. A target-less start verifies the model first, then enters the live view and waits for Mount or Skip before preparing the run. Only one matching request may release a pending command, which prevents a late or unrelated result from changing the interface.
The backend rejects unknown commands and invalid payloads with an error code, message, and retry hint. It also limits control messages and collection frames so a large trace or finding cannot block the control path. The runtime supervises scan completion and failure, then exposes the final state to the terminal before it closes the backend and child process.
References: strix/…/controller.py• L285-437 strix/…/controller.py• L439-510 strix/…/runtime.py• L211-252 strix/…/runtime.py• L372-458
Viewer command surface
The viewer is a local web interface for the run selected by the terminal or by strix view. It presents a run overview, severity summary, run configuration, agent graph, transcripts, findings, reports, and feedback actions in one browser page.
Viewer launch commands
strix view serves the most recent run by default. A run name selects a specific run under strix_runs. The command can choose a port and bind host, can avoid opening a browser, and stays active until the operator stops it.
The viewer also starts from the terminal with Ctrl+O. In that case it shares the live scan process and can send guidance to running agents. A standalone viewer can read the run but cannot control the scan.
The command prints the tokened URL and warns that anyone with the link can steer a live scan and browse history. The link is therefore an access credential, not only a local address.
| Command or action | Purpose |
|---|---|
strix view | Open the most recent run. |
strix view <run> | Open a named run. |
--port <number> | Request a fixed port. The default uses an available port. |
--host <address> | Choose the bind address. The default is loopback. |
--no-open | Serve the viewer without opening a browser. |
Ctrl+O in the terminal | Start or reopen the viewer for the active run. |
References: strix/…/cli.py• L31-107 strix/…/controller.py• L439-494
Run inspection
The viewer chooses Agents as the first view for a live run once agents exist. It chooses Pentest Overview for a finished run. The operator can then switch between the overview, issues, agents, and past runs from the navigation rail. The overview combines run details, severity counts, report sections, and a finished-run option to export an encrypted PDF report.
The issues view groups findings by severity. A finding detail view separates the summary and impact from fix guidance and reproduction evidence. The agents view turns the agent hierarchy into a graph and opens a selected agent's full transcript in a modal. Live transcripts route tool events by tool family and keep older tool names readable. Calls from user MCP servers remain distinct from built-in tools.
The live transcript marks wait_for_user as a handoff to the operator. Historical respond_to_user events use the same viewer renderer, so old runs keep their message and waiting marker without requiring a second user-facing behavior. The viewer also shows short links for features that belong to Strix Cloud or Enterprise. These links open outside the local viewer and do not change local run data or local scan control.
References: strix/…/App.tsx• L195-224 strix/…/App.tsx• L395-423 strix/…/App.tsx• L662-733 strix/…/App.tsx• L777-846 strix/…/RunDetails.tsx• L51-103 strix/…/VulnerabilityDetail.tsx• L166-245 strix/…/index.ts• L103-157 strix/…/WaitForUserRenderer.tsx• L7-21 strix/…/ProCta.tsx• L40-88 strix/…/UpgradeModal.tsx• L30-161
Live steering
Live steering is a browser prompt that sends an instruction to the root agent or to a running child agent. The prompt appears only when the viewer is connected to the live terminal runtime. The browser hides it for finished runs and for standalone strix view sessions.
The operator can select a running child from the target control, type a message, and press Enter or Send prompt. If the target finishes before delivery, the viewer reports that the message was not delivered instead of treating it as accepted.
References: strix/…/App.tsx• L66-95 strix/…/App.tsx• L751-787 strix/…/ScanPromptComposer.tsx• L48-138 strix/…/server.py• L430-455
History and report actions
Past runs are shown as a count before verification and as a full list after verification. Each listed run includes its target, mode, time, status, and severity counts. Selecting a run reloads the same overview, transcript, and findings surfaces for that run.
The viewer can send an encrypted PDF report only after a run finishes. The report carries the full finding detail, including proof-of-concept material, and the local browser receives the password needed to open it. It can also collect feedback through the local server. These actions keep their network requests behind the viewer session and use the local run data as their source.
References: strix/…/App.tsx• L225-232 strix/…/App.tsx• L433-485 strix/…/PastRunsView.tsx• L79-175 strix/…/serverSource.ts• L172-250 strix/…/server.py• L356-425 strix/…/report_pdf.py• L636-697
Viewer data and trust boundary
The viewer server serves the built browser assets and reads run records from disk. The browser polls the local JSON surface while a run is live, then makes one final full read when the run reaches a terminal state. The same surface serves live and finished runs; the finished value tells the browser when to stop polling.
Local data surface
The main read endpoints map to one user need each:
| Endpoint | Information or action |
|---|---|
GET /api/run | Run summary and finished state. |
GET /api/transcript | Agent graph and chat or tool events. |
GET /api/vulnerabilities | Current findings. |
GET /api/report | Stored report markdown. |
GET /api/runs | Run history summary and severity counts. |
GET /api/capabilities | Whether live steering is available. |
POST /api/agents/steer | Send a live agent instruction. |
POST /api/report/send | Send a finished-run report for export. |
POST /api/feedback | Send viewer feedback. |
Run data is read from the selected run directory. Missing live artifacts produce an empty or partial view until the scan writes them.
References: strix/…/server.py• L1-13 strix/…/transcript.py• L42-87 strix/…/serverSource.ts• L63-105
Session authorization
The server prints and opens a tokened URL for the operator. The first page load exchanges that token for a process-specific, HTTP-only session cookie. Run data and mutating actions require that cookie, so reaching an exposed port or loading the bare URL does not grant access.
Binding the viewer to a non-loopback host makes the tokened URL a sharing capability. Anyone who receives that authorized link can inspect the run and, when the viewer is attached to a live scan, steer it. Operators should treat the link as sensitive.
References: strix/…/server.py• L117-145 strix/…/server.py• L237-287 strix/…/server.py• L480-525 strix/…/server.py• L551-581
History verification
The run used to launch the viewer is available to the session holder without email verification. Other runs and the full history list need both the session cookie and a valid verified-email record. This keeps the local history gate separate from access to the active run.
Verification uses a one-time code and stores an expiry. An expired or incomplete record is treated as unverified, so the viewer asks the operator to verify again rather than unlocking history indefinitely.
References: strix/…/server.py• L81-107 strix/…/server.py• L243-275 strix/…/PastRunsView.tsx• L88-123 tests/test_viewer_auth.py• L48-99
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the protocol version, capability list, frame limits, and both the Python and Go envelope definitions aligned.
- Keep collection identity, revision, cursor, item version, and resync rules aligned between the backend stream and terminal update logic.
- Keep each terminal command name and payload aligned with its backend handler and with the control that invokes it.
- Keep target-less setup aligned across prompt parsing, model preflight, pending mount state, the Mount/Skip prompt, and scan preparation.
- Keep panel height, focus order, mouse hit areas, collapse state, zoom state, and hidden-sidebar behavior aligned when sidebar panels change.
- Keep the MCP connection roster fields, running-call tags, and dead-connection meaning aligned between run state, terminal rendering, and tool-event rendering.
- Keep the viewer's
finishedrule aligned with run status and end time so live polling stops only after the run is complete. - Keep the viewer's run selector,
?run=handling, history gate, and all run-scoped endpoints on the same path boundary. - Keep the live-steering capability check aligned across the in-process TUI launcher, viewer server, and browser prompt.
- Keep the token bootstrap and session-cookie checks in place for every run read and mutating viewer action.
- Keep coverage outcome names aligned between agent tool results and the terminal's outcome markers so closed and open surfaces remain distinct.
- Keep tool-family names, legacy aliases, per-tool overrides, MCP connection tags, and user-handoff renderers aligned between terminal events and viewer transcript rendering.
- Keep report calibration fields such as confidence, counterevidence, severity conditions, and fix verification aligned across report state, terminal rendering, viewer findings, and PDF export.
- Keep the PDF export's full-detail content and password handoff aligned with the finished-run gate and the local session boundary.
- Keep the generated asset names in index.html aligned with the renamed JavaScript and CSS files in the viewer bundle.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| TUI protocol version or capability set differs | The terminal exits before the interactive screen starts. | Both sides negotiate version 3 and the exact capability list. |
| Backend socket closes during a scan | The terminal reports a backend disconnect and quits. | The client treats a broken wire as fatal rather than showing stale controls. |
| Model preflight or scan preparation fails | The operator sees an error instead of a partially started scan. | The runtime performs preparation behind the visible setup screen and records the failure in the controller. |
| A target-less scan receives no mount answer | The run stays in preparation and does not start. | The live view keeps a pending Mount/Skip prompt until the backend receives an answer. |
| A panel control is handled at a different height or focus order than it is drawn | A click or Tab action changes the wrong panel or hides the active focus. | Derive panel rectangles and focus order from the same panel state. |
| An MCP session dies after setup | The run loses access to that connection's tools, even though other connections may remain usable. | The engine publishes the full roster with the dead connection marked for the terminal and viewer. |
| Viewer bundle is missing or index.html points to an old asset name | strix view fails, or the browser opens a blank or broken viewer. | Build the viewer and keep its generated asset references aligned. |
| A browser reaches the viewer without the tokened bootstrap URL | Run data and POST actions return forbidden. | The server issues a session cookie only for the correct token. |
| A session requests another run without verified email | Historical run data stays locked. | The server applies the verification gate to every non-active run. |
| A standalone viewer tries to steer an agent | The request is refused because no live coordinator is attached. | Capabilities report steering only for the in-process live viewer. |
| Report export is requested while a scan is live | The server refuses to send a partial report. | Report sending requires the run's finished state. |
| Collection frames arrive with a bad cursor or base revision | The terminal does not apply the incomplete collection. | The client requests a full collection resync. |
| A coverage result uses an unrecognized or missing outcome | The terminal falls back to a neutral marker, which can hide the meaning of the surface state. | Keep coverage outcomes in the shared tool contract and the terminal outcome map aligned. |
Key files
| File | Why to read it |
|---|---|
| strix/…/runtime.py | Shows how the scan runtime launches and supervises the terminal sidecar, prepares the scan, synchronizes agent and connection state, and closes the live session. |
| strix/…/sidecar.py | Explains how the terminal process receives a private authenticated connection and how its environment and lifetime are controlled. |
| strix/…/controller.py | Defines the terminal state and the commands that change setup, mount consent, agents, viewer state, and shutdown. |
| strix/…/server.py | Explains the private protocol connection, state broadcasts, collection streams, and command results. |
| strix/…/protocol.py | Defines the shared protocol version, capabilities, envelope shape, and frame limits. |
| strix/…/protocol.go | Shows the terminal-side message contract for state, collections, connections, and command results. |
| strix/…/setup.go | Shows free-form prompt parsing, target-less launch consent, and the setup screen. |
| strix/…/update.go | Maps keyboard and mouse controls to terminal behavior. |
| strix/…/panels.go | Shows sidebar panel focus, collapse, zoom, and hidden-sidebar behavior. |
| strix/…/view.go | Shows the terminal layout, trace, side panels, viewer status, MCP roster, and scan statistics. |
| strix/…/agents.go | Shows the agent hierarchy, selection, status display, and finding counts. |
| strix/…/vulnerabilities.go | Shows finding selection, detail navigation, scrolling, and copy behavior. |
| strix/…/registry.go | Shows how terminal tool events resolve to structured renderers and bounded previews. |
| strix/…/wait_user.go | Shows how current and recorded user-handoff events appear in the terminal trace. |
| strix/…/report.go | Shows which finding fields the terminal exposes for review and calibration. |
| strix/…/wire.go | Shows how revisioned state, collection updates, command results, and resyncs reach the screen. |
| strix/…/cli.py | Defines the strix view command and its run-selection and server options. |
| strix/…/server.py | Defines the local HTTP surface, session boundary, history gate, and live steering bridge. |
| strix/…/transcript.py | Maps persisted run records into the viewer's summary, transcript, report, and finding data. |
| strix/…/App.tsx | Shows viewer navigation, live polling, run switching, report export entry points, and the main inspection views. |
| strix/…/index.ts | Shows the viewer's tool-family routing, legacy aliases, overrides, and user-handoff event handling. |
| strix/…/WaitForUserRenderer.tsx | Shows the shared viewer treatment for current wait_for_user and recorded respond_to_user events. |
| strix/…/serverSource.ts | Defines the browser-to-server data and action surface. |
| strix/…/PastRunsView.tsx | Explains history verification and switching between local runs. |
| strix/…/ScanPromptComposer.tsx | Explains the browser control for steering a live agent. |
| strix/…/report_pdf.py | Shows how a finished run becomes a full-detail encrypted PDF report. |
| strix/…/index.html | Connects the served viewer page to the current built browser assets. |