How to Configure Docker Runtime and Sandbox Container Settings for Strix

Strix controls its Kali Linux Docker sandbox through environment variables that specify the container image, Docker daemon endpoint, execution timeouts, and internal service ports, all processed at container startup via the entrypoint script.

Strix executes security scanning agents inside an isolated Kali Linux Docker sandbox defined in the official repository. The runtime behavior—from the container image selection to proxy configuration—is governed by environment variables injected at startup, as documented in docs/advanced/configuration.mdx and implemented in the bootstrap logic at containers/docker-entrypoint.sh.

Architecture and Core Configuration Variables

Strix's runtime architecture separates the control plane from the sandbox execution environment. The following variables determine how the runtime communicates with Docker and manages container lifecycle.

Sandbox Image and Runtime Backend

The sandbox image is defined by STRIX_IMAGE, which defaults to ghcr.io/usestrix/strix-sandbox:0.1.13 as specified in containers/Dockerfile. Override this variable to use custom images or specific semantic versions hosted in private registries.

The runtime backend is controlled by STRIX_RUNTIME_BACKEND (default docker). While the current implementation only supports Docker, this abstraction allows future extensibility to Podman or other container engines without code changes.

Docker Daemon Connection

By default, Strix connects to the local Docker socket. To target a remote daemon, set DOCKER_HOST to a TCP endpoint such as tcp://192.168.1.100:2375. This variable is read by the runtime client initialization and passed directly to the Docker SDK, enabling distributed scan execution across remote infrastructure.

Sandbox Timeouts and Resource Limits

Prevent runaway commands using timeout variables:

• STRIX_SANDBOX_EXECUTION_TIMEOUT (default 120 seconds): Maximum duration for a single tool invocation inside the sandbox.
• STRIX_SANDBOX_CONNECT_TIMEOUT (default 10 seconds): Maximum wait time for establishing a connection to the sandbox container.

These values constrain how long the tool server waits for binary execution before forcibly terminating the process, as implemented in the runtime polling logic.

Internal Services Bootstrap

The containers/docker-entrypoint.sh script orchestrates two critical subsystems at container start:

1. Caido HTTP Proxy: Launches automatically via caido-cli, creates a temporary project, and writes proxy variables to /etc/profile.d/proxy.sh, /etc/environment, and /etc/wgetrc. Requires the CAIDO_API_TOKEN environment variable for authentication.
2. Tool Server: Starts via poetry run python -m strix.runtime.tool_server (lines 62-68) and exposes installed security tools via a REST API at /tool_server. The port auto-generates unless overridden by TOOL_SERVER_PORT, while TOOL_SERVER_TIMEOUT inherits from STRIX_SANDBOX_EXECUTION_TIMEOUT.

The entrypoint also injects the Caido CA certificate into the user's NSS store (lines 48-52) so browsers trust the proxy automatically.

Practical Configuration Examples

Local Docker with Default Settings

Run Strix against a local target using the official sandbox image without custom configuration:

docker run --rm -it \
  -e STRIX_LLM="openai/gpt-4o-mini" \
  -e LLM_API_KEY="${LLM_API_KEY}" \
  ghcr.io/usestrix/strix-sandbox:0.1.13 \
  strix --target ./myapp

Remote Docker Daemon and Custom Image

Execute scans on a remote Docker host using a custom-built sandbox image:

export DOCKER_HOST="tcp://192.168.1.100:2375"

docker run --rm -it \
  -e DOCKER_HOST="${DOCKER_HOST}" \
  -e STRIX_IMAGE="myregistry.local/strix-custom:latest" \
  -e STRIX_LLM="anthropic/claude-3-5-sonnet" \
  -e LLM_API_KEY="${ANTHROPIC_KEY}" \
  usestrix/strix:latest \
  strix --target ./app

Extended Timeouts for Large Scans

Increase the execution window for comprehensive vulnerability assessments:

