Class SandboxedToolForge

Validates agent-generated code and runs it on an executor, by default in an in-process node:vm context (InProcessExecutor). node:vm is not a security mechanism (Node's documentation): the checks here hold for code that acts through the injected functions, and memory is reported, not limited.

Runtime bounds:

  • Memory: observed as a heap delta, not preemptively capped
  • Execution time: configurable wall-clock timeout, default 5000 ms
  • Blocked APIs: eval, Function, process, require, import, child_process, fs.write*

Allowlisted APIs (each requires explicit opt-in):

  • fetch: HTTP requests (the first URL's host is checked when fetchDomainAllowlist is set)
  • fs.readFile: Read-only file access (path-restricted, max 1 MB)
  • crypto: Hashing and HMAC only

Example

const forge = new SandboxedToolForge({ timeoutMs: 3000 });

const result = await forge.execute({
  code: 'function execute(input) { return input.a + input.b; }',
  input: { a: 2, b: 3 },
  allowlist: [],
  memoryMB: 128,
  timeoutMs: 3000,
});

console.log(result.output); // 5

Constructors

constructor

Methods

effectiveOptions attachBroker validateCode execute

Properties

executor

Constructors

constructor

Methods

effectiveOptions

  • effectiveOptions(): {
        memoryMB: number;
        timeoutMs: number;
        fetchDomainAllowlist: string[];
        fsReadRoots: string[];
    }

  • The options this forge runs with, defaults applied. The engine reads them to check a host-built forge against a ceiling.

    Returns {
        memoryMB: number;
        timeoutMs: number;
        fetchDomainAllowlist: string[];
        fsReadRoots: string[];
    }

    • memoryMB: number
    • timeoutMs: number
    • fetchDomainAllowlist: string[]
    • fsReadRoots: string[]

attachBroker

  • attachBroker(broker): void

  • Under a ceiling the engine attaches its broker: from then on the functions injected into forged code are the broker's, and every execution needs a call handle. A forge serves one broker.

    Parameters

    • broker: CapabilityBroker

    Returns void

    Throws

    Error when a different broker is already attached.

validateCode

  • validateCode(code, allowlist): {
        valid: boolean;
        violations: string[];
    }

  • Static analysis of code — reject dangerous patterns before execution.

    Scans the source string for banned API usage patterns using regex matching. The list is read in catalogue names first (fs.readFile stands for fs.read, fs.writeFile for fs.write, fs.unlink for fs.delete).

    Checked patterns (always banned):

    • eval(), new Function(), require(), import, process.*
    • child_process; every fs.write* name but fs.writeFile, every fs.unlink* name but fs.unlink; fs.rm, fs.rmdir, fs.appendFile, fs.truncate

    Conditionally banned (when the list does not grant them):

    • fetch( — without fetch
    • fs.writeFile — without fs.write; fs.unlink — without fs.delete
    • any other fs. reference — without fs.read (or its alias fs.readFile)
    • crypto.* — without crypto

    Parameters

    • code: string

      The raw source code string to validate.

    • allowlist: readonly AllowlistName[]

      The capabilities the code may use, in either name.

    Returns {
        valid: boolean;
        violations: string[];
    }

    valid: true with no violations, or valid: false with a violations array describing each flagged pattern.

    • valid: boolean
    • violations: string[]

    Example

    const forge = new SandboxedToolForge();
    const result = forge.validateCode('eval("exploit")', []);
    // result.valid === false
    // result.violations === ['eval() is forbidden']

execute

  • execute(request): Promise<SandboxExecutionResult>

  • Execute agent-generated code in the sandbox.

    The code must define a function named execute that accepts a single argument and returns the output:

    function execute(input) { return input.a + input.b; }

    Execution flow:

    1. Run validateCode() — reject immediately if violations are found.
    2. Pre-parse the source; a syntax error comes back with a hint.
    3. Build the functions the list grants (the broker's under a ceiling).
    4. Hand the run to the executor and turn its answer into the result.

    Parameters

    Returns Promise<SandboxExecutionResult>

    A SandboxExecutionResult with the output (on success) or error description (on failure), plus execution time telemetry.

    Example

    const result = await forge.execute({
      code: 'function execute(input) { return { sum: input.a + input.b }; }',
      input: { a: 10, b: 20 },
      allowlist: [],
      memoryMB: 128,
      timeoutMs: 5000,
    });
    // result.success === true
    // result.output === { sum: 30 }

Properties

Readonly executor

executor: ForgedCodeExecutor

What runs forged code: the in-process executor unless the host passed one.

Settings

Member Visibility

Theme

On This Page

constructoreffectiveOptionsattachBrokervalidateCodeexecuteexecutor