V8 Execution Sandbox
Relevant source files
The following files were used as context for generating this wiki page:
The V8 Execution Sandbox provides an isolated environment for executing untrusted TypeScript programs authored by AI agents. This sandbox ensures that programs operate with restricted capabilities, preventing unauthorized network access, file system manipulation, or credential leakage. Sources: README.md:14-17, crates/coral-v8/tests/program_runtime.rs:25-33
The system utilizes the V8 engine to execute emitted JavaScript after a compilation phase that enforces strictly defined TypeScript profiles. Every execution run is recorded, and every external call is checked against a user-defined policy. Sources: README.md:65-72, crates/coral-v8/tests/program_runtime.rs:35-64
Architecture and Components
The sandbox architecture separates program compilation from execution. A ProgramCompiler validates and transforms TypeScript into sandboxed JavaScript, while a ProgramExecutor manages the lifecycle of the execution isolate. Sources: crates/coral-v8/tests/program_runtime.rs:36-39, crates/coral-v8/tests/program_runtime.rs:175-180
Key Components
| Component | Description |
|---|---|
ProgramCompiler | Validates TypeScript syntax, checks for forbidden capabilities, and generates a sandboxed JavaScript bundle. |
ProgramExecutor | Manages the V8 Isolate, enforces resource limits, and executes the compiled code. |
ProgramHost | A trait implemented by the embedding application to handle I/O, such as operation invocations, logging, and emissions. |
ProgramExecutionControl | Provides methods to terminate a running isolate from a separate thread. |
Sources: crates/coral-v8/tests/program_runtime.rs:36-70, crates/coral-v8/tests/program_runtime.rs:710-738, crates/coral-v8/tests/program_runtime.rs:72-88
Execution Flow
The following diagram illustrates the flow from TypeScript source to final execution outcome:
The diagram shows the transition from authored source through the compiler's security gates to execution via a controlled Host interface. Sources: crates/coral-v8/tests/program_runtime.rs:36-64, crates/coral-v8/src/js/compiler/saved_function_linking.js:143-200, README.md:65-72
Capability Restrictions
The sandbox enforces strict "no-imports" and "no-ambient-globals" policies. Programs cannot access Node.js internals, browser APIs, or sensitive environment variables. Sources: crates/coral-v8/tests/program_runtime.rs:434-450, crates/coral-v8/tests/program_runtime.rs:528-560
Forbidden APIs
The sandbox explicitly removes or blocks access to:
- Networking:
fetch,XMLHttpRequest,WebSocket,EventSource. - System/Environment:
process,require,module,Deno,Bun. - Storage/Filesystem:
File,FileReader,localStorage. - Dynamic Code:
eval,new Function. - Binary Buffers:
ArrayBuffer,SharedArrayBuffer,DataView, and typed arrays (e.g.,Uint8Array).
Sources: crates/coral-v8/tests/program_runtime.rs:434-445, crates/coral-v8/tests/program_runtime.rs:528-560, crates/coral-v8/tests/program_runtime.rs:582-600
The coral Host Root
Programs interact with the outside world exclusively through the coral global object. This object is projected into the sandbox at runtime and provides typed access to providers and saved functions. Sources: crates/coral-v8/src/js/compiler/typescript_environment.js:20-40, crates/coral-v8/src/js/compiler/saved_function_linking.js:154-175
Interaction Methods
coral.providers: Provides access to external services (e.g., GitHub, Slack) via defined operations.coral.functions: Accesses previously saved and typed programs.coral.emit(value): Sends data back to the caller without ending the program.coral.OperationError: A specialized error class for handling failed external calls.
Sources: crates/coral-v8/src/js/compiler/typescript_environment.js:20-45, crates/coral-v8/tests/program_runtime.rs:658-680, crates/coral-v8/tests/program_runtime.rs:1143-1160
This sequence demonstrates how internal JavaScript calls are marshaled to the Rust host for policy enforcement. Sources: crates/coral-v8/tests/program_runtime.rs:658-680, crates/coral-v8/tests/program_runtime.rs:710-738, README.md:126-140
Saved Function Linking
The sandbox supports "Saved Functions," which are modular pieces of code that can be called by other programs. The linker generates private bindings (__coralSavedFunctionDefaults) to securely inject these dependencies into the program's scope. Sources: crates/coral-v8/src/js/compiler/saved_function_linking.js:143-200, crates/coral-v8/tests/program_runtime.rs:374-400
Security Boundaries in Linking
The linker ensures that authored code cannot reach private compiler bindings. It blanks out export keywords and renames default exports to unique, hygiene-protected identifiers like __coralSavedFunctionDefaultExport_1 to prevent collisions. Sources: crates/coral-v8/src/js/compiler/saved_function_linking.js:56-100, crates/coral-v8/tests/program_runtime.rs:374-432
Resource and Execution Limits
To prevent denial-of-service or infinite loops, the sandbox enforces several limits:
- Timeouts: Compilation is bounded by
COMPILATION_TIMEOUT. Execution is bounded by the host (default 15 minutes). Sources: crates/coral-v8/tests/program_runtime.rs:20-22, crates/coral-mcp/src/arguments.rs:24-25 - Memory/Isolate Limits:
IsolateLimitsdefine memory constraints for the V8 isolate. Sources: crates/coral-v8/tests/program_runtime.rs:36, crates/coral-v8/tests/program_runtime.rs:175 - Termination:
ProgramExecutionControl::terminate()allows the host to force-kill non-cooperative JavaScript (e.g.,while(true) {}). Sources: crates/coral-v8/tests/program_runtime.rs:72-88 - JSON Serialization: Final values and operation arguments are subject to byte size limits (e.g.,
HOST_BYTES). Sources: crates/coral-v8/tests/program_runtime.rs:945-950, crates/coral-v8/tests/program_runtime.rs:1074-1100
Error Handling
Errors within the sandbox are captured and sanitized before being reported to the user. The sandbox distinguishes between:
CompilationError: Syntax or capability violations found during the build phase.ProgramRejected: Uncaught runtime exceptions, including stack traces mapped back to authored locations.ProgramHostTerminated: Errors caused by external termination or host failure.OperationError: Catchable errors returned by external providers.
Sources: crates/coral-v8/tests/program_runtime.rs:205-230, crates/coral-v8/tests/program_runtime.rs:1143-1175, crates/coral-v8/tests/program_runtime.rs:72-88, crates/coral-v8/src/js/compiler/typescript_environment.js:28-35
Summary
The V8 Execution Sandbox is a critical security layer that allows AI agents to execute complex logic safely. By combining a restricted TypeScript profile, static analysis of capabilities, and a controlled host-interop interface, it prevents untrusted code from compromising system integrity or accessing sensitive user data. Sources: README.md:14-30, AGENTS.md:15-20