Metadata-Version: 2.4
Name: nex-box
Version: 0.2.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Security
Summary: Sub-millisecond Copy-on-Write ephemeral sandbox runtime for autonomous coding agents.
Keywords: sandbox,agent,cow,reflink,testing,apfs,overlayfs
Author-email: The Trinity <inquiries@houseoflawpc.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/houseoflawpc/nex-box#readme
Project-URL: Homepage, https://github.com/houseoflawpc/nex-box
Project-URL: Repository, https://github.com/houseoflawpc/nex-box.git

# nex-box ⚡

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

[![PyPI version](https://img.shields.io/pypi/v/nex-box.svg)](https://pypi.org/project/nex-box/)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](https://pypi.org/project/nex-box/)
[![Rust](https://img.shields.io/badge/rust-2021%20edition-orange.svg)](https://www.rust-lang.org/)

`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)

```text
         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

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

Via Cargo:
```bash
cargo install nex-box
```

---

## Quickstart

### 1. Python API (`import nex_box`)

```python
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`)

```bash
# 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](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
