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 whenfetchDomainAllowlistis 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?
Optional configuration overrides. All fields have sensible defaults (128 MB memory, 5000 ms timeout, no domain restrictions).
Returns
SandboxedToolForge
Properties
executor
readonlyexecutor: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:
- Run
validateCode()— reject immediately if violations are found. - Pre-parse the source; a syntax error comes back with a hint.
- Build the functions the list grants (the broker's under a ceiling).
- Hand the run to the executor and turn its answer into the result.
Parameters
request
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; everyfs.write*name butfs.writeFile, everyfs.unlink*name butfs.unlink;fs.rm,fs.rmdir,fs.appendFile,fs.truncate
Conditionally banned (when the list does not grant them):
fetch(— withoutfetchfs.writeFile— withoutfs.write;fs.unlink— withoutfs.delete- any other
fs.reference — withoutfs.read(or its aliasfs.readFile) crypto.*— withoutcrypto
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']