Skip to main content

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

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:

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:

Configuration

Which security level should I use?

How do I increase the timeout?

How do I allow more iterations?

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:
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, 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 for integration examples.