Runtime API

Manage sandboxed execution environments

Overview

The Runtime API manages Docker-based sandboxed environments for secure tool execution. Each agent runs in an isolated container with its own filesystem and network.

Getting the Runtime

get_runtime

from strix.runtime import get_runtime

runtime = get_runtime() -> AbstractRuntime

Returns the global runtime instance based on configuration.

return · AbstractRuntime

Runtime instance (currently DockerRuntime)

Example:

from strix.runtime import get_runtime

runtime = get_runtime()
print(f"Runtime backend: {type(runtime).__name__}")

AbstractRuntime

Base interface for runtime implementations.

create_sandbox

async def create_sandbox(
    agent_id: str,
    existing_token: str | None = None,
    local_sources: list[dict[str, str]] | None = None
) -> SandboxInfo

Creates or retrieves a sandboxed environment.

agent_id · str · required

Unique identifier for the agent

existing_token · str | None

Authentication token to reuse

local_sources · list[dict[str, str]] | None

Local directories to mount in the sandbox

Show local_sources format

Each dictionary should contain:

• source_path: Local directory path
• workspace_subdir: Optional subdirectory name in /workspace

return · SandboxInfo

Sandbox information dictionary

Show SandboxInfo fields

workspace_id · str

Container ID

api_url · str

Tool server API URL

auth_token · str | None

Authentication token

tool_server_port · int

Host port for tool server

caido_port · int

Host port for Caido proxy

agent_id · str

Agent identifier

Example:

import asyncio
from strix.runtime import get_runtime

async def main():
    runtime = get_runtime()
    
    sandbox = await runtime.create_sandbox(
        agent_id="agent_abc123",
        local_sources=[{
            "source_path": "/path/to/local/code",
            "workspace_subdir": "target"
        }]
    )
    
    print(f"Container ID: {sandbox['workspace_id']}")
    print(f"API URL: {sandbox['api_url']}")
    print(f"Token: {sandbox['auth_token'][:10]}...")

asyncio.run(main())

get_sandbox_url

async def get_sandbox_url(
    container_id: str,
    port: int
) -> str

Returns the host-accessible URL for a container port.

container_id · str · required

Docker container ID

port · int · required

Container port number

return · str

Accessible URL (e.g., “http://127.0.0.1:49152”)

destroy_sandbox

async def destroy_sandbox(container_id: str) -> None

Stops and removes a sandbox container.

container_id · str · required

Container ID to destroy

Example:

await runtime.destroy_sandbox("container_id_here")

cleanup

def cleanup() -> None

Cleans up runtime resources asynchronously.

DockerRuntime

Docker-based runtime implementation.

Configuration

Configure via environment variables:

export STRIX_RUNTIME_BACKEND=docker
export STRIX_IMAGE=ghcr.io/usestrix/strix-sandbox:0.1.12
export STRIX_SANDBOX_EXECUTION_TIMEOUT=120
export STRIX_SANDBOX_CONNECT_TIMEOUT=10

Container Features

The Docker sandbox provides:

• Isolated filesystem - Each container has /workspace for file operations
• Network access - Containers can make external HTTP requests
• Tool server - Built-in HTTP server for executing tools
• Caido proxy - Integrated proxy for HTTP traffic analysis
• Security - Runs as non-root user with limited capabilities

Container Lifecycle

Containers are shared across agents in the same scan:

1. First agent creates the container
2. Subsequent agents reuse the same container
3. Local sources are copied only once
4. Container persists until explicitly destroyed or cleanup

Example:

from strix.runtime import get_runtime
import asyncio

async def main():
    runtime = get_runtime()
    
    # Create sandbox for first agent
    sandbox1 = await runtime.create_sandbox("agent_001")
    
    # Same container reused for second agent
    sandbox2 = await runtime.create_sandbox("agent_002")
    
    assert sandbox1["workspace_id"] == sandbox2["workspace_id"]
    
    # Cleanup when done
    await runtime.destroy_sandbox(sandbox1["workspace_id"])

asyncio.run(main())

Exceptions

SandboxInitializationError

from strix.runtime import SandboxInitializationError

class SandboxInitializationError(Exception):
    def __init__(
        message: str,
        details: str | None = None
    )

Raised when sandbox creation or initialization fails.

message · str · required

Error message

details · str | None

Additional error details

Example:

from strix.runtime import get_runtime, SandboxInitializationError

try:
    runtime = get_runtime()
    sandbox = await runtime.create_sandbox("agent_123")
except SandboxInitializationError as e:
    print(f"Failed to initialize sandbox: {e.message}")
    if e.details:
        print(f"Details: {e.details}")

Cleanup

cleanup_runtime

from strix.runtime import cleanup_runtime

cleanup_runtime() -> None

Cleans up the global runtime instance and all containers.

Example:

from strix.runtime import cleanup_runtime
import atexit

# Register cleanup on exit
atexit.register(cleanup_runtime)

Advanced Usage

Custom Local Sources

import asyncio
from strix.runtime import get_runtime

async def scan_local_app():
    runtime = get_runtime()
    
    sandbox = await runtime.create_sandbox(
        agent_id="scanner_001",
        local_sources=[
            {
                "source_path": "/path/to/webapp",
                "workspace_subdir": "webapp"
            },
            {
                "source_path": "/path/to/configs",
                "workspace_subdir": "configs"
            }
        ]
    )
    
    # Files now available at:
    # /workspace/webapp/
    # /workspace/configs/
    
    return sandbox

asyncio.run(scan_local_app())

Accessing Container Services

import httpx

# Access tool server
tool_server_url = f"{sandbox['api_url']}/execute"

async with httpx.AsyncClient() as client:
    response = await client.post(
        tool_server_url,
        json={
            "agent_id": "agent_123",
            "tool_name": "terminal_execute",
            "kwargs": {"command": "ls /workspace"}
        },
        headers={"Authorization": f"Bearer {sandbox['auth_token']}"}
    )
    print(response.json())

Environment Variables

STRIX_RUNTIME_BACKEND · str · default: "'docker'"

Runtime backend to use (currently only “docker” supported)

STRIX_IMAGE · str · default: "'ghcr.io/usestrix/strix-sandbox:0.1.12'"

Docker image for sandboxes

STRIX_SANDBOX_EXECUTION_TIMEOUT · str · default: "'120'"

Tool execution timeout in seconds

STRIX_SANDBOX_CONNECT_TIMEOUT · str · default: "'10'"

Connection timeout in seconds

DOCKER_HOST · str · default: "None"

Custom Docker host URL (e.g., “tcp://192.168.1.100:2376”)