🧰 NEONBOX: Deterministic Sandboxed Runtime

Low-Latency Micro-Jail, Capability Security, & Transactional Rollback for AI Agent Tool Execution

---

  _   _ _____ ___  _   _ ____   _____  __
 | \ | | ____/ _ \| \ | | __ ) / _ \ \/ /
 |  \| |  _|| | | |  \| |  _ \| | | \  / 
 | |\  | |__| |_| | |\  | |_) | |_| /  \ 
 |_| \_|_____\___/|_| \_|____/ \___/_/\_\
    * 100% HERMETIC TOOL EXECUTION • NO SPILLS ON THE COUNTER *

---

🎨 1970s DINER VISUAL MATRIX & CHROME SIGNATURE

---

📸 Photorealistic Visual Asset Prompt

Midjourney / Stable Diffusion Prompt:
A 1970s diner kitchen with polished stainless steel countertops, order tickets hanging on a metal wheel, an illuminated vintage vacuum-tube terminal box with green phosphor text and glowing analog needle meters displaying memory and CPU wattage, reflections of neon cyan diner signs on chrome hoods, Kodachrome 64, anamorphic lens, warm cinematic lighting, hyper-realistic, 8k resolution --ar 16:9 --style raw --v 6.0

---

🕹️ INTERACTIVE 3D WEBGL DINER CHROME COUNTER GRAPHIC

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>NeonBox 3D Chrome Terminal</title>
  <style>
    body { margin: 0; background: #1A1A1A; overflow: hidden; }
    #canvas-container { width: 100vw; height: 100vh; }
  </style>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
</head>
<body>
  <div id="canvas-container"></div>
  <script>
    const scene = new THREE.Scene();
    scene.fog = new THREE.FogExp2(0x1a1a1a, 0.05);
    const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 100);
    camera.position.set(0, 1.4, 3.8);

    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setSize(window.innerWidth, window.innerHeight);
    renderer.setPixelRatio(window.devicePixelRatio);
    document.getElementById('canvas-container').appendChild(renderer.domElement);

    // Neon Lights
    const cyanLight = new THREE.PointLight(0x00f5d4, 4, 10);
    cyanLight.position.set(-2, 2, 2);
    scene.add(cyanLight);

    const redLight = new THREE.PointLight(0xc41e3a, 2.5, 10);
    redLight.position.set(2, -1, 1);
    scene.add(redLight);

    // Chrome Sandbox Cube
    const boxGeo = new THREE.BoxGeometry(1.6, 1.2, 1.2);
    const chromeMat = new THREE.MeshStandardMaterial({
      color: 0xe8ecef,
      metalness: 0.95,
      roughness: 0.1
    });
    const boxMesh = new THREE.Mesh(boxGeo, chromeMat);
    scene.add(boxMesh);

    // Glowing Inner Vacuum Tube Core
    const coreGeo = new THREE.IcosahedronGeometry(0.5, 1);
    const coreMat = new THREE.MeshBasicMaterial({ color: 0x00f5d4, wireframe: true });
    const coreMesh = new THREE.Mesh(coreGeo, coreMat);
    scene.add(coreMesh);

    function animate() {
      requestAnimationFrame(animate);
      boxMesh.rotation.y += 0.008;
      coreMesh.rotation.x -= 0.015;
      coreMesh.rotation.y += 0.02;
      renderer.render(scene, camera);
    }
    animate();

    window.addEventListener('resize', () => {
      camera.aspect = window.innerWidth / window.innerHeight;
      camera.updateProjectionMatrix();
      renderer.setSize(window.innerWidth, window.innerHeight);
    });
  </script>
</body>
</html>

---

📜 THE MENU: FEATURE OVERVIEW & CAPABILITY MATRIX

Standard tool calling in AI frameworks runs tools directly on the host machine or relies on sluggish Docker containers ($1,500\text{ms}$ startup). If an agent executes a faulty command that modifies the filesystem, you're stuck cleaning up the mess. NeonBox provides sub-10ms micro-jails with instant transactional rollback.

Diner Menu Item	Naive Tool Execution (exec / subprocess)	Heavyweight Containers (Docker / Podman)	NeonBox Sandboxed Runtime
Startup Latency	~2ms (Unsafe)	1,200ms – 2,500ms (Unusable for loops)	⚡ < 10ms micro-jail
Ambient Authority	❌ Leaks all environment tokens & secrets	⚠️ Requires full container daemon	🛡️ Zero Ambient Authority (Scrubbed)
Path Traversal Protection	❌ Easily escapes cwd via ..	✅ Container isolated	🔒 Strict Path Confinement Check
Atomic File Rollback	❌ Permanent side-effects on crash	❌ Container state discarded or persistent	⏪ Deterministic Transactional Rollback
Memory / CPU Watchdog	❌ Infinite loops freeze host	⚠️ Static container quotas	⏱️ Active Background Watchdog Thread

---

🍳 THE KITCHEN: CAPABILITY MODEL & ROLLBACK GUARANTEE

