NullBox Cloud

REST API for spinning up secure NullBox AI agent sandboxes on demand. Each sandbox is a QEMU-backed NullBox VM running the full service stack (nulld, cage, egress, warden, sentinel, watcher).

Quick Start

# Set paths to pre-built NullBox kernel and initramfs
export NULLBOX_KERNEL=/path/to/nullbox-kernel
export NULLBOX_INITRAMFS=/path/to/nullbox-initramfs.cpio.gz

# Build and run
cargo build --release
./target/release/nullbox-cloud

The server listens on 0.0.0.0:3000.

API

Method	Path	Description
POST	/v1/sandboxes	Create a new sandbox
GET	/v1/sandboxes	List all sandboxes
GET	/v1/sandboxes/:id	Get sandbox status and ports
DELETE	/v1/sandboxes/:id	Destroy a sandbox
POST	/v1/sandboxes/:id/exec	Forward a command to a service
GET	/health	Health check

Create a sandbox

curl -X POST http://localhost:3000/v1/sandboxes \
  -H 'Content-Type: application/json' \
  -d '{"memory_mb": 4096, "cpus": 4, "timeout_secs": 3600}'

Response:

{
  "id": "sb_a1b2c3d4",
  "status": "running",
  "ports": {
    "ctxgraph": 20000,
    "harness": 20001,
    "dashboard": 20002
  },
  "created_at": "2026-04-06T12:00:00Z",
  "timeout_secs": 3600
}

Execute a command inside a sandbox

curl -X POST http://localhost:3000/v1/sandboxes/sb_a1b2c3d4/exec \
  -H 'Content-Type: application/json' \
  -d '{"service": "sentinel", "request": {"method": "inspect", "agent": "test"}}'

Destroy a sandbox

curl -X DELETE http://localhost:3000/v1/sandboxes/sb_a1b2c3d4

Configuration

Env Var	Default	Description
NULLBOX_KERNEL	nullbox-kernel	Path to NullBox kernel image
NULLBOX_INITRAMFS	nullbox-initramfs.cpio.gz	Path to NullBox initramfs

Design

• Raw TcpListener HTTP server (no framework, same as NullBox's nullweb)
• One thread per connection
• QEMU process per sandbox with unique port forwarding
• Port allocation starts at 20000, increments by 10 per sandbox
• Background reaper thread cleans up expired sandboxes every 30 seconds
• Max 10 concurrent sandboxes (hardcoded, configurable in source)
• No auth in v0.1

Requirements

• Rust nightly (edition 2024)
• QEMU with KVM support
• Pre-built NullBox kernel and initramfs images