Container Runtime — SCORPIOX CODE

Overview

scorpiox code runs AI agents inside lightweight Linux containers built from scratch in C. The scorpiox-unshare runtime uses Linux kernel namespaces (PID, mount, user, UTS, network) to create fully isolated environments without requiring root privileges or any container daemon. For macOS and cross-platform use, scorpiox-podman delegates to Podman for OCI-compliant execution.

            shell
# Run an agent in a container
scorpiox --container "Refactor auth module"

# Custom image with GPU and port mapping
scorpiox --container --image scorpiox-ubuntu --gpu -p 8080:8080

# Podman runtime (macOS/cross-platform)
scorpiox --podman --image scorpiox-alpine "Fix build pipeline"
        

Container Runtimes

🔧 scorpiox-unshare native

scorpiox/scorpiox-unshare.c

Native Linux user namespace containers — zero daemon, zero dependencies. Uses clone() with CLONE_NEW* flags to create isolated namespaces, overlayfs for copy-on-write rootfs, slirp4netns for userspace networking, and cgroups v2 for resource limits.

pid_namespacemount_namespaceuser_namespace uts_namespacenetwork_namespaceoverlayfs seccomp_filtercapability_droppingcgroups_v2 gpu_passthroughoci_image_extractionport_mapping volume_mountspivot_rootslirp4netns privileged_modeentrypoint_scripts

linux-x64linux-arm64

🐳 scorpiox-podman oci

scorpiox/scorpiox-podman.c

Podman-based container runtime — delegates to podman CLI for OCI-compliant container execution. Supports custom registries, volume mounts, port mapping, environment variables, and host networking. Uses fork+execvp for safe process execution without shell interpolation.

oci_registry_pullvolume_mountsport_mapping environment_variableshost_networkinginteractive_tty auto_removecustom_registry

linux-x64linux-arm64darwin-x64darwin-arm64

⚙️ scorpiox-sdk orchestrator

scorpiox/scorpiox-sdk.c

SDK container orchestration — agent runner that launches containers via scorpiox-unshare (Linux) or scorpiox-wsl (Windows). Manages the full lifecycle: forkpty → container runtime → agent execution → session monitoring. Supports serve mode with REST API, headless agent mode, and TUI mode.

agent_lifecycleforkpty_executionsession_monitoring serve_mode_rest_apicontainer_port_forwarding wsl2_integrationtui_modeheadless_mode

linux-x64linux-arm64darwin-x64darwin-arm64windows-x64

Isolation & Security

scorpiox-unshare applies multiple layers of kernel-level isolation. Each container runs in its own namespace set with seccomp filtering and capability dropping.

🔒 PID Namespace

CLONE_NEWPID

Process ID isolation — container processes get their own PID tree with PID 1 init. Prevents visibility of host processes.

📁 Mount Namespace

CLONE_NEWNS

Filesystem isolation — container gets private mount tree. All mounts are made MS_REC|MS_PRIVATE to prevent propagation to host.

👤 User Namespace

CLONE_NEWUSER

UID/GID isolation — maps container root (uid 0) to unprivileged host user. Skipped when running as real root for NFS/CIFS compatibility.

🏷️ UTS Namespace

CLONE_NEWUTS

Hostname isolation — container gets its own hostname set via sethostname(). Derived from image name.

🌐 Network Namespace

CLONE_NEWNET

Network isolation — isolated network stack with slirp4netns providing outbound connectivity via tap device at 10.0.2.100. Bypass with --net host.

💾 OverlayFS

mount("overlay")

Copy-on-write filesystem — rootfs image is read-only lower layer, ephemeral upper layer captures writes. Falls back to bind-mount on older kernels (< 5.11).

🔄 Pivot Root

SYS_pivot_root

Root filesystem switch — atomically swaps container rootfs as new /. Old root is unmounted and detached. proc and sysfs mounted before pivot.

🛡️ Seccomp BPF

prctl(PR_SET_SECCOMP)

Syscall filtering via BPF — blocks personality() (prevents ASLR disable) and keyctl() (prevents kernel keyring manipulation). Uses PR_SET_NO_NEW_PRIVS.

⚡ Capability Dropping

prctl(PR_CAPBSET_DROP)

Drops dangerous Linux capabilities from bounding set. Removes CAP_IPC_LOCK to prevent mlock() memory pinning DoS attacks.

📊 Cgroups v2

/sys/fs/cgroup/sx-<pid>/

Memory resource limiting via cgroups v2. Per-container cgroup with memory.max limit. Supports human-readable sizes (e.g., 40G, 512M). Cleaned up on exit.

Image Management

