Stateless WSL2 execution — import .tar rootfs as ephemeral distributions on Windows. Overlayfs, volume mounts, and automatic cleanup. Pure C, zero dependencies.
scorpiox-wsl is a stateless WSL2 container runtime written in pure C (source: scorpiox/scorpiox-wsl.c). It imports .tar rootfs archives as ephemeral WSL2 distributions, executes commands inside them, and automatically tears down the distribution when done.
Unlike traditional WSL usage where distributions persist between sessions, scorpiox-wsl treats each invocation as disposable — import, execute, unregister. This gives AI agents a clean Linux environment on every run without accumulating state.
Each session creates a fresh WSL2 distribution from a .tar rootfs image. No leftover state between runs.
Copy-on-write filesystem inside WSL — base image stays read-only, writes go to an ephemeral upper layer.
Bind-mount host Windows directories into the WSL2 environment using -v host:container syntax.
Distributions are automatically unregistered on exit. No orphaned WSL instances cluttering wsl --list.
Pure C implementation using Win32 APIs. No PowerShell scripts, no Docker, no external tooling required.
On Windows, scorpiox-sdk automatically selects scorpiox-wsl as the container runtime for agent execution.
The WSL container runtime follows a simple import → execute → cleanup lifecycle. Each invocation creates a unique WSL2 distribution name to avoid collisions.
# 1. Image is downloaded from the distribution server
# Default: https://dist.scorpiox.net/container-images/
# Cached at: ~/.scorpiox/images/
# 2. Import as ephemeral WSL2 distro
wsl --import scorpiox-abc123 C:\tmp\scorpiox-abc123 alpine.tar
# 3. Execute commands inside the distro
wsl -d scorpiox-abc123 -- /bin/bash -c "echo hello"
# 4. Unregister on exit (automatic)
wsl --unregister scorpiox-abc123
Downloaded .tar images are cached under ~/.scorpiox/images/. Subsequent launches skip the download step entirely. The image registry is configurable via IMAGE_BASE_URL in scorpiox-env.txt.
| Feature | Description |
|---|---|
wsl2_distro_import |
Imports .tar rootfs as a new WSL2 distribution using wsl.exe --import |
overlayfs |
Copy-on-write filesystem — base rootfs is read-only, session writes go to an upper layer |
volume_mounts |
Bind-mount host directories into the WSL2 environment with -v flag |
ephemeral_distros |
Each session creates a uniquely-named distro — no state leaks between runs |
auto_cleanup |
Automatic distro unregistration on process exit, signal, or error |
distro_lifecycle |
Full lifecycle management: create, exec, terminate, unregister |
WSL container settings are configured in scorpiox-env.txt. These keys control image sources, package installation, and tmux integration.
| Key | Default | Description |
|---|---|---|
IMAGE_BASE_URL |
https://dist.scorpiox.net/container-images/ |
Base URL for downloading container rootfs images |
CONTAINER_PACKAGES |
git,cmake,gcc,make,curl,samurai |
Packages auto-installed on first boot. Set to none to disable. |
TMUX_WSL_EXTRA_ARGS |
|
Extra arguments passed to scorpiox-wsl when launched from tmux |
TMUX_WSL_VOLUME_MOUNT |
|
Volume mount spec for WSL containers launched via tmux |
# Use a custom image server
IMAGE_BASE_URL=https://my-server.example.com/images/
# Install extra packages in WSL 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
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.
# 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 from the distribution server
scorpiox-wsl --list-images
# Clean all cached images and rootfs
scorpiox-wsl --clean
Each invocation generates a unique distro name like scorpiox-a1b2c3. You can run multiple agents simultaneously — each in its own isolated WSL2 instance. All instances are cleaned up independently when their respective processes exit.
Volume mounts bind host Windows directories into the WSL2 environment. This lets agents read and write files on the host filesystem.
# Basic volume mount
scorpiox-wsl -v C:\Users\dev\project:/workspace
# Read-only mount
scorpiox-wsl -v C:\configs:/etc/app:ro
# Multiple mounts (up to 16)
scorpiox-wsl -v C:\src:/workspace -v C:\data:/data
# Bind host directory at /workspace (shorthand)
scorpiox-wsl --bind C:\Users\dev\project
# Persist directory at /persist
scorpiox-wsl --persist C:\Users\dev\state
| Option | Mount Point | Notes |
|---|---|---|
-v host:container |
Custom | General-purpose bind mount, up to 16 mounts |
-v host:container:ro |
Custom (read-only) | Read-only bind mount for config files |
--bind dir |
/workspace |
Shorthand for mounting project directory |
--persist dir |
/persist |
Persistent storage across sessions |
scorpiox-sdk is the agent orchestrator that manages the full chain: host → container → agent → headless AI session. On Windows, the SDK automatically selects scorpiox-wsl as the container backend.
On Windows, the SDK detects the platform and delegates to scorpiox-wsl. On Linux, it uses scorpiox-unshare instead. No configuration needed.
The SDK passes ports, volumes, environment variables, and packages through to the WSL container automatically.
# The SDK handles container selection automatically
# On Windows → scorpiox-wsl
# On Linux → scorpiox-unshare
scorpiox-sdk --image alpine -v C:\project:/workspace
# Tmux integration — each agent in its own WSL pane
scorpiox-tmux --mode wsl --image alpine
scorpiox-tmux can launch multiple agents in parallel, each running in its own WSL2 container inside a separate tmux pane. Set --mode wsl to use the WSL runtime. Configure default mounts with TMUX_WSL_VOLUME_MOUNT in scorpiox-env.txt.