+---------------------------------------------------------------------------------+
|                                 NEONBOX JAIL                                    |
|                                                                                 |
|   Tool Invocation Payload                                                       |
|             |                                                                   |
|             v                                                                   |
|   [ 1. Capability Verification ] ---> CAP_SUBPROCESS / CAP_FS_WRITE             |
|             |                                                                   |
|             v                                                                   |
|   [ 2. Environment Scrubbing ]   ---> Strip API keys, tokens, auth headers      |
|             |                                                                   |
|             v                                                                   |
|   [ 3. Pre-Execution Snapshot ]  ---> Transactional Manifest (SHA-256)          |
|             |                                                                   |
|             v                                                                   |
|   [ 4. Sandboxed Execution ]    <--- Active Watchdog (Timeout & RSS Memory)     |
|             |                                                                   |
|       +-----+-----+                                                             |
|       |           |                                                             |
|    SUCCESS     FAILURE / TIMEOUT / CRASH                                        |
|       |           |                                                             |
|       v           v                                                             |
|   [ Commit ]  [ ATOMIC ROLLBACK ] ---> Restore clean state, delete dirty files  |
+---------------------------------------------------------------------------------+

Formal Mathematical Proof of Rollback Invariance

Theorem (State Invariance under Failure):
Let $S_0 \in \mathcal{S}$ denote the initial filesystem state of the workspace directory before tool execution. For any tool execution command $C$ resulting in terminal status $E \in {\text{TIMEOUT}, \text{MEMORY_EXCEEDED}, \text{EXECUTION_ERROR}}$:

$$\mathcal{R}(\text{Exec}(C, S_0)) = S_0$$

Proof:
The pre-execution snapshot $\mathcal{M}_0$ maps relative paths to byte sequences:

$$\mathcal{M}_0 = { (p_i, b_i) \mid p_i \in \text{Paths}(S_0), \quad b_i = \text{Read}(p_i) }$$

Upon failure, the rollback operator $\mathcal{R}$ executes two deterministic phases:

1. Unlink Additionals: $\forall p \in \text{Paths}(S_{\text{final}}) \setminus \text{Paths}(S_0), \quad \text{Unlink}(p)$.
2. Byte Reversion: $\forall (p_i, b_i) \in \mathcal{M}_0, \quad \text{Write}(p_i, b_i)$.

Since the workspace is strictly path-confined ($p_i \in \text{Workspace}$), no external state outside the workspace is accessible. Thus, the post-rollback state $S_{\text{recovered}} \equiv S_0$. No dirty side-effects can leak. $\blacksquare$

---

🛎️ THE WAITSTAFF: API HOOKS & CODE RECIPES

1. Initializing the Sandbox

from neonbox import NeonBoxRuntime, SandboxConfig, ExecutionPolicy, Capability

# Initialize hermetic sandbox
config = SandboxConfig(
    workspace_dir="./agent_sandbox_dir",
    auto_rollback_on_failure=True
)
runtime = NeonBoxRuntime(config)

2. Executing a Tool Safely

# Configure policy: Grant subprocess execution with a 3-second hard timeout
policy = ExecutionPolicy(
    allowed_capabilities={Capability.CAP_SUBPROCESS, Capability.CAP_FS_WRITE},
    timeout_seconds=3.0,
    max_memory_mb=128
)

result = runtime.execute_command("python -c \"print('Hello from the counter!')\"", policy)
print(f"Status: {result.status.value} (Time: {result.execution_time_ms:.1f}ms)")

---

🍳 BLUE PLATE SPECIAL: 60-SECOND QUICKSTART

# 1. Clone repository
git clone https://github.com/retro-ai/neonbox-runtime.git
cd neonbox-runtime

# 2. Run unit tests
python -m unittest discover -s tests -p "test_*.py"

# 3. Run latency & isolation benchmark
python -m neonbox.cli benchmark

# 4. Execute custom command inside the jail
python -m neonbox.cli run --cmd "python -c \"print('Counter is clean!')\""

---

🧾 THE BILL / CHECK: TELEMETRY & AUDIT LOG

NeonBox outputs exact resource receipts for every tool call:

{
  "status": "SUCCESS",
  "exit_code": 0,
  "execution_time_ms": 8.42,
  "peak_memory_mb": 14.2,
  "filesystem_modified": false,
  "rollback_performed": false
}

---

🎵 THE JUKEBOX: CROSS-PROJECT ECOSYSTEM

Track Selection	Project Title	Description	Link
Track A1	RetroSync Engine	Hierarchical Causal Attestation Graphs & Vector Drift Reconciliation	RetroSync Engine
Track B4	Route66 Consensus	Deadlock-Free Lamport Priority Multi-Agent Orchestrator	Route66 Engine
Track C7	NeonBox Runtime	Deterministic Low-Latency Sandboxed Tool Execution Jail	[You Are Here]
Track D10	Diner Browser Agent	Autonomous Playwright Browser Agent for Online Guerrilla Marketing	Marketing Agent

---

NeonBox Runtime is released under the Apache-2.0 License. Keep the grease off the motherboard.