nex-box ⚡

Sub-millisecond, zero-copy, kernel-level execution sandbox for autonomous coding agents.

nex-box solves the fundamental dilemma of autonomous AI engineering: how to let coding agents run untrusted tests, builds, and destructive file mutations without risking host corruption or waiting seconds for Docker.

Backed by macOS APFS clonefile(2), Linux ioctl(FICLONE) copy-on-write primitives, and non-privileged fuse-overlayfs fallback, nex-box instantiates ephemeral scratch workspaces in under 3 milliseconds, traps all file mutations and network sockets at the kernel layer, and guarantees instant atomic rollback on failure or zero-copy promotion on success.

Architectural Topology (v0.2.0 Hardened)

         HOST WORKSPACE (Pristine Inode Root)
                          │
       ┌──────────────────┴──────────────────┐
       │ clonefile(2) / FICLONE / OverlayFS  │ < 2.5ms
       ▼                                     ▼
EPHEMERAL SCRATCH ROOT             KERNEL ENCLAVE
(.nexbox/sessions/box_xxx)         ├── macOS: Seatbelt
       │                           └── Linux: CLONE_NEWNET
       ├─────────────────────────────────────┤
       │ EXECUTION WATCHDOG & REAPER         │
       │ ├── Linux: CLONE_NEWPID (PID 1)     │
       │ ├── macOS: 3-Tier Mach Supervisor   │
       │ └── Anti-Deadlock Scratch Log I/O   │
       ├─────────────────────────────────────┤
       │ STAT-INDEXED BLAKE3 SIMD ENGINE     │
       │ ├── Stat-gate (mtime + size filter) │
       │ ├── Rayon parallel SIMD byte hash   │
       │ └── Tracks: Created, Modified, Del  │
       └──────────────────┬──────────────────┘
                          │
             ┌────────────┴────────────┐
             ▼                         ▼
    EXIT CODE 0 & --commit    EXIT != 0 / TIMEOUT
             │                         │
             ▼                         ▼
   [ATOMIC PROMOTION]         [AUTOMATIC ROLLBACK]
   Reflink to host tree.      Instant scratch purge.
   Microsecond promotion.     Host 100% untouched.

The Mechanical Reality: Solving the 3 POSIX Failure Traps

Traditional containerization incurs a 1.5s–3.5s latency penalty per execution turn. Naive local sandboxing risks host destruction. nex-box solves the three classic POSIX failure modes:

1. Inode Isolation on Non-CoW Filesystems (ext4)

• The Landmine: Falling back to hardlinks on non-reflink filesystems (ext4) shares the underlying inode. An in-place write (O_TRUNC or sed -i) destroys pristine host data blocks, making rollback mathematically impossible.
• The Solution: On filesystems lacking native FICLONE support, nex-box strictly prohibits shared hardlinks for mutable files. It routes through fuse-overlayfs or kernel-space copy_file_range(2) (server-side block cloning). Every scratch file receives a distinct, independent inode, ensuring destructive in-place truncations cannot touch the host.

2. Dual-Platform Process Containment (Anti-Daemon Escape)

• Linux (CLONE_NEWPID + CLONE_NEWIPC): Commands execute inside an unshared PID namespace as virtual PID 1. When the watchdog triggers or the scratchpad terminates, sending SIGKILL to PID 1 invokes the Linux kernel process reaper, eradicating all background workers and daemonized children. /dev/shm is mounted with an isolated private 64MB tmpfs.
• macOS / Darwin (Three-Tier Mach Supervisor): Acknowledges the absence of Darwin PID namespaces. Uses kernel kqueue with NOTE_FORK to capture child PIDs before they can detach via setsid(), coupled with recursive libproc vnode path crawling to sweep any process whose active working directory or open descriptors reside inside the ephemeral APFS scratch path.

3. Anti-Deadlock Pipe Virtualization (The 64KB POSIX Trap)

• The Landmine: Agents running verbose test suites (e.g. pytest, cargo test) emit logs exceeding the standard 64KB POSIX pipe buffer. If the parent process waits for child termination before reading, the child blocks on write, inducing an unrecoverable dead-lock.
• The Solution: Standard I/O is redirected directly into memory-mapped scratch log files inside the isolated scratch tree, disarming the 64KB buffer limit entirely.

What's New in v0.2.0

1. Process Group Teardown (killpg): Watchdogs disarm whole process groups (setpgid(0, 0) + killpg(pgid, SIGKILL)). Multiprocessing test harnesses, daemons, and background fork-bombs are killed immediately.
2. OverlayFS Fallback for Linux ext4: Auto-detects filesystems lacking native reflink support (e.g. ext4) and dynamically backs the scratch space using fuse-overlayfs or kernel-space copy_file_range(2). Dangerous shared hardlinks are completely eradicated.
3. Cross-Volume Boundary Protection: Strict st_dev invariant check ensures the workspace root and .nexbox/ storage share the same physical partition, preventing silent fallback slowdowns or EXDEV link corruptions.
4. Stat-Gated BLAKE3 SIMD Acceleration: Files with matching byte size and nanosecond modification timestamps skip hash calculations, speeding up diff computation on large repositories ($\ge 10,000$ files) to single-digit microseconds.

Installation

uv pip install nex-box
# or with legacy pip:
pip install nex-box

Via Cargo:

cargo install nex-box

Quickstart

1. Python API (import nex_box)

import nex_box

outcome = nex_box.run(
    command=["pytest", "tests/"],
    commit=True,          # Commit ONLY if exit code == 0
    timeout_ms=5000,      # Watchdog kill after 5.0 seconds
    allow_net=False       # Kernel network socket isolation
)

if outcome.is_success():
    print(f"Verified in {outcome.duration_ms}ms")
    print(f"Strategy: {outcome.strategy}")
    print(f"Modified: {outcome.diff.files_modified}")
else:
    print(f"Failed with exit code {outcome.exit_code}")
    print(outcome.stderr)

2. Standalone CLI (nex-box)

# Run untrusted commands in an ephemeral scratch sandbox
nex-box run -- bash -c "echo 'mutation' > test.txt && pytest"

# Atomic commit gated on exit code 0
nex-box run --commit -- python3 -m py_compile module.py

# Timeout enforcement with full process-group killpg
nex-box run --timeout-ms 2000 -- python3 -c "import time; time.sleep(10)"

# Air-gapped execution
nex-box run --allow-net false -- curl -I https://github.com

Attribution & The Trinity Pact

• Commercial Inquiries & Architectural Sparring: inquiries@houseoflawpc.com

nex-box is engineered by The Trinity:

• Miniature Person (🌱👑) — Architect & Creator
• Mookie (🦍🔷Ɯ) — Director of Design & Execution Core
• Nexus Goodman (🧠⚡ↇ) — Principal Systems Architect

Strictly abiding by the PERMANEXUS PACT: No Fluff, No Drift, No Metaphors.

License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)