Configuration

This page documents all configuration options for @enclave-vm/browser.

Quick Example

import { BrowserEnclave } from '@enclave-vm/browser';

const enclave = new BrowserEnclave({
  // Security level preset
  securityLevel: 'SECURE',

  // Core limits
  timeout: 10000,
  maxToolCalls: 50,
  maxIterations: 5000,
  memoryLimit: 2 * 1024 * 1024, // 2MB

  // Tool handler
  toolHandler: async (name, args) => {
    return executeToolSafely(name, args);
  },

  // Additional options
  globals: { context: { userId: 'user-123' } },
  validate: true,
  transform: true,
});

Core Options

Option	Type	Default	Description
`securityLevel`	string	`'STANDARD'`	Preset: `STRICT`, `SECURE`, `STANDARD`, `PERMISSIVE`
`preset`	string	`'agentscript'`	AST preset: `agentscript`, `strict`, `secure`, `standard`, `permissive`
`timeout`	number	varies	Maximum execution time in milliseconds. Time spent waiting for `toolHandler` does not count toward the hard stop, so a tool call in progress is never cut off; once `timeout` has passed, the script’s next tool call fails with `Execution aborted` (same as `@enclave-vm/core`)
`maxToolCalls`	number	varies	Maximum tool calls per execution
`maxIterations`	number	varies	Maximum loop iterations (per loop)
`memoryLimit`	number	1048576	Memory limit in bytes (soft tracking)
`toolHandler`	function	-	Async function that handles `callTool()` invocations
`toolNamespaces`	object	-	Expose tools as `ns.method(args)`: `{ mail: ['list', 'send'] }` or `{ users: { get: 'users:get' } }`. Each call is a `callTool()` call, validated by the outer iframe. Same naming rules as `@enclave-vm/core`
`globals`	object	-	Additional globals available in the sandbox (JSON data only; the constructor throws for a function, symbol, BigInt, circular structure, Map, Set, RegExp or `undefined`)
`validate`	boolean	`true`	Validate code with ast-guard before execution
`transform`	boolean	`true`	Transform code before execution (AgentScript wrappers)
`allowFunctionsInGlobals`	boolean	varies	No effect in the browser: functions never cross the iframe boundary, so a function in `globals` always throws. Expose host capabilities as tools
`sanitizeStackTraces`	boolean	varies	Sanitize the stack of every error `run()` returns (frames become `at [REDACTED]`, URLs and paths are redacted)
`maxSanitizeDepth`	number	varies	Maximum nesting depth of the value a script returns; a deeper value fails the run
`maxSanitizeProperties`	number	varies	Maximum properties (keys, array elements, Map and Set entries, over the whole value) a script may return; a larger value fails the run

Console Limits

Option	Type	Default	Description
`maxConsoleOutputBytes`	number	varies	Maximum total console output in bytes
`maxConsoleCalls`	number	varies	Maximum number of console calls

Security Level Comparison

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

Setting	STRICT	SECURE	STANDARD	PERMISSIVE
`timeout`	5000	15000	30000	60000
`maxIterations`	1000	5000	10000	100000
`maxToolCalls`	10	50	100	1000
`maxConsoleOutputBytes`	64KB	256KB	1MB	10MB
`maxConsoleCalls`	100	500	1000	10000
`maxSanitizeDepth`	5	10	20	50
`maxSanitizeProperties`	50	100	500	1000
`sanitizeStackTraces`	true	true	false	false
`blockTimingAPIs`	true	false	false	false
`allowUnboundedLoops`	false	false	true	true
`unicodeSecurityCheck`	true	true	false	false
`allowFunctionsInGlobals`	false	false	false	true
`secureProxy.blockConstructor`	true	true	true	false
`secureProxy.blockPrototype`	true	true	true	true
`secureProxy.blockLegacyAccessors`	true	true	true	true
`secureProxy.proxyMaxDepth`	5	10	15	20
`secureProxy.throwOnBlocked`	true	true	true	false

Secure Proxy Configuration

Override proxy behavior for the current security level:

Option	Type	Default	Description
`secureProxyConfig.blockConstructor`	boolean	varies	Block access to `.constructor`
`secureProxyConfig.blockPrototype`	boolean	varies	Block access to `.__proto__` and `.prototype`
`secureProxyConfig.blockLegacyAccessors`	boolean	varies	Block `__defineGetter__`, `__defineSetter__`, etc.
`secureProxyConfig.proxyMaxDepth`	number	varies	Maximum nesting depth for proxy wrapping
`secureProxyConfig.throwOnBlocked`	boolean	varies	Throw error vs return `undefined` on blocked access

