Skip to main content
This page documents all configuration options for @enclave-vm/browser.

Quick Example

Core Options

Every numeric option on this page (timeout, maxToolCalls, maxIterations, memoryLimit, maxSanitizeDepth, maxSanitizeProperties, maxConsoleOutputBytes, maxConsoleCalls, doubleIframe.parentTimeoutBuffer) must be a finite number of 0 or more. The constructor throws a TypeError for anything else: a number written as text ('5000'), NaN, Infinity, a negative value. For a limit that should never be reached, pass Number.MAX_SAFE_INTEGER. The exception is toolCallGraceMs, which takes Infinity.

Console Limits

Security Level Comparison

All “varies” defaults above depend on the selected security level:

Secure Proxy Configuration

Override proxy behavior for the current security level:

Double Iframe Configuration

Configure the outer iframe security barrier:

Built-in Suspicious Patterns

These patterns are detected automatically when blockSuspiciousSequences is enabled: These patterns are heuristics over tool names and arguments. They run in the outer iframe, which keeps a record of the tool calls of the last two seconds: a sequence whose steps are further apart than that is not detected, and RAPID_ENUMERATION counts the same operation within those two seconds.

Custom Suspicious Patterns

There are two ways to add a pattern, and they run in different places:
A call a pattern detects is refused: the script’s callTool rejects with Suspicious pattern detected: <description> [<id>] and the handler is not called. A function-based pattern that throws refuses the call as well. Both kinds are off when blockSuspiciousSequences is false. The constructor throws a TypeError for an entry of suspiciousPatterns without a detect function.

Custom Globals

Inject read-only data into the sandbox. Only JSON-serializable values are supported — functions cannot cross the iframe boundary. The constructor throws for a global that is or contains a function or symbol (also one hidden behind toJSON()), a BigInt, a circular structure, or a value JSON would turn into {} (Map, Set, RegExp, DOM node, …), and for an undefined global. The error names the global and the path (Custom global "cfg" contains a function at "hooks.0.run"), so the problem shows up before any script runs. Dates are passed as ISO strings.
Custom globals are only supported with the agentscript preset (the default). Using globals with other presets will throw an error.
Each custom global is also available with a __safe_ prefix (e.g., config and __safe_config), matching the pattern used by AgentScript’s code transformation. A script reaches a custom global, or a tool namespace, as a parameter of the function it runs in. The name therefore means your value even when the frame’s window has a property of that name (location, name, top, history) or the sandbox’s own code has a variable of that name (timeout, result).

Tool Namespaces and callTool Options

A namespace call is a callTool() call: counted toward maxToolCalls and checked by the outer iframe (rate limit, operation names, suspicious sequences). With { throwOnError: false }, a failing tool resolves to { success: false, error: { name, message, code?, toolName } } and a working one to { success: true, data }; refusals by the enclave still throw.