WSL Container Runtime — SCORPIOX CODE

Overview

scorpiox-wsl is the Windows container runtime for SCORPIOX CODE. It turns WSL2 into a stateless container engine — importing .tar rootfs images as ephemeral WSL distributions that are destroyed on exit. No Docker, no Podman, no daemon. Just wsl.exe --import and pure C.

On Linux, SCORPIOX CODE uses scorpiox-unshare (user-namespace containers via clone()). On Windows, scorpiox-wsl provides the same semantics: isolated Linux environments from OCI images, with volume mounts, port forwarding, and automatic garbage collection.

📦

Ephemeral Distros

Each session imports a fresh rootfs via wsl --import. Random distro names prevent collisions across parallel agents.

🔄

Overlayfs Support

Copy-on-write filesystem layering. Base image stays read-only, writes go to an ephemeral upper layer.

💾

Volume Mounts

Bind-mount host directories into the container. Supports -v C:\src:/workspace syntax with read-only option.

🧹

Auto Cleanup

On exit, the WSL distro is terminated and unregistered. No orphaned distributions, no disk bloat.

⚡

Zero Dependencies

Pure C binary. Uses Windows APIs (CreateProcessW) to drive wsl.exe directly. No runtime needed.

🔗

SDK Integration

scorpiox-sdk auto-selects scorpiox-wsl on Windows and scorpiox-unshare on Linux. Same agent, both platforms.

How It Works

The WSL runtime follows a 5-step lifecycle for each container session:

1

Image Download

Fetches .tar rootfs from https://dist.scorpiox.net/container-images/. Supports OCI image layouts with index.json + layered blob extraction. Cached at ~/.scorpiox/images/.

2

WSL Import

Runs wsl.exe --import sx-<random> <tmpdir> <image.tar> to register a new ephemeral distribution. The random suffix ensures parallel sessions never collide.

3

Environment Setup

Mounts volumes via /mnt/ paths, configures networking, installs packages from CONTAINER_PACKAGES if set, and runs entrypoint scripts.

4

Execution

Launches wsl.exe -d sx-<name> with the target command or interactive shell. PTY allocated via CreateProcessW for full terminal support.

5

Cleanup

On process exit: wsl --terminate sx-<name> then wsl --unregister sx-<name>. Temp directories removed. Zero artifacts left on host.

Image Caching

Downloaded rootfs tarballs are cached at ~/.scorpiox/images/. Update checks compare HTTP Content-Length headers against local file size. Use scorpiox-wsl --clean to purge the cache.

Features

Comparison of container runtimes available in SCORPIOX CODE. The SDK automatically selects the correct runtime for the current platform.

Runtime	Source	Platforms	Key Features
`scorpiox-wsl`	`scorpiox-wsl.c`	Windows x64, ARM64	WSL2 import/unregister, ephemeral distros, volume mounts, CreateProcessW
`scorpiox-unshare`	`scorpiox-unshare.c`	Linux x64, ARM64	User namespaces, overlayfs, seccomp, cgroups v2, slirp4netns, GPU passthrough
`scorpiox-podman`	`scorpiox-podman.c`	Linux, macOS	OCI registry pull, Podman CLI delegation, host networking, custom registries
`scorpiox-sdk`	`scorpiox-sdk.c`	All platforms	Agent lifecycle, forkpty, serve mode REST API, auto runtime selection

Image Management

SCORPIOX CODE uses OCI-format rootfs images distributed as .tar archives. Images are downloaded from a configurable distribution server and cached locally.

Property	Value
Format	`OCI` — flat rootfs tarballs or layered OCI image layouts
Default Server	`https://dist.scorpiox.net/container-images/`
Registry Env	`SCORPIOX_REGISTRY` — override distribution server URL
Image Cache	`~/.scorpiox/images/`
Rootfs Cache	`~/.scorpiox/rootfs/`
Default Image	`scorpiox-alpine`
Operations	`download`, `extract`, `list`, `update`, `clean`, `oci_layer_extract`

                CLI
                # List available images on the distribution server
scorpiox-wsl --list-images

# Download and cache an image without running
scorpiox-wsl --image scorpiox-alpine --pull-only

# Force re-download (ignore cache)
scorpiox-wsl --image ubuntu --update

# Clean all cached images and extracted rootfs
scorpiox-wsl --clean
            

Configuration

Container behavior is controlled via scorpiox-env.txt keys. These apply to both scorpiox-wsl and scorpiox-unshare runtimes.

Key	Default	Description
`IMAGE_BASE_URL`	`https://dist.scorpiox.net/container-images/`	Base URL for downloading container rootfs images
`SCORPIOX_REGISTRY`		Override the default OCI registry URL for image pulls
`CONTAINER_PACKAGES`	`git,cmake,gcc,make,curl,samurai`	Packages auto-installed on first boot. Set to `none` to skip.
`TMUX_WSL_EXTRA_ARGS`		Extra arguments passed to scorpiox-wsl when launched via tmux
`TMUX_WSL_VOLUME_MOUNT`		Volume mount spec for WSL containers launched via tmux

                scorpiox-env.txt
                # Use a custom image server
