Skip to main content

​
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
​
return
SandboxInfo
Sandbox information dictionary
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”)

Build docs developers (and LLMs) love

Get started for freeTalk to us