Use Cases

Code Mode (MCP)

Example on GitHub Full working example: the LLM chains real host-tool calls in one sandboxed run and returns a structured result.

Instead of calling MCP tools one at a time, Code Mode lets the LLM write JavaScript that orchestrates everything in one go, run safely in a V8 sandbox by Secure Exec.

Why Code Mode

81% less token overhead: With 50 tools, replacing per-call tool descriptions with a single code-execution tool cuts tool description tokens by 81%
Fewer round-trips: Chain multiple tool calls, conditionals, and data transformations in a single execution
Real control flow: Loops, branching, and Promise.all, not a chain of isolated tool calls
One structured result: The LLM returns a single JSON value via globalThis.__return(), decoded on the host as result.value

How it works

Register your host tools on the host with NodeRuntime.create({ tools }). Each becomes a named command inside the sandbox.
Give the LLM one tool (“execute code”) and feed its generated JavaScript to rt.run().
The generated code invokes your tools by name. Each call round-trips out of the sandbox, runs the tool’s host handler, and the handler’s return value comes back to the guest.
The guest hands a single structured result back to the host with globalThis.__return(value), which rt.run() decodes as result.value.

Host tools are the heart of Code Mode. The handlers run on the host, never in the sandbox, so the guest gets controlled, named capabilities (the kind an AI agent calls as tools) without being granted the underlying access. Registering tools auto-grants the tool permission scope; pass your own permissions.tool policy to gate individual tools.

Register the host tools

Each tool has a description, a JSON Schema inputSchema, and a handler. The handler receives the parsed input and returns a JSON-serializable result.

import { NodeRuntime } from "secure-exec";

// Register the host tools. These handlers run on the HOST, not in the sandbox.
// In a real app each handler would hit a database, an API, or a service; here we
// keep them small and deterministic so the example is easy to follow.
const rt = await NodeRuntime.create({
  tools: {
    "get-weather": {
      description: "Look up the current temperature for a city",
      inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
      handler: ({ city }: { city: string }) => {
        const table: Record<string, { temp_f: number }> = {
          "San Francisco": { temp_f: 61 },
          Tokyo: { temp_f: 75 },
        };
        return table[city] ?? { temp_f: null };
      },
    },
    calculate: {
      description: "Evaluate a simple arithmetic expression",
      inputSchema: {
        type: "object",
        properties: { expression: { type: "string" } },
        required: ["expression"],
      },
      handler: ({ expression }: { expression: string }) => {
        return { result: Number(eval(expression)) };
      },
    },
  },
});

The agent’s generated code

The agent then generates code like this (call it llmGeneratedCode). The guest calls each tool with the callHostTool(name, input) global, which resolves with the host handler’s return value. It chains three tool calls with real control flow (Promise.all, arithmetic, branching) in one execution, then returns a single structured result:

// Imagine this string was written by the LLM. It chains three host-tool calls
// with real control flow (Promise.all, arithmetic, branching) in one execution,
// then hands a single structured result back to the host. callHostTool resolves
// with the host handler's return value.
const llmGeneratedCode = `
const [sf, tokyo] = await Promise.all([
  callHostTool("get-weather", { city: "San Francisco" }),
  callHostTool("get-weather", { city: "Tokyo" }),
]);

const diffF = Math.abs(sf.temp_f - tokyo.temp_f);
const diffC = await callHostTool("calculate", { expression: \`\${diffF} * 5 / 9\` });

console.log("chained 3 tool calls in one sandbox execution");

globalThis.__return({
  san_francisco: sf,
  tokyo: tokyo,
  difference: { fahrenheit: diffF, celsius: diffC.result },
  warmer: sf.temp_f > tokyo.temp_f ? "San Francisco" : "Tokyo",
});
`;

Run it and read the result

Run the LLM’s code in one sandboxed pass and read back the structured result:

try {
  // rt.run() executes the guest code and decodes whatever it passes to
  // globalThis.__return(), while still capturing stdout/stderr/exitCode.
  const result = await rt.run(llmGeneratedCode, { timeout: 5000 });

  console.log("exitCode:", result.exitCode);
  console.log("stdout:", result.stdout.trim());
  console.log("structured result:", JSON.stringify(result.value, null, 2));
} finally {
  await rt.dispose();
}

See Full Example

Three tool calls, one sandbox execution, zero extra LLM round-trips. Running it prints:

exitCode: 0
stdout: chained 3 tool calls in one sandbox execution
structured result: {
  "san_francisco": {
    "temp_f": 61
  },
  "tokyo": {
    "temp_f": 75
  },
  "difference": {
    "fahrenheit": 14,
    "celsius": 7.777777777777778
  },
  "warmer": "Tokyo"
}