IMAGE_BASE_URL=https://my-mirror.example.com/images/

# Override OCI registry
SCORPIOX_REGISTRY=https://registry.internal.corp/scorpiox/

# Install extra packages in containers
CONTAINER_PACKAGES=git,cmake,gcc,make,curl,samurai,python3,nodejs

# Disable auto-package installation
CONTAINER_PACKAGES=none

# Pass extra args when launching via tmux
TMUX_WSL_EXTRA_ARGS=--net host

# Mount project directory into tmux WSL sessions
TMUX_WSL_VOLUME_MOUNT=C:\Users\dev\project:/workspace
            

Distro Lifecycle

Each WSL container session follows a deterministic lifecycle. The distro name is generated with a random suffix to prevent collisions when running multiple agents in parallel.

                CLI
                # Launch an interactive WSL container
scorpiox-wsl --image alpine

# Run a one-off command
scorpiox-wsl --image ubuntu -- apt update && apt install -y build-essential

# Mount a host directory
scorpiox-wsl --image alpine -v C:\src:/workspace

# List available images
scorpiox-wsl --list-images

# Clean all cached images and rootfs
scorpiox-wsl --clean
            

Parallel Sessions

Each invocation generates a unique distro name like sx-a7f3b2. You can run dozens of parallel agents — each gets its own isolated WSL2 distribution, its own mount namespace, and its own cleanup handler.

Volume Mounts & Port Forwarding

Volume mounts bind host directories into the container filesystem. Port forwarding maps container ports to the Windows host.

Property	Value
Syntax	`-v host:container[:ro]`
Max Mounts	`16`
Options	`ro` (read-only), `rw` (default)
Port Syntax	`-p host:container`
Auto Port	`-p host+:container` — auto-allocate host port
Max Port Mappings	`16`
Protocol	`tcp`

Built-in Mounts

Flag	Container Path	Description
`--bind`	`/workspace`	Primary workspace bind mount
`--persist`	`/persist`	Persistent cache directory — survives container restarts
auto	`/opt/host-bin`	Auto-binds host scorpiox binaries (read-only)

                CLI
                # Mount source code into /workspace
scorpiox-wsl -v C:\Users\dev\myproject:/workspace --image alpine

# Read-only mount for config files
scorpiox-wsl -v C:\configs:/etc/app:ro --image alpine

# Forward port 8080 from container to host port 9090
scorpiox-wsl -p 9090:8080 --image alpine

# Auto-allocate host port for container port 3000
scorpiox-wsl -p 0+:3000 --image alpine
            

Networking

WSL2 containers support two networking modes. The default isolated mode uses slirp4netns for userspace networking. Host mode shares the Windows network stack.

Mode	Flag	Container IP	DNS	Description
Isolated (default)	—	`10.0.2.100`	`10.0.2.3`	CLONE_NEWNET + slirp4netns tap device. Full outbound, inbound via port mapping only.
Host	`--net host`	host IP	host resolver	Shares host network stack. No isolation. Container uses host DNS.

slirp4netns Details

API socket at /tmp/sx_slirp_<pid>.sock. Tap device tap0 with container IP 10.0.2.100. Port forwarding commands sent as JSON via the API socket. 3 retry attempts for connection setup.

SDK Integration

scorpiox-sdk is the agent orchestrator that manages the full container lifecycle. It automatically selects the correct runtime based on the host platform.

Automatic Runtime Selection

On Windows, SDK launches scorpiox-wsl via CreateProcessW. On Linux, it uses scorpiox-unshare via forkpty(). Same agent code, both platforms.

Agent Passthrough

SDK forwards volume mounts (-v), port mappings (-p), environment variables, and networking flags to the underlying runtime.

Serve Mode

REST API for launching containers programmatically. Auto port resolution, session monitoring, and structured JSON responses.

Tmux Multi-Agent

Launch multiple agents in tmux panes — each gets its own isolated WSL2 container. Use TMUX_WSL_EXTRA_ARGS and TMUX_WSL_VOLUME_MOUNT for per-session config.

SDK Feature Matrix

Feature	Description
`agent_lifecycle`	Full spawn → monitor → cleanup lifecycle management
`forkpty_execution`	PTY allocation for interactive terminal sessions
`session_monitoring`	Real-time output capture and health checks
`serve_mode_rest_api`	HTTP API for programmatic container management
`windows_createprocess`	Native Win32 process creation for WSL runtime
`wsl2_integration`	Direct wsl.exe --import/--unregister orchestration
`tui_mode`	Terminal UI for interactive agent management
`headless_mode`	Non-interactive execution for CI/CD pipelines