Secure Exec

Secure Exec is designed for high-performance, isolated code execution in several scenarios:

• AI Agent Tool Use: Executing code generated by LLMs safely.
• User-facing Dev Servers: Running lightweight web frameworks like Express or Hono.
• MCP Tool-code Execution: Implementing Model Context Protocol tools.
• Plugin Systems: Creating sandboxed extension points for your applications.
• Coding Playgrounds: Providing interactive, isolated environments for users to write and run code.

Code Mode is a pattern that allows an AI agent to use a single code-execution tool instead of many individual Model Context Protocol (MCP) tools. Instead of making multiple round-trips to call isolated tools, the LLM writes JavaScript that orchestrates multiple operations (loops, branching, Promise.all) in a single execution. This code is run safely within a Secure Exec V8 sandbox.

Key Benefits:

• Reduced Token Overhead: Replacing dozens of tool descriptions with one code-execution tool can reduce tool description tokens by up to 81%.
• Fewer Round-trips: Multiple tool calls and data transformations are chained in one execution.
• Real Control Flow: The agent can use standard programming constructs like loops and conditionals.
• Structured Output: The agent returns a single JSON value via globalThis.__return(), which the host decodes as result.value.

Secure Exec provides a bridged environment that supports most Node.js core modules and web frameworks.

Supported Node.js Modules

Most core modules are bridged to real host capabilities rather than being stubbed, including:

• fs (Filesystem)
• child_process (Subprocesses)
• http / net (Networking)
• dns
• process
• os

Framework Support

You can run web servers and frameworks out of the box, such as:

• Express
• Hono
• Next.js

Advanced Orchestration

• Long-running tasks: For stateful or durable tasks, it is recommended to pair Secure Exec with Rivet Actors to handle persistence and fault tolerance.
• Production Servers: For production deployments of web servers, pair Secure Exec with Rivet Actors to leverage built-in routing, scaling, and lifecycle management.

Secure Exec virtualizes all VM networking to ensure guest code cannot access the real host network. The networking model is built on several isolation principles:

• Kernel Socket Table: All guest networking (including fetch(), node:http, and raw sockets) is routed through a virtualized kernel socket table rather than the host network.
• Hermetic Loopback: Guests can access loopback services within their own VM, but the socket table is isolated; a guest cannot reach services running on the real host's loopback interface.
• Default Deny Egress: Outbound networking is denied by default. You must explicitly opt-in using the network permission.
• Host-to-Guest Proxying: Host loopback ports are invisible to the guest unless you explicitly expose them using loopbackExemptPorts.

Detecting Failures

A common pattern is to check the exitCode and use stderr to provide diagnostic information when a guest fails:

const { stderr, exitCode } = await rt.exec(code);
if (exitCode !== 0) throw new Error(`guest exited ${exitCode}: ${stderr}`);

Long-running Guests

For processes that are intended to stay alive (like development servers), use spawn() instead of exec() or run(). spawn() returns a live NodeRuntimeProcess handle which provides:

• onStdout / onStderr streaming hooks.
• writeStdin(data) to send data to the guest.
• kill() to terminate the process.
• wait() to await the process exit.

Secure Exec classifies its resource limit constants into three distinct categories. Understanding these classes helps you distinguish between hard system constraints and configurable security policies:

• invariant: Hard limits that are fundamental to the system's stability or correctness. These cannot be changed by users or policies (e.g., MAX_SYMLINK_DEPTH, MAX_PATH_LENGTH).
• policy: Configurable limits that define the security boundary of an execution environment. These are typically used to restrict resource consumption (e.g., DEFAULT_PYTHON_MAX_OLD_SPACE_MB, MAX_WASM_MODULE_FILE_BYTES).
• policy-deferred: Limits that are part of the policy system but may be evaluated or applied at a different stage of the execution lifecycle (e.g., DEFAULT_PROCESS_TIMEOUT_MS).

The architecture provides two primary filesystem engines depending on your use case:

ObjectFs (Direct Mapping)

Maps paths directly to object keys. Best when external tools need to interact with the same bucket layout.

• Semantics: Lossy POSIX. rename is a copy-and-delete; hard links are unsupported; symlinks are marker objects; partial writes rewrite the entire object.
• Storage: One object per file under a configured prefix.

ChunkedFs (Managed POSIX)

A managed filesystem designed for performance and deduplication.

• Semantics: Full POSIX support. Small files are stored inline in metadata; larger files are split into content-addressed chunks.
• Storage: Metadata is authoritative. Blocks are addressed by hash (blake3(content)). Identical chunks are deduplicated automatically.
• Defaults: Inline threshold is 64 KiB; default chunk size is 4 MiB.