Docker Settings

Strix uses Docker to create isolated sandbox environments for security testing. Understanding Docker configuration helps you customize the runtime behavior and troubleshoot issues.

Prerequisites

Strix requires Docker to be installed and running:

# Check if Docker is installed
docker --version

# Check if Docker is running
docker ps

Docker Desktop must be running before you start Strix. If Docker is not available, Strix will exit with an error.

Sandbox Image

Default Image

Strix uses a pre-built Docker image that contains all security testing tools:

export STRIX_IMAGE="ghcr.io/usestrix/strix-sandbox:0.1.12"

The sandbox image includes:

Python runtime with security libraries
Terminal environments for command execution
Browser automation (Playwright)
HTTP proxy (Caido)
Common security tools (Nuclei, etc.)

Custom Image

You can use a custom sandbox image:

export STRIX_IMAGE="your-registry/custom-strix-sandbox:tag"

Custom images must implement the Strix tool server API and include all required dependencies. Using an incompatible image will cause Strix to fail.

Image Pull

On first run, Strix automatically pulls the sandbox image:

Pulling image ghcr.io/usestrix/strix-sandbox:0.1.12
This only happens on first run and may take a few minutes...

The image is cached locally and reused for subsequent runs.

Runtime Configuration

Runtime Backend

Strix uses Docker as the runtime backend:

export STRIX_RUNTIME_BACKEND="docker"

Currently, only docker is supported as a runtime backend. Other backends may be added in future releases.

Execution Timeout

Control how long Strix waits for individual tool executions:

export STRIX_SANDBOX_EXECUTION_TIMEOUT="120"  # seconds

This timeout applies to:

Terminal command execution
Python script execution
File operations
HTTP requests via proxy

Increase this value if you’re testing slow targets or running complex exploits:

# For slow targets
export STRIX_SANDBOX_EXECUTION_TIMEOUT="300"  # 5 minutes

Connection Timeout

Control how long Strix waits to connect to the sandbox tool server:

export STRIX_SANDBOX_CONNECT_TIMEOUT="10"  # seconds

Increase this value if container startup is slow:

# For slow Docker environments
export STRIX_SANDBOX_CONNECT_TIMEOUT="30"

Container Management

Container Naming

Strix creates containers with predictable names:

strix-scan-{scan-id}

Where scan-id is derived from the scan configuration.

Container Reuse

Strix automatically reuses containers across runs:

If a container with the same scan ID exists, Strix reuses it
If the container is stopped, Strix restarts it
If the container is corrupted, Strix recreates it

This improves performance by avoiding repeated container creation.

Manual Container Management

You can manually manage Strix containers:

# List all Strix containers
docker ps -a --filter "name=strix-scan-"

# Stop a running scan container
docker stop strix-scan-{scan-id}

# Remove a scan container
docker rm -f strix-scan-{scan-id}

# Remove all Strix containers
docker rm -f $(docker ps -a --filter "name=strix-scan-" -q)

Container Cleanup

Strix automatically cleans up containers when:

The scan completes successfully
You exit the TUI
The process is interrupted (Ctrl+C)

In some cases, containers may not be cleaned up automatically. You can clean them manually:

# Remove all stopped Strix containers
docker container prune --filter "label=strix-scan-id"

Network Configuration

Port Bindings

Strix automatically binds container ports to random host ports:

Tool Server - Container port 48081 → Random host port
Caido Proxy - Container port 48080 → Random host port

You can find the bound ports:

docker ps --filter "name=strix-scan-" --format "table {{.Names}}\t{{.Ports}}"

Host Access

The sandbox can access services on your host machine using:

host.docker.internal

This is useful for testing local applications:

# Test a local web app running on port 3000
strix --target http://localhost:3000

# Strix rewrites this to http://host.docker.internal:3000 inside the container

Docker Host

If you’re using a remote Docker daemon, set DOCKER_HOST:

export DOCKER_HOST="tcp://remote-host:2375"

Strix automatically detects the Docker host and adjusts connection URLs:

For local Docker: Uses 127.0.0.1
For remote Docker: Uses the hostname from DOCKER_HOST

Container Capabilities

Network Capabilities

Strix containers run with elevated network capabilities:

--cap-add=NET_ADMIN
--cap-add=NET_RAW

This allows:

Network packet manipulation
Raw socket access
Custom network configurations
Advanced network reconnaissance

These capabilities are required for certain security testing techniques. They are isolated to the container and do not affect your host system.

Workspace Mounts

Local Source Code

When testing local code, Strix automatically copies it to the container:

strix --target ./my-app

# Code is copied to /workspace inside the container

Strix mounts local directories as:

