Class SandboxedToolForge

Runs agent-generated code in an isolated sandbox with strict resource limits.

Attempts to use isolated-vm for true V8 isolate sandboxing. Falls back to Node.js vm module with timeout if isolated-vm is not installed.

Resource limits:

  • Memory: configurable, default 128 MB
  • Execution time: configurable, default 5000 ms
  • Blocked APIs: eval, Function, process, require, import, child_process, fs.write*

Allowlisted APIs (each requires explicit opt-in):

  • fetch: HTTP requests (domain-restricted)
  • 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

validateCode execute

Constructors

constructor

Methods

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. If an API is not present in the allowlist, references to it are also flagged.

    Checked patterns (always banned):

    • eval(), new Function(), require(), import, process.*
    • child_process, fs.write*, fs.unlink, fs.rm, fs.rmdir

    Conditionally banned (when not in allowlist):

    • fetch( — when 'fetch' is not in the allowlist
    • fs.* — when 'fs.readFile' is not in the allowlist
    • crypto.* — when 'crypto' is not in the allowlist

    Parameters

    • code: string

      The raw source code string to validate.

    • allowlist: SandboxAPI[]

      The set of APIs the code is permitted to use.

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

    An object with valid: true if no violations were found, 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. Wrap the agent's code into a self-contained expression that calls execute.
    3. Run in a Node.js vm sandbox with a restricted global context.
    4. Parse the output, measure execution time, and return 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 }

Settings

Member Visibility

Theme

On This Page

constructorvalidateCodeexecute