Nox

Scripting for the
AI Era

Embeddable. Fast. Deterministic. Nox is a statically-typed scripting language designed with strict sandboxing and resource guards, built perfectly for AI agents and host applications.

Get Started Download Latest
agent.nox
bash - 80x24
Architecture & Mechanics

How Nox Protects
and Performs

Explore the core architectural mechanics of the Nox virtual machine. Switch modes, trigger interop calls, and run race conditions to experience the engine in real-time.

CONTAINMENT GUARANTEES

Deterministic Resource Guards

Nox VM isolates untrusted or runaway scripts generated by LLM agents. By setting rigid memory bounds and instruction cycle limits, the engine halts runaway scripts instantly and deterministically, fully protecting the parent process.

  • 100% Host Insulation: CPU resource consumption is blocked from escaping the virtual machine runtime bounds.
  • Deterministic Errors: Throws precise, uncatchable QuotaExceededError exceptions exactly at the specified cycle threshold.
  • Microsecond Halts: VM containment teardowns occur in microseconds, freeing all local registers immediately.
Resource Guards

VM Containment Shield

Host: SECURE

Configure VM Guard

Instruction Limit400,000 inst.
VM Instruction Counter:0
Host CPU Core 0:0.0% (Fully Responsive)
VM IDLE
nox-vm: Ready. Choose a script configuration and click Run Simulation.
Blazing Fast

Zero-GC Primitives Race

Nox VM: Microsecond Boot

VM Benchmarks

Nox VM
0.00s
Latency • 0M ops/s
0 Primitive GC Pauses
Traditional VM
0.00s
Latency • 0M ops/s
0 GC Pauses
Nox VM (Pre-allocated Primitives, Zero-GC pMem)Pipelined
Dynamic VM (Stop-the-World GC Sweeps)Sweeping Soon
benchmark: Click Start Race to observe primitive execution flow and Stop-The-World GC sweeps side-by-side.
PERFORMANCE RATIOS

Flat Registers & Dual-Bank Memory

Traditional script wrappers create high garbage collection overhead by wrapping primitives in objects. Nox splits memory into a flat primitive bank (pMem) and a reference bank (rMem), minimizing GC allocation pressure.

  • Register-Based Architecture: Tight register execution slots with zero-copy base pointer shifts for function calls.
  • Zero-Boxing Primitives: Primitive variables (ints, doubles, booleans) run entirely inside flat arrays, generating zero GC pauses.
  • Compiler-Directed Cleanups: The compiler emits KILL_REF instructions on scope exit, nulling reference slots instantly to permit immediate host reclamation.
PRE-FLIGHT SECURITY

Static Typing & Type-Gate Scanner

Prevent runtime bugs before code even reaches execution. Nox features a strong static type checker with type inference that acts as a secure boundary gate, ensuring only validated data shapes are admitted into the sandbox.

  • Pre-Execution Rejection: Invalid syntax and type-contract violations are blocked at compile time.
  • Strong Type Inference: A scripting syntax that reads smoothly like Python/JS but retains rigid compiler safety and type-checking.
  • Strict Bounds Enforcement: Compiler validation guarantees parameter types match registered host plugin APIs exactly.
Strict Typing

Type-Gate Compiler Scanner

Scanner: Pre-execution Guard
COMPILE CONTRACT (main.nox)
main() {
int score = 42;
boolean active = true;
int limit = "twenty";
}
Compiler Gate Status
Contract:WAITING...
VMSAFE
SCANNER
Conveyor Rail 0Pre-Verification Buffer
compiler: Ready. Click Scan & Compile to analyze typing contracts.
Kotlin Interop

Secure Interop Bridge Funnel

Boundary: Strict Filtering

1. Host Privileges (Kotlin)

Toggle which local JVM resources the embedding application registers into the Nox VM context:

2. Sandbox Interop Script