Path inside container: /workspace/{directory-name}
Ownership: pentester:pentester (non-root)
Permissions: 755 (readable and executable)

Multi-Target Mounts

With multiple local targets, each is mounted separately:

strix --target ./frontend --target ./backend

# /workspace/frontend
# /workspace/backend

Resource Limits

By default, Strix containers have no resource limits. You can add limits using Docker configuration:

Memory Limit

Edit Docker daemon configuration (/etc/docker/daemon.json):

{
  "default-ulimits": {
    "memlock": {
      "Name": "memlock",
      "Hard": 8589934592,
      "Soft": 8589934592
    }
  }
}

Or use Docker Compose for custom resource limits (not directly supported by Strix).

CPU Limit

Similarly, you can configure CPU limits in Docker daemon configuration.

Resource limits are not currently exposed as Strix configuration options. You’ll need to configure them at the Docker daemon level.

Troubleshooting

Docker Not Found

If you see “Docker not found”:

Install Docker Desktop: https://www.docker.com/products/docker-desktop
Ensure Docker is in your PATH: which docker
Start Docker Desktop

Docker Not Running

If you see “Docker is not available”:

Start Docker Desktop
Verify it’s running: docker ps
Check Docker daemon: docker info

Permission Denied

If you see permission errors:

# On Linux, add your user to the docker group
sudo usermod -aG docker $USER

# Log out and log back in for changes to take effect

Image Pull Failed

If image pull fails:

Check your internet connection
Verify you can reach GitHub Container Registry:
```
curl -I https://ghcr.io
```

Try pulling manually:

docker pull ghcr.io/usestrix/strix-sandbox:0.1.12

Check Docker Hub rate limits (if applicable)

Container Creation Failed

If container creation fails:

Check Docker daemon logs: docker logs
Ensure sufficient disk space: df -h
Remove old containers: docker container prune
Remove old images: docker image prune

Tool Server Timeout

If you see “Tool server failed to start”:

Increase connection timeout:

export STRIX_SANDBOX_CONNECT_TIMEOUT="30"

Check container logs:
```
docker logs strix-scan-{scan-id}
```
Verify container is running:
```
docker ps --filter "name=strix-scan-"
```

Port Conflicts

Strix uses random ports to avoid conflicts. If you still encounter issues:

Check for port exhaustion: netstat -an | grep LISTEN
Restart Docker Desktop
Remove old containers: docker rm -f $(docker ps -a --filter "name=strix-scan-" -q)

Performance Optimization

Container Reuse

To maximize performance, let Strix reuse containers:

# Multiple scans reuse the same container
strix --target https://app.com
strix --target https://app.com  # Reuses container from first scan

Disk Space

Periodically clean up old containers and images:

# Remove stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Remove unused volumes
docker volume prune -f

Resource Allocation

Allocate sufficient resources to Docker Desktop:

Open Docker Desktop settings
Increase CPU and memory allocation
Recommended: 4+ CPUs, 8+ GB RAM

Get Started

Core Concepts

Usage

Skills

Integrations

Configuration

​Prerequisites

​Sandbox Image

​Default Image

​Custom Image

​Image Pull

​Runtime Configuration

​Runtime Backend

​Execution Timeout

​Connection Timeout

​Container Management

​Container Naming

​Container Reuse

​Manual Container Management

​Container Cleanup

​Network Configuration

​Port Bindings

​Host Access

​Docker Host

​Container Capabilities

​Network Capabilities

​Workspace Mounts

​Local Source Code

​Multi-Target Mounts

​Resource Limits

​Memory Limit

​CPU Limit

​Troubleshooting

​Docker Not Found

​Docker Not Running

​Permission Denied

​Image Pull Failed

​Container Creation Failed

​Tool Server Timeout

​Port Conflicts

​Performance Optimization

​Container Reuse

​Disk Space

​Resource Allocation

​See Also

Build docs developers (and LLMs) love

Prerequisites

Sandbox Image

Default Image

Custom Image

Image Pull

Runtime Configuration

Runtime Backend

Execution Timeout

Connection Timeout

Container Management

Container Naming

Container Reuse

Manual Container Management

Container Cleanup

Network Configuration

Port Bindings

Host Access

Docker Host

Container Capabilities

Network Capabilities

Workspace Mounts

Local Source Code

Multi-Target Mounts

Resource Limits

Memory Limit

CPU Limit

Troubleshooting

Docker Not Found

Docker Not Running

Permission Denied

Image Pull Failed

Container Creation Failed

Tool Server Timeout

Port Conflicts

Performance Optimization

Container Reuse

Disk Space

Resource Allocation

See Also