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

# FAQ

> Frequently asked questions about Enclave

## General

### What is Enclave?

Enclave is a secure JavaScript execution environment for running untrusted code, such as AI-generated scripts or user-provided code. It provides a defense-in-depth security model with AST validation, code transformation, and runtime sandboxing.

### When should I use Enclave?

Use Enclave when you need to:

* Execute LLM-generated code safely
* Run user-provided scripts in a controlled environment
* Build plugin/extension systems
* Create workflow automation with tool access

### What JavaScript features are supported?

Enclave uses AgentScript, a safe subset of JavaScript. It supports:

* Variables (`const`, `let`)
* Conditionals (`if/else`, ternary)
* Bounded loops (`for`, `for-of`)
* Array methods with arrow functions
* Tool calls via `callTool()`
* Safe globals (`Math`, `JSON`, `Array`, etc.)

See [AgentScript](https://docs.agentfront.dev/enclave/concepts/agentscript.md) for the full specification.

### What's blocked and why?

Blocked constructs include:

* `eval`, `Function` - Prevents code injection
* `process`, `require` - Prevents system access
* `window`, `global` - Prevents sandbox escape
* `while` loops - Prevents infinite loops
* User functions - Prevents recursion bombs

## Security

### How secure is Enclave?

Enclave uses a 6-layer defense-in-depth model:

1. Pre-scanner (size, nesting and literal limits)
2. AST validation (blocked constructs)
3. Code transformation (safe wrappers)
4. AI Scoring Gate (optional, a heuristic risk score)
5. Runtime sandbox (a realm with only the allowed globals, a membrane, limits)
6. Output sanitization

The layers are built to hold independently: the runtime does not rely on the validator having refused a script. What the sandbox does not deliver is stated too. In process, the timeout and the memory limit are the enclave's own accounting, not the engine's, and the worker pool adds a hard stop and a heap limit per worker without leaving the host's process. A host that must survive whatever a script does runs the enclave in a child process or a container with limits of the operating system. See the [Security Model](https://docs.agentfront.dev/enclave/concepts/security-model.md#what-enclave-does-not-protect-against).

### Can scripts access the file system?

No. Scripts have no access to `fs`, `require`, or any Node.js APIs. All external interactions must go through tools you provide.

### Can scripts make network requests?

No. `fetch`, `XMLHttpRequest`, and `WebSocket` are blocked. To allow network access, create a tool that performs the request on behalf of the script.

### Can scripts access environment variables?

No. `process` is blocked. If you need to provide configuration, pass it through custom globals or tools.

## Performance

### What's the performance overhead?

Typical overhead is 5-15ms per execution for validation and transformation. Actual execution time depends on the script complexity and tool call latency.

### How many concurrent executions can I run?

With the default VM adapter, scripts run on the thread that calls `run()`: executions interleave where they await tools, and a script that computes holds the thread. With the worker pool adapter, up to `maxWorkers` scripts run at the same time on worker threads.

### How much memory does each execution use?

It depends on script data and tool responses. `memoryLimit` (1 MB by default) bounds what a script builds, as the enclave counts it: text and arrays that grow. It is an estimate, not a limit of the engine's heap. With the worker pool each worker also has a heap limit (`memoryLimitPerWorker`).

## Tools

### How do I create tools?

Define a tool handler function:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  toolHandler: async (toolName, args) => {
    switch (toolName) {
      case 'users:list':
        return db.users.findAll({ limit: args.limit });
      default:
        throw new Error(`Unknown tool: ${toolName}`);
    }
  },
});
```

### Can scripts call any tool?

Only tools you handle in `toolHandler` are available. Unknown tool calls throw errors. You control exactly what scripts can do.

### How do I limit tool access per user?

A tool handler receives the tool name and the arguments. Create the enclave, or pass a handler to `run()`, for the user the script runs for:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
function handlerFor(userId: string) {
  const allowed = getAllowedToolsForUser(userId);
  return async (name: string, args: Record<string, unknown>) => {
    if (!allowed.includes(name)) {
      throw new Error(`Tool ${name} not allowed`);
    }
    return executeToolSafely(name, args);
  };
}

const result = await enclave.run(code, handlerFor(userId));
```

## Configuration

### Which security level should I use?

| Level | Use Case |
| - | - |
| STRICT | Untrusted AI/user code |
| SECURE | Semi-trusted automation |
| STANDARD | Internal tools |
| PERMISSIVE | Testing only |

### How do I increase the timeout?

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  timeout: 60000, // 60 seconds
});
```

### How do I allow more iterations?

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  maxIterations: 50000, // Default is 10000
});
```

## Streaming

### What is EnclaveJS?

EnclaveJS is a streaming runtime layer that adds real-time code execution with tool orchestration, session management, and client SDKs for browser and React applications.

### When should I use EnclaveJS vs enclave-vm directly?

Use **enclave-vm** directly for:

* Server-side batch processing
* Simple request/response patterns
* Internal tools

Use **EnclaveJS** for:

* Real-time streaming UIs
* React applications
* Browser or remote clients that follow a run on your server

The EnclaveJS broker does not authenticate callers and the client does not encrypt: use HTTPS and put your own authentication in front of the broker.

## Troubleshooting

### Why is my code being blocked?

Read the issues of the failed run:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const result = await enclave.run(code);
if (result.error?.code === 'VALIDATION_ERROR') {
  console.log(result.error.message);
  console.log(result.error.data?.issues);
}
```

Common reasons:

* Using blocked identifiers
* Declaring functions
* Using `while` loops
* Accessing unknown globals

### Why is execution timing out?

Common causes:

* Slow tool calls
* Too many iterations
* Waiting for external resources

Debug by logging tool call durations and reviewing iteration counts.

### Why am I getting "Maximum tool call limit exceeded"?

Your script is making too many tool calls. Solutions:

* Batch operations in tools
* Increase `maxToolCalls`
* Review script logic

## Integration

### Can I use Enclave with TypeScript?

Yes! Enclave is written in TypeScript and provides full type definitions.

### Can I use Enclave in the browser?

`@enclave-vm/core` requires Node.js for the vm module. In a browser, either use [`@enclave-vm/browser`](https://docs.agentfront.dev/enclave/core-libraries/enclave-browser/overview), which runs validated AgentScript in nested iframes, or use the EnclaveJS client SDK to connect to a server running a broker.

### Does Enclave work with Next.js/Express/Fastify?

Yes. Enclave is a library that runs in any Node.js environment. See [Guides](https://docs.agentfront.dev/enclave/guides/first-agent.md) for integration examples.

## Related

* [Common Errors](https://docs.agentfront.dev/enclave/troubleshooting/common-errors.md) - Error reference
* [Debugging](https://docs.agentfront.dev/enclave/troubleshooting/debugging.md) - Debug techniques
* [AgentScript](https://docs.agentfront.dev/enclave/concepts/agentscript.md) - Language specification


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