Strix Sandbox Execution Mode: Isolated vs Normal In-Process Security Testing

Strix sandbox execution mode routes security-testing tools into isolated Docker containers, while normal mode runs tools directly inside the host Python process.

The open-source repository usestrix/strix provides a flexible architecture for security automation that supports two distinct runtime environments. Understanding Strix sandbox execution mode is essential for safe deployment, as it determines whether potentially dangerous operations run inside isolated containers or within the main application process.

How Execution Mode Is Selected

The environment variable STRIX_SANDBOX_MODE controls the active mode, defaulting to false. The registry module in strix/tools/registry.py reads this value to determine tool availability:

def _is_sandbox_mode() -> bool:
    return os.getenv("STRIX_SANDBOX_MODE", "false").lower() == "true"

When this function returns true, the system activates sandbox filtering logic that restricts which tools remain registered for use.

Tool Registration Logic

When developers decorate functions with @register_tool, the system evaluates three flags to determine inclusion:

• sandbox_execution – Determines if the tool can run inside the sandbox
• requires_browser_mode – Disables the tool if browser capabilities are unavailable
• requires_web_search_mode – Disables the tool if the Perplexity API key is missing

The _should_register_tool() function in strix/tools/registry.py implements the sandbox-specific filtering:

def _should_register_tool(*, sandbox_execution, requires_browser_mode, requires_web_search_mode) -> bool:
    sandbox_mode = _is_sandbox_mode()
    if sandbox_mode and not sandbox_execution:
        return False
    # ... additional mode checks

Tools marked with sandbox_execution=False are excluded from the registry when sandbox execution mode is active, while tools marked True (such as terminal_execute and python_action) remain available.

Execution Flow and Architecture

The executor in strix/tools/executor.py serves as the central dispatcher, determining whether to invoke _execute_tool_locally() or _execute_tool_in_sandbox():

execute_in_sandbox = should_execute_in_sandbox(tool_name)
sandbox_mode = os.getenv("STRIX_SANDBOX_MODE", "false").lower() == "true"

if execute_in_sandbox and not sandbox_mode:
    return await _execute_tool_in_sandbox(...)
else:
    return await _execute_tool_locally(...)

Normal Mode Execution

In normal mode, the executor calls the Python function directly in-process. The agent has access to all registered tools, including high-level orchestration functions like create_agent and finish_scan. This approach offers lower latency but provides no isolation from the host system.

Sandbox Mode Execution

When sandbox execution mode is active, the system follows this workflow:

1. Container Initialization: BaseAgent._initialize_sandbox_and_state() triggers runtime.create_sandbox() in strix/runtime/docker_runtime.py
2. Image Deployment: Creates a container using ghcr.io/usestrix/strix-sandbox:0.1.13 with environment variable STRIX_SANDBOX_MODE=true
3. Token Generation: Generates unique authentication tokens for the sandbox session
4. HTTP Routing: Sends POST requests to http://<container>/execute with the tool name and arguments
5. Result Return: The tool-server processes the request and returns results to the agent

The container runs as a non-root user (pentester) and is destroyed after the scan completes.

Key Differences Between Normal and Sandbox Mode

Aspect	Normal Mode	Sandbox Mode
Tool Availability	All tools registered (orchestration + action tools)	Only sandbox_execution=True tools remain
Execution Location	Direct Python call in-process	Remote HTTP call to Docker container
Isolation Level	None – full host access	Complete filesystem and network isolation
Performance	Faster (no network hop)	Slower (container startup + HTTP overhead)
Security	Risky for untrusted code	Safe execution of dangerous operations

Practical Implementation Examples

Enable sandbox mode via CLI:

STRIX_SANDBOX_MODE=true strix --target ./myapp

Register a tool that only runs in sandbox containers:

from strix.tools.registry import register_tool

@register_tool(sandbox_execution=True)
def terminal_execute(agent_state, command: str):
    # Executes inside container when sandbox mode is active

    pass

@register_tool(sandbox_execution=False)
def create_agent(...):
    # Excluded from registry when STRIX_SANDBOX_MODE=true

    pass

Execute a tool manually with agent state:

from strix.tools.executor import execute_tool

result = await execute_tool(
    "terminal_execute",
    agent_state=state,
    command="ls -la /workspace"
)

Unit test verifying mode behavior:

def test_sandbox_registers_sandbox_tools_but_not_non_sandbox_tools(monkeypatch):
    monkeypatch.setenv("STRIX_SANDBOX_MODE", "true")
    tools = _reload_tools_module()
    names = set(tools.get_tool_names())
    
    assert "terminal_execute" in names
    assert "create_agent" not in names

Summary

• Strix sandbox execution mode isolates dangerous tools in Docker containers controlled via the STRIX_SANDBOX_MODE environment variable
• The registry filters tools based on the sandbox_execution flag, removing non-sandbox tools when the mode is enabled
• Execution routes through HTTP to a tool-server inside ghcr.io/usestrix/strix-sandbox images according to the logic in strix/tools/executor.py
• Normal mode offers speed and convenience while sandbox mode provides security isolation for untrusted operations via the Docker runtime in strix/runtime/docker_runtime.py

Frequently Asked Questions

What happens if STRIX_SANDBOX_MODE is not set?

When the environment variable is undefined, Strix defaults to normal mode (false), executing all tools directly within the host Python process without container isolation.

Which tools are available in sandbox execution mode?

Only tools explicitly marked with sandbox_execution=True remain available, such as low-level action tools like terminal_execute, python_action, and list_requests. High-level orchestration tools like create_agent are filtered out by the _should_register_tool() logic.

How does the executor choose between local and sandbox execution?

The execute_tool() function in strix/tools/executor.py checks both the tool's sandbox eligibility and the current mode. If the tool supports sandbox execution and the mode is enabled, it routes to _execute_tool_in_sandbox(); otherwise, it calls _execute_tool_locally().

What Docker image does Strix use for sandbox containers?

The system uses ghcr.io/usestrix/strix-sandbox:0.1.13 as defined in the configuration, launching containers with the pentester non-root user and automatic token authentication for HTTP requests to the internal tool-server.

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