> ## 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` |
| `timeout` | number | varies | Maximum execution time in milliseconds |
| `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-serializable only) |
| `validate` | boolean | `true` | Validate code with ast-guard before execution |
| `transform` | boolean | `true` | Transform code before execution (AgentScript wrappers) |
| `allowFunctionsInGlobals` | boolean | varies | Whether to allow functions in custom globals. Functions never cross the iframe boundary; 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) |

## 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 |

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

```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 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.

```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'],

    // These are silently skipped (not serializable)
    // handler: () => {},       // function
    // element: document.body,  // DOM node
  },
});

// 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.
</Warning>

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

```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](/enclave/core-libraries/enclave-browser/overview) - Getting started
* [Security Architecture](/enclave/core-libraries/enclave-browser/security-architecture) - Isolation model details
* [@enclave-vm/core Configuration](/enclave/core-libraries/enclave-vm/configuration) - Node.js configuration reference
* [Security Levels](/enclave/core-libraries/enclave-vm/security-levels) - Security preset details


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