docker run --rm -it \
  -e STRIX_SANDBOX_EXECUTION_TIMEOUT=600 \
  -e STRIX_SANDBOX_CONNECT_TIMEOUT=30 \
  ghcr.io/usestrix/strix-sandbox:0.1.13 \
  strix --target ./large-scan

This configuration allows individual tools up to 10 minutes to complete before aborting.

Disabling Browser Automation

Skip Playwright and Chromium installation when browser-based tools are unnecessary:

docker run --rm -it \
  -e STRIX_DISABLE_BROWSER="true" \
  ghcr.io/usestrix/strix-sandbox:0.1.13 \
  strix --target ./no-browser

Custom Tool Server Port

Explicitly set the tool server port for integration with external orchestration platforms:

docker run --rm -it \
  -e TOOL_SERVER_PORT=9090 \
  -e TOOL_SERVER_TOKEN="my-secret-token" \
  ghcr.io/usestrix/strix-sandbox:0.1.13 \
  strix --target ./custom-port

The tool server becomes reachable at http://host.docker.internal:9090 with the specified authentication token.

Key Implementation Files

Reference these source files when extending or debugging the Docker runtime:

• containers/Dockerfile: Defines the base Kali Linux image, installs security tools (Nmap, Nuclei, Trivy), creates the pentester user, and sets ENV STRIX_SANDBOX_MODE=true to signal sandbox context to the application code.

• containers/docker-entrypoint.sh: Boot script that initializes the Caido proxy (lines 12-45), injects CA certificates into the NSS store (lines 48-52), launches the tool server (lines 62-68), executes health checks (lines 69-80), and finally hands control to the user command via exec "$@".

• docs/advanced/configuration.mdx: Authoritative documentation for all environment variables affecting Docker runtime and sandbox behavior.

• strix/runtime/tool_server.py: Implements the HTTP API that forwards tool invocations to binaries inside the container, handling timeouts and output streaming.

• strix/config/__init__.py: Loads configuration from environment variables and optional ~/.strix/cli-config.json, exposing the same keys documented in the configuration reference.

Summary

• Set STRIX_IMAGE to override the default sandbox container image (ghcr.io/usestrix/strix-sandbox:0.1.13).
• Configure DOCKER_HOST to connect to remote Docker daemons via TCP or Unix socket.
• Tune STRIX_SANDBOX_EXECUTION_TIMEOUT and STRIX_SANDBOX_CONNECT_TIMEOUT to prevent hung processes during long-running scans.
• Control internal services through TOOL_SERVER_PORT, CAIDO_API_TOKEN, and STRIX_DISABLE_BROWSER.
• All configuration is processed at runtime by containers/docker-entrypoint.sh without requiring image rebuilds.

Frequently Asked Questions

What is the default sandbox image used by Strix?

The default image is ghcr.io/usestrix/strix-sandbox:0.1.13, defined in docs/advanced/configuration.mdx and baked into the Dockerfile. You can override this by setting the STRIX_IMAGE environment variable to any accessible OCI registry path, including private repositories requiring authentication.

How do I connect Strix to a remote Docker daemon?

Set the DOCKER_HOST environment variable to your remote endpoint, such as tcp://remote-host:2375, before running the container. Strix's runtime client reads this variable during initialization to establish the connection, enabling scans to execute on remote infrastructure without local Docker installation.

Can I disable the browser automation tools in the sandbox?

Yes. Set STRIX_DISABLE_BROWSER=true when running the container. This skips the Playwright Chromium installation and related setup steps in the entrypoint script, reducing container startup time and resource consumption when browser-based tools are unnecessary for your security assessment.

Where are the proxy settings configured for sandboxed tools?

The entrypoint script at containers/docker-entrypoint.sh writes proxy variables to /etc/profile.d/proxy.sh, /etc/environment, and /etc/wgetrc after starting the Caido proxy. It also injects the CA certificate into the system trust store (lines 48-52) so that tools respecting http_proxy and https_proxy environment variables automatically route traffic through the container's HTTP proxy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}