Skip to main content

Class: SandboxedToolForge

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:164

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​

new SandboxedToolForge(config?): SandboxedToolForge

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:192

Create a new SandboxedToolForge instance.

Parameters​

config?​

SandboxedToolForgeConfig

Optional configuration overrides. All fields have sensible defaults (128 MB memory, 5000 ms timeout, no domain restrictions).

Returns​

SandboxedToolForge

Properties​

executor​

readonly executor: ForgedCodeExecutor

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:184

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

Methods​

attachBroker()​

attachBroker(broker): void

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:221

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.


effectiveOptions()​

effectiveOptions(): object

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:205

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

Returns​

object

fetchDomainAllowlist​

fetchDomainAllowlist: string[]

fsReadRoots​

fsReadRoots: string[]

memoryMB​

memoryMB: number

timeoutMs​

timeoutMs: number


execute()​

execute(request): Promise<SandboxExecutionResult>

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:390

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​

request​

SandboxExecutionRequest

The execution request containing code, input, allowlist, and resource limits.

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 }

validateCode()​

validateCode(code, allowlist): object

Defined in: packages/agentos/src/cognition/emergent/SandboxedToolForge.ts:309

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​

object

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

valid​

valid: boolean

violations​

violations: string[]

Example​

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