const enclave = new BrowserEnclave({
  securityLevel: 'STANDARD',
  secureProxyConfig: {
    throwOnBlocked: false, // Return undefined instead of throwing
    proxyMaxDepth: 5,      // Limit proxy nesting
  },
});

Double Iframe Configuration

Configure the outer iframe security barrier:

Option	Type	Default	Description
`doubleIframe.enabled`	boolean	`true`	Enable double iframe isolation
`doubleIframe.parentTimeoutBuffer`	number	`1000`	Extra timeout for outer iframe (ms)
`doubleIframe.parentValidation.validateOperationNames`	boolean	`true`	Validate tool names
`doubleIframe.parentValidation.allowedOperationPattern`	RegExp	-	Whitelist pattern for tool names
`doubleIframe.parentValidation.blockedOperationPatterns`	RegExp[]	-	Blacklist patterns for tool names
`doubleIframe.parentValidation.maxOperationsPerSecond`	number	`100`	Rate limit for tool calls
`doubleIframe.parentValidation.blockSuspiciousSequences`	boolean	`true`	Detect multi-step attack patterns
`doubleIframe.parentValidation.rapidEnumerationThreshold`	number	`30`	Same-operation repetition threshold
`doubleIframe.parentValidation.rapidEnumerationOverrides`	object	`{}`	Per-operation threshold overrides
`doubleIframe.parentValidation.suspiciousPatterns`	array	`[]`	Custom detection patterns

const enclave = new BrowserEnclave({
  doubleIframe: {
    enabled: true,
    parentTimeoutBuffer: 2000,
    parentValidation: {
      validateOperationNames: true,
      allowedOperationPattern: /^[a-z]+:[a-z]+$/i,
      blockedOperationPatterns: [/^admin:/i, /^system:/i],
      maxOperationsPerSecond: 50,
      blockSuspiciousSequences: true,
    },
  },
});

Built-in Suspicious Patterns

These patterns are detected automatically when blockSuspiciousSequences is enabled:

Pattern	Description
`EXFIL_LIST_SEND`	List/query operation followed by send/export
`RAPID_ENUMERATION`	Same operation repeated beyond threshold in 5s window
`CREDENTIAL_EXFIL`	Credential access followed by external operation
`BULK_OPERATION`	Bulk/batch/mass/dump operations or unlimited queries
`DELETE_AFTER_ACCESS`	Delete operation after data read (potential cover-up)

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.

const enclave = new BrowserEnclave({
  globals: {
    // These work (JSON-serializable)
    config: { apiVersion: 'v2', maxRetries: 3 },
    userId: 'user-123',
    features: ['search', 'export'],

    // This throws at construction: expose host functions as tools instead
    // handler: () => {},
  },
});

// In sandboxed code:
// const version = config.apiVersion; // 'v2'
// const id = userId;                 // 'user-123'

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.

Tool Namespaces and callTool Options

const enclave = new BrowserEnclave({
  toolHandler: async (name, args) => callMyTool(name, args),
  toolNamespaces: { mail: ['list', 'send'] },
});

await enclave.run(`
  const inbox = await mail.list({});
  const r = await callTool('users:get', { id: inbox[0].from }, { throwOnError: false });
  return r.success ? r.data : r.error.message;
`);

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.

Overview - Getting started
Security Architecture - Isolation model details
@enclave-vm/core Configuration - Node.js configuration reference
Security Levels - Security preset details

Get Started

Concepts

@enclave-vm/core

@enclave-vm/browser

@enclave-vm/ast

EnclaveJS Streaming

Guides

Examples

Troubleshooting

Quick Example

Core Options

Console Limits

Security Level Comparison

Secure Proxy Configuration

Double Iframe Configuration

Built-in Suspicious Patterns

Custom Globals

Tool Namespaces and callTool Options

​Quick Example

​Core Options

​Console Limits

​Security Level Comparison

​Secure Proxy Configuration

​Double Iframe Configuration

​Built-in Suspicious Patterns

​Custom Globals

​Tool Namespaces and callTool Options

​Related

Quick Example

Core Options

Console Limits

Security Level Comparison

Secure Proxy Configuration

Double Iframe Configuration

Built-in Suspicious Patterns

Custom Globals

Tool Namespaces and callTool Options

Related