Container Runtime

Overview

scorpiox code runs every AI agent session inside a rootless container powered by scorpiox-unshare — a purpose-built container runtime written in C. It uses Linux user namespaces (CLONE_NEWUSER, CLONE_NEWPID, CLONE_NEWNS) to create fully isolated execution environments without requiring root privileges or a Docker daemon.

Key capabilities:

Rootless execution — no daemon, no suid, no root required
Bind-mount project directories into the container with read-write or read-only access
Container image caching — pull once, start in milliseconds
Configurable networking — host mode, isolated, or no network at all

🔒

User Namespaces

CLONE_NEWUSER + CLONE_NEWPID + CLONE_NEWNS for complete process isolation

📁

Bind Mounts

Your project directory is mounted at /workspace inside the container

⚡

Instant Startup

Cached images skip download — containers launch in under 50ms

🌐

Network Control

Host networking for tool access, or full isolation for untrusted code

How It Works

When you start a scorpiox code session with containers enabled, the runtime executes the following sequence:

Image resolution — resolves the container image from the local cache at ~/.scorpiox/containers/images/. If not cached, pulls from the configured registry.
Namespace creation — calls unshare(CLONE_NEWUSER | CLONE_NEWPID | CLONE_NEWNS) to create isolated user, PID, and mount namespaces.
Filesystem setup — overlays the cached rootfs, bind-mounts your project directory to /workspace, and mounts /proc, /dev/null, /dev/urandom.
Network config — based on container_network setting: shares the host network stack, creates an isolated namespace, or disables networking entirely.
Agent execution — pivot_root into the new rootfs and exec the scorpiox-code agent binary with inherited environment variables and the configured provider.

                lifecycle
                # Container lifecycle (simplified)
scorpiox-unshare \
    --rootfs ~/.scorpiox/containers/images/default \
    --bind /home/user/project:/workspace \
    --net host \
    -- /usr/local/bin/scorpiox-code --provider anthropic

# Internals: unshare() → mount() → pivot_root() → exec()
            

Configuration

Container behavior is configured in scorpiox-env.txt in your project root or ~/.scorpiox/scorpiox-env.txt globally.

Key	Default	Description
container_enabled	true	Enable or disable container isolation for agent sessions
container_image	default	Container image name — resolved from ~/.scorpiox/containers/images/
container_network	host	Network mode: `host`, `isolated`, or `none`
container_mount_ro	(empty)	Comma-separated paths to mount as read-only inside the container
container_cache_dir	~/.scorpiox/containers	Directory for cached container images and overlayfs layers
container_timeout	3600	Maximum container lifetime in seconds before forced termination
container_memory_mb	4096	Memory limit for the container via cgroup (if available)

                scorpiox-env.txt
                # Container configuration
container_enabled=true
container_image=default
container_network=host
container_cache_dir=~/.scorpiox/containers
container_timeout=3600
container_memory_mb=4096

# Mount project root read-write (default), docs read-only
container_mount_ro=/home/user/docs,/etc/ssl/certs
            

Examples

Basic Session

Start a scorpiox code session with default container settings. Your current directory is automatically mounted at /workspace.

                shell
                $ cd ~/my-project
$ scorpiox-code
# → Container starts with default image
# → ~/my-project mounted at /workspace
# → Agent has full read-write access to project files
            

Disable Container Isolation

For trusted environments or when you need direct host access, disable containers:

                scorpiox-env.txt
                # Run agent directly on host (no isolation)
container_enabled=false
            

Air-Gapped Execution

Run the agent with no network access — useful for security-sensitive codebases:

                scorpiox-env.txt
                # Complete network isolation
container_network=none

# Agent can still read/write project files
# but cannot make any network calls
            

Custom Image with Extra Tools

Use a custom container image pre-loaded with your build toolchain:

                shell
                # Import a custom rootfs tarball
$ scorpiox-code --container-import ./my-toolchain.tar.gz --name rust-dev

# Use it in scorpiox-env.txt
container_image=rust-dev
            

Image Caching

Container images are stored as extracted rootfs directories under ~/.scorpiox/containers/images/. The first run downloads and extracts the image; subsequent runs use the cached rootfs directly.

                shell
                # Cache structure
~/.scorpiox/containers/
├── images/
│   ├── default/          # Base image rootfs
│   │   ├── bin/
│   │   ├── lib/
│   │   ├── usr/
│   │   └── etc/
│   └── rust-dev/         # Custom image rootfs
├── overlays/             # Per-session overlay layers
│   └── session-a1b2c3/
└── tmp/                  # Download staging area
            

Startup Performance

With a cached image, container startup takes <50ms. The overlay filesystem captures any writes made during the session. When the session ends, the overlay is discarded — leaving the base image pristine for the next run.

Networking

Three network modes control how the containerized agent accesses the network:

`host` (default)

Shares the host network namespace. The agent can reach the internet, call APIs (Anthropic, OpenAI, etc.), and access local services. Best for general use.

`isolated`

Creates a new network namespace with loopback only. The agent can communicate between its own processes but cannot reach external networks.

`none`

No network namespace setup at all. All socket syscalls fail. Maximum isolation for processing sensitive code offline.

                scorpiox-env.txt
                # Allow API calls but block everything else
container_network=host

# Full network isolation — agent works offline
container_network=none
            