HOST ENV
SECURE BRIDGE
STANDBY
VM SANDBOX
SCRIPT
Ready. Select a call configuration and click Execute Bridge Call.
HOST BOUNDARY SECURITY

Secure Interop & Funnel Bridging

Integrating scripts shouldn't expose your host app databases or file systems. Nox allows developers to safely export selective Kotlin methods via a capability funnel that restricts raw access, maintaining granular privilege separation.

  • Annotation-Driven Interop: Seamlessly register JVM host methods with zero-overhead @NoxFunction and @NoxModule annotations.
  • Casting Funnel Safety: Outgoing parameters are securely wrapped and checked against defined schemas before boundary transit.
  • Dynamic Capability Controls: Selectively revoke or grant file systems, networks, or DB scopes inside the supervisor runtime bridge per sandbox call.
Ecosystem & Extensibility

3-Tier Plugin Architecture

Extend the sandbox without compromising runtime boundaries or timing predictability. Nox offers a multi-tier extension strategy to run raw JVM code, native shared binaries, or sandboxed script imports.

Tier 0 Kotlin Annotations

Compiled Host Built-ins

Directly compiled inside the host JVM application. Native FFI calls are bound on startup using JIT-optimized JVM MethodHandles, matching static local function speed. 

@NoxModule("math_ext")
object MathExtension {
    @NoxFunction("hypot")
    @JvmStatic
    fun hypot(a: Double): Double
}
Tier 1 Native C ABI

External Shared Plugins

Enables native plugin extension under GraalVM Native Image mode. Dynamically load C/C++ platform shared libraries (.so, .dylib, .dll) via dlopen with zero JVM dependencies. 

#include "nox_plugin.h"
NoxPluginManifest* nox_plugin_init() {
    // Returns native shared manifest
    return &manifest;
}
Tier 2 Nox Imports

Pure Script Imports

Simplest extension model. Import standalone .nox files, name-spaced locally at compile-time. Modules maintain private global scopes to prevent cross-scope data contamination. 

import "utils/math.nox" as math;

main() {
    return math.calculate(42);
}
Deep Dive Architecture

Defense-In-Depth Engineering

Nox implements absolute sandboxing by ensuring that if a primitive, reflection method, or native capability is not explicitly implemented in the VM bytecode, **it does not exist** within the sandbox.

AST-Level Sandboxing

Zero JVM Reflection

Nox compiles strictly to a custom, compact bytecode set instead of JIT compiling to native JVM classes. By bypassing JVM classloaders, Reflection attacks, raw pointer escapes, and classloading injection exploits are physically impossible.

Sliding Window Frames

Zero-Copy Register Shifts

Nox manages calling scopes by shifting Base Pointers (bp / bpRef) forward over pre-allocated register arrays. Function arguments are pre-placed in landing zones, completely avoiding heap copying or frame allocations.

Permission Bridge

Coroutine-Suspended supervisor

Sensitive FFI calls pause VM executions, suspending the Kotlin coroutine to trigger a host supervisor policy engine. The Host evaluates granular contexts (auto-approvals, prompts) before delivering typed approvals or throwing SecurityError.

Timeout Watchdogs

Structured Coroutines

Naïve timing loops crash when blocking calls hang. Nox runs wall-clock watchdogs in separate coroutines alongside the VM execution thread, utilizing Kotlin structured concurrency to forcibly cancel hung VM scopes even during blocked network FFI.

Dynamic Memory Caps

Pre-Flight Allocation Limits

To protect hosts from memory exhaustion, Nox monitors proxy metrics (string lengths, JSON nodes, array element counts) *before* objects enter rMem. Breaching configured caps halts the isolate before JVM OOMs occur.

Isolate Recycling

Ephemeral Coroutine Scopes

Each script execution spawns an entirely clean, single-use coroutine isolate. Isolates share zero static heap state, making persistent cross-sandbox data contamination, side-channel attacks, or context poisoning physically impossible.