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) / ioctl(FICLONE) / Overlay │ < 2.5ms Latency
              ▼                                         ▼
   EPHEMERAL SCRATCH ROOT                    KERNEL CONFINEMENT ENCLAVE
   (.nexbox/sessions/box_xxx)                 ├── macOS Seatbelt: (deny network*)
              │                               └── Linux: unshare(CLONE_NEWNET)
              ├─────────────────────────────────────────┤
              │ COMMAND EXECUTION & WATCHDOG TIMER      │
              │ ├── Process Group Teardown (killpg)     │
              │ ├── Scratch Log I/O (Anti-Pipe Lock)    │
              │ └── Hard millisecond SIGKILL watchdog   │
              ├─────────────────────────────────────────┤
              │ STAT-INDEXED BLAKE3 SIMD ENGINE         │
              │ ├── Stat-gate (mtime + size filter)     │
              │ ├── Rayon parallel SIMD byte hash       │
              │ └── Extracts: Created, Modified, Deleted│
              └────────────────────┬────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
           EXIT CODE 0 & --commit        EXIT CODE != 0 / TIMEOUT
                    │                             │
                    ▼                             ▼
        [ATOMIC PROMOTION]               [AUTOMATIC ROLLBACK]
   Reflink changes to host tree.    Instant purge of scratch tree.
   Host updated in microseconds.    Host remains 100% untouched.

What's New in v0.2.0

1. Process Group Teardown (killpg): Watchdogs now isolate and disarm whole process groups (setpgid(0, 0) + killpg(pgid, SIGKILL)). Multiprocessing test harnesses, daemonized subprocesses, and background fork-bombs are killed immediately without orphaning zombie workers.
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 high-throughput parallel Rayon cloning. 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 filesystem 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

pip install nex-box
# or with uv:
uv 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,          # Automatically commit to host ONLY if exit code == 0
    timeout_ms=5000,      # Hard watchdog killpg after 5.0 seconds
    allow_net=False       # Kernel-level network socket isolation
)

if outcome.is_success():
    print(f"Verified in {outcome.duration_ms}ms (Strategy: {outcome.strategy})")
    print(f"Cloned in: {outcome.clone_duration_micros}µs")
    print(f"Files Modified: {outcome.diff.files_modified}")
else:
    print(f"Agent 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

License

Dual-licensed under either of:

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

### File 4: src/lib.rs
```rust
//! src/lib.rs - Root library entrypoint exporting main components and PyO3 C-extension.

pub mod main_components;

#[cfg(feature = "python")]
use pyo3::prelude::*;

#[cfg(feature = "python")]
use main_components::python_bindings::{run, PySandboxOutcome, PyWorkspaceDiff};

/// Python native C-extension module entrypoint
#[cfg(feature = "python")]
#[pymodule]
fn nex_box(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(run, m)?)?;
    m.add_class::<PySandboxOutcome>()?;
    m.add_class::<PyWorkspaceDiff>()?;
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
    Ok(())
}