usestrix/strix · error · RuntimeError

strix_image is not configured. Set it in ~/.strix/cli-config

Error message

strix_image is not configured. Set it in ~/.strix/cli-config.json.

What it means

Raised by _resolve_sandbox_image (strix/interface/cli.py:35) when the loaded settings' runtime.image (the strix_image sandbox container image) is empty. Strix executes all scan tooling inside a Docker sandbox, so the CLI refuses to start without an image reference; the message points at ~/.strix/cli-config.json as the persistent config location.

Source

Thrown at strix/interface/cli.py:35

from strix.core.runner import run_strix_scan
from strix.report.state import ReportState, set_global_report_state
from strix.runtime import session_manager

from .utils import (
    build_live_stats_text,
    format_vulnerability_report,
    has_model_response,
    read_workspace_files,
)


logger = logging.getLogger(__name__)


def _resolve_sandbox_image() -> str:
    image = load_settings().runtime.image
    if not image:
        raise RuntimeError(
            "strix_image is not configured. Set it in ~/.strix/cli-config.json.",
        )
    return image


async def run_cli(args: Any) -> None:  # noqa: PLR0915
    console = Console()

    start_text = Text()
    start_text.append("Penetration test initiated", style="bold #22c55e")

    target_text = Text()
    target_text.append("Target", style="dim")
    target_text.append("  ")
    if len(args.targets_info) == 1:
        target_text.append(args.targets_info[0]["original"], style="bold white")
    else:
        target_text.append(f"{len(args.targets_info)} targets", style="bold white")

View on GitHub (pinned to 8551339130)

Solutions

Set the image in ~/.strix/cli-config.json, e.g. {"runtime": {"image": "ghcr.io/usestrix/strix-sandbox:latest"}}.
Or set it via whatever settings source your version supports (STRIX_IMAGE env / `strix config` command) before launching the CLI.
Verify by loading settings and printing runtime.image non-empty; also ensure Docker is running since the sandbox needs it.

Example fix

# before
# ~/.strix/cli-config.json -> {}
$ strix -t ./   # RuntimeError: strix_image is not configured

# after
$ cat ~/.strix/cli-config.json
{"runtime": {"image": "ghcr.io/usestrix/strix-sandbox:latest"}}
$ strix -t ./

Defensive patterns

Strategy: validation

Validate before calling

from strix.config import load_settings
image = load_settings().runtime.image
if not image:
    raise SystemExit('configure runtime.image in ~/.strix/cli-config.json first')

Type guard

def sandbox_image_configured() -> bool:
    from strix.config import load_settings
    return bool(load_settings().runtime.image)

Try / catch

try:
    run_cli(args)
except RuntimeError as exc:
    if 'strix_image is not configured' in str(exc):
        write_cli_config(image='ghcr.io/usestrix/strix-sandbox:latest')
        run_cli(args)
    else:
        raise

Prevention

Run strix's post-install config step once and commit ~/.strix/cli-config.json to your workstation setup.
In CI, template the config file with the image before invoking strix.

When it happens

Trigger: Running the strix CLI on a fresh install where strix_image was never configured; a cli-config.json missing the runtime.image key or set to ""; config file replaced/reset.

Common situations: Skipping the post-install configuration step; JSON typos (image under the wrong section so it never loads); CI containers that mount a minimal HOME without ~/.strix.

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/de09182aa7c59f1b. Report an issue: GitHub.