> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete configuration reference for @enclave-vm/browser

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

## Quick Example

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` |
| `preScan` | object | the pre-scanner preset named like `preset` | `{ preset?, config? }`: the [pre-scanner](https://docs.agentfront.dev/enclave/core-libraries/ast-guard/pre-scanner.md) preset the text of a script is checked with before anything parses it, and overrides of single limits. The default `agentscript` pre-scanner takes 100 KB in 1,000 lines of at most 2,000 characters and refuses regular-expression literals and bidirectional or invisible control characters. Not consulted with `validate: false` |
| `timeout` | number | varies | Maximum execution time in milliseconds (at most 2,147,483,647, the longest delay a timer takes). Time spent waiting for `toolHandler` does not count toward the hard stop, so a tool call in progress is not cut off at the deadline; once `timeout` has passed, the script's next tool call fails with `Execution aborted` (same as `@enclave-vm/core`). A script that computes without yielding is ended at the timeout only where the browser runs the sandbox frames in another process than the page: see [Timeouts and the Browser's Process Model](https://docs.agentfront.dev/enclave/core-libraries/enclave-browser/security-architecture.md#timeouts-and-the-browsers-process-model) |
| `toolCallGraceMs` | number | `timeout` | How long a tool call that is still in progress when `timeout` has passed may take to deliver. When that is over as well, `run()` returns the timeout error (`EXECUTION_TIMEOUT`, with `error.data.pendingHostCalls`) and what the handler returns later is dropped. `0` ends the run at the hard stop; `Infinity` waits for the handler however long it takes (same as `@enclave-vm/core`). The host page's hard stop is `timeout` plus `doubleIframe.parentTimeoutBuffer` (1,000 ms by default), and the grace is counted from there: with `timeout: 100` and `toolCallGraceMs: 0` a run whose tool call does not return ends about 1,100 ms after it started |
| `maxToolCalls` | number | varies | Maximum tool calls per execution |
| `maxIterations` | number | varies | Maximum loop iterations (per loop) |
| `memoryLimit` | number | 1048576 | Limit in bytes on what the tracked operations allocate over a run (`repeat`, `padStart`, `padEnd`, `join`, `fill`); other allocations are not counted. `0` turns the tracking off |
| `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`). Each run reads the values again, so a change inside a global is picked up; a global that changes between a string and another kind of value fails the run with `GLOBALS_CHANGED` (scripts are validated against what each global was when the enclave was created). A name the runtime owns (one starting with `__safe_`, `__ag_` or `__iter_`, and `__maxIterations`) is refused with a `TypeError` |
| `validate` | boolean | `true` | Validate code with ast-guard before execution. Several guarantees hold only for a validated script: see [What Each Guarantee Rests On](https://docs.agentfront.dev/enclave/core-libraries/enclave-browser/security-architecture.md#what-each-guarantee-rests-on). With `false`, a script still cannot use the frame's document or open a connection, but it can reach the sandbox's own variables |
| `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 |

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

| 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 | No effect in the browser: a value is wrapped when it is read, at any depth, and the blocked properties are refused at every one of them |
| `secureProxyConfig.throwOnBlocked` | boolean | varies | Throw error vs return `undefined` on blocked access |

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new BrowserEnclave({
  securityLevel: 'STANDARD',
  secureProxyConfig: {
    throwOnBlocked: false, // Return undefined instead of throwing
  },
});
```

## Double Iframe Configuration

Configure the outer iframe security barrier:

| Option | Type | Default | Description |
| - | - | - | - |
| `doubleIframe.enabled` | boolean | `true` | No effect: the two iframes are how the package runs a script, and are always used |
| `doubleIframe.parentTimeoutBuffer` | number | `1000` | Milliseconds the host page adds to `timeout` for its own hard stop, so that the outer iframe can report its timeout first |
| `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 as functions: `{ id, description, detect(operationName, args, history) }`. See [Custom Suspicious Patterns](#custom-suspicious-patterns) |

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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 within the recorded calls |
| `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) |

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:

| Option | Form | Where it runs | What it sees |
| - | - | - | - |
| `customSerializablePatterns` | `{ id, description, detectBody }`: the body of `function (operationName, args, history)` as source text | In the outer iframe, with the built-in patterns | The calls of the last two seconds |
| `doubleIframe.parentValidation.suspiciousPatterns` | `{ id, description, detect }`: a function | In the host page, for every tool call that passed the tool-call limit and the name patterns, just before your tool handler | The tool name, the copy of the arguments the handler would receive, and the earlier calls of the execution that reached a handler (the last 10,000) |

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new BrowserEnclave({
  toolHandler,
  doubleIframe: {
    parentValidation: {
      suspiciousPatterns: [
        {
          id: 'EXPORT_AFTER_READ',
          description: 'export after a read',
          detect: (operationName, args, history) =>
            operationName === 'report:export' && history.some((call) => call.operationName.startsWith('crm:')),
        },
      ],
    },
  },
});
```

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.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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'
```

> [!WARNING]
>
> 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

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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.

## Related

* [Overview](https://docs.agentfront.dev/enclave/core-libraries/enclave-browser/overview.md) - Getting started
* [Security Architecture](https://docs.agentfront.dev/enclave/core-libraries/enclave-browser/security-architecture.md) - Isolation model details
* [@enclave-vm/core Configuration](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/configuration.md) - Node.js configuration reference
* [Security Levels](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/security-levels.md) - Security preset details


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.