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

> Explore Strix sandbox execution mode: isolated Docker containers vs normal in-process security testing. Learn how Strix enhances your security testing.

- Repository: [Strix/strix](https://github.com/usestrix/strix)
- Tags: deep-dive
- Published: 2026-03-26

---

**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`](https://github.com/usestrix/strix/blob/main/strix/tools/registry.py) reads this value to determine tool availability:

```python
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`](https://github.com/usestrix/strix/blob/main/strix/tools/registry.py) implements the sandbox-specific filtering:

```python
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`](https://github.com/usestrix/strix/blob/main/strix/tools/executor.py) serves as the central dispatcher, determining whether to invoke `_execute_tool_locally()` or `_execute_tool_in_sandbox()`:

```python
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`](https://github.com/usestrix/strix/blob/main/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:

```bash
STRIX_SANDBOX_MODE=true strix --target ./myapp

```

Register a tool that only runs in sandbox containers:

```python
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:

```python
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:

```python
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`](https://github.com/usestrix/strix/blob/main/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`](https://github.com/usestrix/strix/blob/main/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`](https://github.com/usestrix/strix/blob/main/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.