OCI-compliant image management with automatic download, extraction, and caching. Images are fetched from the scorpiox distribution server.

            shell
# List available container images
scorpiox --container --list-images

# Use a specific image
scorpiox --container --image scorpiox-ubuntu

# Custom registry
SCORPIOX_REGISTRY=https://my-registry.example.com scorpiox --container
        

Setting	Value
Default image	scorpiox-alpine
Image cache	~/.scorpiox/images/
Rootfs cache	~/.scorpiox/rootfs/
Dist URL	https://dist.scorpiox.net/container-images/
Registry env	SCORPIOX_REGISTRY
Format	OCI (index.json + blobs/sha256 + layered extraction)
Update check	HTTP Content-Length comparison

Networking

Two networking modes: fully isolated with slirp4netns userspace networking, or host mode sharing the host network stack directly.

🔒 Isolated (default)

CLONE_NEWNET + slirp4netns tap device. Container gets 10.0.2.100, DNS at 10.0.2.3. Full outbound connectivity, inbound via port mapping only.

🌐 Host Networking

Shares host network stack — no CLONE_NEWNET. Enabled with --net host. Container uses host DNS resolver directly.

            shell
# Port mapping (host:container)
scorpiox --container -p 8080:8080 -p 3000:3000

# Auto port resolution (host finds free port)
scorpiox --container -p 0+:8080

# Host networking (bypass isolation)
scorpiox --container --net host
        

Parameter	Detail
API socket	/tmp/sx_slirp_<pid>.sock
Tap device	tap0
Container IP	10.0.2.100
DNS	10.0.2.3
Max port mappings	16
Protocol	tcp

Volumes & Mounts

Bind-mount host directories into the container with optional read-only mode. Up to 16 custom mounts plus built-in workspace, persist, and host binary mounts.

            shell
# Custom volume mount
scorpiox --container -v /data/models:/models:ro

# Multiple volumes
scorpiox --container -v ./src:/workspace -v /tmp/cache:/persist
        

Mount	Container Path	Description
--bind	/workspace	Primary workspace bind mount
--persist	/persist	Persistent cache directory
auto	/opt/host-bin	Auto-binds host scorpiox binaries (read-only)

Volume syntax: -v host:container[:ro] — max 16 custom mounts. Mount flags: MS_BIND | MS_REC. Read-only remount: MS_BIND | MS_REMOUNT | MS_RDONLY.

GPU Passthrough

NVIDIA GPU device passthrough via bind-mounting device nodes into the container. Also bind-mounts host NVIDIA driver libraries from /usr/lib.

            shell
# Enable GPU passthrough
scorpiox --container --gpu "Train the model"
        

Device	Path
nvidia*	/dev/nvidia*
nvidiactl	/dev/nvidiactl
nvidia-uvm	/dev/nvidia-uvm
nvidia-uvm-tools	/dev/nvidia-uvm-tools
dri/*	/dev/dri/*

Container Lifecycle

Create — clone() with CLONE_NEW* flags allocates new stack and spawns child process
Start — Parent writes uid_map/gid_map, signals sync_pipe; child sets up rootfs, mounts, pivot_root
Exec — Child process exec's entrypoint script, /bin/bash, or /bin/sh with optional command via -c flag
Stop — Parent waitpid() on child, then cleans up: slirp4netns kill, cgroup removal, work directory removal
Kill — SIGTERM/SIGINT forwarded to child via signal handler; SIGCHLD triggers cleanup

Device & Filesystem Setup

Minimal /dev via tmpfs with bind-mounted host device nodes. Includes devpts for PTY allocation and shared memory tmpfs.

Essential Devices

null · zero · random · urandom · tty

Pseudo Filesystems

devpts · shm · proc · sysfs · tmpfs /tmp · tmpfs /run

Symlinks

/dev/fd · /dev/stdin · /dev/stdout · /dev/stderr · /dev/ptmx

Privileged Mode

Skip user namespace with --privileged for full capabilities. Required for NFS/CIFS/FUSE mounts inside containers.

Configuration

Container settings in scorpiox-env.txt:

            scorpiox-env.txt
# Container runtime
SX_CONTAINER=true
SX_CONTAINER_IMAGE=scorpiox-alpine
SX_CONTAINER_MEMORY=40G

# Networking
SX_CONTAINER_NET=isolated
SX_CONTAINER_PORTS=8080:8080,3000:3000

# Volumes
SX_CONTAINER_VOLUMES=/data:/data:ro,./cache:/persist

# GPU
SX_CONTAINER_GPU=true

# Custom registry
SCORPIOX_REGISTRY=https://dist.scorpiox.net/container-images/
        