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

# Overview

> Secure JavaScript execution environment with defense-in-depth architecture for running untrusted and LLM-generated code safely

Enclave is a secure execution environment for running untrusted JavaScript code. It provides a defense-in-depth security model that combines AST validation (via ast-guard), code transformation, and runtime sandboxing to safely execute model-generated code.

> [card] AST Validation
>
> Block dangerous constructs before execution using ast-guard's AgentScript preset

> [card] Code Transformation
>
> Automatically transform code for safe execution with proxied functions and loop limits

> [card] Runtime Sandboxing
>
> Execute in isolated Node.js vm context with controlled globals and resource limits

## When to Use Enclave

Enclave is designed for scenarios where you need to execute JavaScript code from untrusted sources:

* **LLM-generated code** - Execute code written by AI models safely
* **User-provided scripts** - Run user scripts in a controlled environment
* **Plugin/extension systems** - Allow third-party code to run securely
* **Workflow automation** - Execute orchestration logic with tool access

## Installation

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
npm install @enclave-vm/core
```

## Quick Start

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave } from '@enclave-vm/core';

// Create an enclave with a tool handler
const enclave = new Enclave({
  timeout: 5000, // 5 second timeout
  maxToolCalls: 50, // Max 50 tool calls
  maxIterations: 10000, // Max 10K loop iterations
  toolHandler: async (toolName, args) => {
    // Handle tool calls from the script
    console.log(`Tool called: ${toolName}`, args);
    return { result: 'data' };
  },
});

// Execute AgentScript code
const code = `
  const users = await callTool('users:list', { limit: 10 });
  const filtered = users.filter(u => u.active);
  return filtered.length;
`;

const result = await enclave.run(code);

if (result.success) {
  console.log('Result:', result.value);
  console.log('Stats:', result.stats);
} else {
  console.error('Error:', result.error);
}

// Clean up
enclave.dispose();
```

## Execution Results

Enclave returns a structured result with success/error status and execution stats:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ExecutionResult<T> {
  success: boolean;
  value?: T;              // Result value (if success)
  error?: {               // Error details (if failed)
    name: string;
    message: string;
    code?: string;
    stack?: string;       // Only for errors made outside the sandbox
    data?: Record<string, unknown>;
  };
  stats: {
    duration: number;      // Execution time in ms
    toolCallCount: number; // Number of tool calls made
    iterationCount: number; // Number of loop iterations
  };
}
```

### Error Codes

| Code | Meaning | Action |
| - | - | - |
| `VALIDATION_ERROR` | AST validation failed, or the script is too large | Fix the code - blocked construct used |
| `DOUBLE_VM_EXECUTION_ERROR` | The script failed in the sandbox: an error it did not catch, a failed tool call, the tool-call or iteration limit, a timeout (`error.message` says which) | Fix script logic, check the tool, or raise the limit |
| `MEMORY_LIMIT_EXCEEDED` | Memory limit exceeded | Reduce memory usage or increase limit |
| `SECURITY_VIOLATION` | A dynamic import, or a blocked operation at `STRICT` or `SECURE` | Fix the code |
| `ENCLAVE_ERROR` | A failure outside the sandbox, such as a syntax error in the script | Fix the code |

See [Configuration](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/configuration.md#error-codes) for the complete list. `name` and `message` are strings of bounded length whatever a script threw, and an error made inside the sandbox has no `stack`.

## Related

* [Security Levels](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/security-levels.md) - Pre-configured security profiles
* [Tool System](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/tool-system.md) - Integrating tools with enclave
* [Configuration](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/configuration.md) - All configuration options
* [ast-guard](https://docs.agentfront.dev/enclave/core-libraries/ast-guard/overview.md) - AST validation library


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