Runtime backends and sessions
The runtime layer gives each scan an isolated sandbox for code, tools, and proxy traffic. It selects a sandbox backend, prepares the scan workspace, starts the Caido proxy service, reports bring-up progress, and releases the resources when the scan ends. This page is a child of Scan execution lifecycle and relates to Runner lifecycle and scan inputs.
Runtime boundary
The runtime boundary separates scan control from the environment in which the agent acts. The scan runner asks the session manager for one runtime bundle per scan, then passes that bundle to the agent execution system.
The bundle gives the scan:
- A backend client that manages the sandbox.
- A sandbox session that runs commands and exposes ports.
- A Caido client handle for proxy tools.
The scan uses the same bundle for the root agent and its child agents. This keeps their work inside one scan-owned environment while their model histories remain separate.
Backend selection
Backend registry
The backend registry maps a runtime name to the factory that creates a sandbox. The configured name is matched exactly, so a bad name stops startup instead of silently selecting another runtime. Docker is the built-in choice, and downstream users can register another backend before session creation.
Each backend also declares whether it can see the caller's filesystem. This declaration controls whether local source is mounted into the sandbox or sent as runtime input.
| Backend capability | Source delivery |
|---|---|
| Bind mounts | Local source trees remain on the host and are mounted into the sandbox. |
| No bind mounts | Local source trees are materialized in the sandbox as runtime input. |
References: strix/…/backends.py• L20-106
Docker runtime
The Docker backend creates and starts a sandbox from the selected image. It connects through DOCKER_HOST when set, then through the active Docker context, or finally through the default Docker socket. A connection failure identifies the selected endpoint and its underlying cause so startup errors point to the Docker service that must be fixed.
The Docker client keeps the image entry point active so the image can start its sidecar services. It also adds the network access needed by security tools and by applications served on the host. The runtime can apply host-level controls for network choice, CPU, memory, shared memory, process count, and host device access. Container logs have a bounded default size so a noisy tool does not fill the host disk. Optional run labels link containers to the current Strix run for host-side tracking.
When a scan needs local source, the Docker client adds the session manager's bind mounts after the base image mounts. It preserves the mount order from shallow paths to deeper paths so a nested source mapping can cover the part of the workspace it owns. If a custom Docker network is used, exposed ports are resolved through the container's address on that network instead of through host port bindings.
These controls shape the resource and network boundary around an autonomous scan without changing the scan's agent flow. The image entry point remains part of that boundary because it starts Caido and prepares the in-container trust setup before the keep-alive command runs.
References: strix/…/backends.py• L20-51 strix/…/docker_connection.py• L15-89 strix/…/docker_client.py• L54-188 strix/…/docker_client.py• L191-320
Sandbox provisioning
Workspace boundary
The session manager maps each approved local source into the sandbox workspace. It can protect source metadata with read-only mounts, and it places supplied extra files only below the workspace root. Unsafe paths and paths that collide with a source tree or another extra file are skipped. This gives the agent a stable view of scan inputs while preventing input paths from escaping the sandbox or replacing a source tree.
The source delivery path follows the selected backend. Docker uses host mounts for local sources. Extra files use a single archive that is uploaded and unpacked inside the sandbox, so they remain writable by the agent. A backend without mount support receives local sources as sandbox-managed entries instead.
References: strix/…/session_manager.py• L64-87 strix/…/session_manager.py• L90-219 strix/…/session_manager.py• L224-239 strix/…/backends.py• L78-101
Caido runtime
Caido runs as a sidecar inside the sandbox and receives the scan's HTTP and HTTPS traffic through the sandbox environment. The session manager exposes the sidecar endpoint, then creates a host-side client that the proxy tools use for captured traffic, replay, sitemap, and scope operations.
The provisioning flow connects the two sides of this boundary:
- The sandbox starts the Caido sidecar.
- The bootstrap process checks the guest endpoint until it can obtain a guest token.
- The host-side client connects to the exposed endpoint.
- A fresh temporary Caido project is created and selected for the scan.
The following diagram shows how a scan moves from backend selection to an agent-ready runtime.
flowchart LR
A[Scan request] --> B[Select backend]
B --> C[Create and start sandbox]
C --> D[Prepare workspace]
C --> E[Start Caido sidecar]
E --> F[Bootstrap host-side Caido client]
D --> G[Runtime bundle]
F --> G
G --> H[Run agents]
References: strix/…/session_manager.py• L297-350 strix/…/caido_bootstrap.py• L1-8 strix/…/caido_bootstrap.py• L32-78 strix/…/caido_bootstrap.py• L81-115
Startup status
Runtime bring-up reports short-lived phase messages through an optional status sink. The runner can surface these phases before the first model response so a user can tell whether the scan is creating its sandbox, preparing its workspace, setting up its proxy, or waiting for the agent to start.
The runtime reports these phases in order. The workspace phase appears only when extra files are present:
Starting sandbox containerPlacing workspace filesSetting up the proxyWaiting for the first model response— reported by the scan runner after the runtime bundle is ready.
These messages describe startup progress. They do not replace the agent status and lifecycle state maintained by the scan coordinator.
References: strix/…/status.py• L1-8 strix/…/session_manager.py• L276-285 strix/…/session_manager.py• L325-347 strix/…/runner.py• L234-243
Session management
Session reuse
The session manager owns the scan-to-runtime relationship. It caches the runtime bundle by scan ID, returns that bundle on later requests, and avoids creating a second sandbox for the same scan. This supports a resumed or repeated entry into the same in-process scan without duplicating its container or proxy resources.
Caido setup starts in parallel with the rest of scan startup. The runtime can therefore become available as soon as the sandbox is ready, while the proxy client is resolved only when a proxy operation first needs it. A caller timeout does not cancel the shared Caido setup for other callers.
References: strix/…/session_manager.py• L33-38 strix/…/session_manager.py• L257-283 strix/…/session_manager.py• L347-369 strix/…/caido_handle.py• L1-42
Resource release
Cleanup removes the scan from the cache, closes the Caido client or cancels its unfinished setup, deletes the sandbox through the backend, and closes the Docker client when one exists. Extra files do not need a separate host staging directory because the session uploads and removes their archive inside the sandbox. The scan runner performs this cleanup in its final shutdown path when cleanup_on_exit is enabled.
Docker teardown first makes a best-effort attempt to stop the container. It treats a missing container, a Docker API error, and a broken daemon connection as teardown conditions rather than new scan failures. Cleanup remains best effort: a failure to kill or delete a container is logged so it does not block the next scan, but the container may remain until normal Docker reaping removes it. The runner closes agent history sessions before runtime cleanup so no active child still depends on a resource that is being torn down.
References: strix/…/session_manager.py• L372-378 strix/…/session_manager.py• L380-416 strix/…/caido_handle.py• L50-60 strix/…/docker_client.py• L297-320 strix/…/runner.py• L471-486
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the backend capability declaration aligned with how local sources and extra files reach the sandbox.
- Keep workspace path validation and collision rules aligned between local source entries and uploaded extra files.
- Keep extra-file upload and extraction failure handling paired with half-started session cleanup.
- Keep the exposed Caido port, sandbox proxy environment, and endpoint resolution contract aligned across the session manager, runtime image, and bootstrap flow.
- Preserve the scan-ID cache and cleanup pairing so a reused scan does not create duplicate runtimes or leave its proxy client open.
- Keep startup phase names aligned with the caller that displays them. They are progress signals, not agent lifecycle states.
- If the Docker client behavior changes, re-check image entry-point startup, host reachability, security-tool network access, device pass-through, resource and log limits, custom-network port resolution, run labels, and teardown behavior together.
- Keep Docker endpoint precedence and connection error reporting aligned with the Docker client construction path.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
STRIX_RUNTIME_BACKEND names an unregistered backend. | Scan startup fails before a sandbox is created. | Backend lookup rejects unknown names instead of falling back. |
DOCKER_HOST points to an unreachable daemon, or the selected Docker context is missing or unavailable. | Scan startup fails with the selected endpoint and its root cause. | Endpoint resolution uses a defined precedence order and wraps connection errors with endpoint details. |
| The Docker image does not start its entry point or the Caido listener is not ready. | Proxy bootstrap cannot obtain a token and proxy tools report that the client is unavailable. | Docker keeps the image entry point active, and bootstrap retries the guest login. |
| A selected custom network does not contain the sandbox after it starts. | Exposed application ports cannot resolve to a usable endpoint. | The Docker session resolves the container address on the selected network and reports a backend-unavailable error when none exists. |
| A proxy caller times out while shared Caido setup is still running. | That caller stops waiting, but the shared setup remains usable for later callers. | The Caido handle shields the bootstrap task from caller cancellation. |
An extra-file path is outside /workspace or collides with a source or earlier extra file. | The extra file is skipped and is not available at the requested path. | The session manager validates paths and rejects collisions before it creates an archive entry. |
| Upload or extraction of the extra-file archive fails after the sandbox starts. | Session creation fails and the half-started sandbox is discarded instead of entering the session cache. | The session manager tears down the client and session before it re-raises the staging error. |
| A tunnel needs a host device that is not passed into the sandbox. | The tunnel cannot open its device even when its network capability is present. | Device pass-through is configured explicitly for the Docker runtime. |
| Sandbox deletion or the Docker daemon fails during cleanup. | The scan can finish, but a container or client may remain until it is reaped. | Cleanup logs and swallows teardown errors after attempting client closure and deletion. |
Key files
| File | Why to read it |
|---|---|
| strix/…/backends.py | Defines backend selection, registration, and the source-delivery capability boundary. |
| strix/…/docker_connection.py | Explains how the runtime chooses a Docker endpoint and reports connection failures. |
| strix/…/session_manager.py | Owns per-scan sandbox creation, workspace setup, extra-file placement, Caido attachment, cache reuse, and cleanup. |
| strix/…/docker_client.py | Shows the Docker runtime boundary and the resource, network, entry-point, mount, labeling, port, and teardown guarantees. |
| strix/…/caido_bootstrap.py | Explains how the in-sandbox sidecar becomes a usable host-side proxy client. |
| strix/…/caido_handle.py | Defines delayed Caido readiness and safe cancellation or closure. |
| strix/…/runner.py | Shows where the scan obtains the runtime bundle and where it releases it during shutdown. |