README.md

Enclave

Secure sandbox runtime for AI agents

Documentation | Live Demo | FrontMCP Framework

---

Why Enclave?

• Extensive security testing - See security audit for details
• Defense in depth - 6 security layers for LLM-generated code
• Streaming runtime - Real-time event streaming with tool call support
• Zero-config - Works out of the box with sensible defaults
• TypeScript-first - Full type safety and excellent DX

Install

Core Packages

npm install @enclave-vm/core    # Secure JS sandbox
npm install ast-guard           # AST security validation

Streaming Runtime

npm install @enclave-vm/broker   # Tool broker & session management
npm install @enclave-vm/client   # Browser/Node client SDK
npm install @enclave-vm/react    # React hooks & components

Packages

Package	Description
@enclave-vm/core	Secure JavaScript sandbox with 6 security layers
@enclave-vm/broker	Tool registry, secrets management, session API
@enclave-vm/client	Browser & Node.js client for streaming sessions
@enclave-vm/react	React hooks: useEnclaveSession, EnclaveProvider
@enclave-vm/runtime	Deployable runtime worker (Lambda, Vercel, etc.)
@enclave-vm/types	TypeScript types & Zod schemas
@enclave-vm/stream	NDJSON streaming, encryption, reconnection
ast-guard	AST-based security validator

Quick Start

import { Enclave } from '@enclave-vm/core';

const enclave = new Enclave({
  securityLevel: 'SECURE',
  toolHandler: async (name, args) => {
    if (name === 'getUser') return { id: args.id, name: 'Alice' };
    throw new Error(`Unknown tool: ${name}`);
  },
});

const result = await enclave.run(`
  const user = await callTool('getUser', { id: 123 });
  return { greeting: 'Hello, ' + user.name };
`);

if (result.success) {
  console.log(result.value); // { greeting: 'Hello, Alice' }
}

enclave.dispose();

React Integration

import { EnclaveProvider, useEnclaveSession } from '@enclave-vm/react';

function App() {
  return (
    <EnclaveProvider brokerUrl="https://your-server.com">
      <CodeRunner />
    </EnclaveProvider>
  );
}

function CodeRunner() {
  const { execute, state, result, stdout } = useEnclaveSession();

  const runCode = () =>
    execute(`
    const data = await callTool('fetchData', { id: 123 });
    return data;
  `);

  return (
    <div>
      <button onClick={runCode} disabled={state === 'running'}>
        {state === 'running' ? 'Running...' : 'Run Code'}
      </button>
      {stdout && <pre>{stdout}</pre>}
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}

Architecture

See README-ARCHITECTURE.md for detailed architecture documentation covering:

• Deployment scenarios (embedded vs extracted runtime)
• Streaming protocol (NDJSON)
• Tool broker pattern
• Reference sidecar & auto-ref
• Security & encryption

Demos

Enclave Demo (basic sandbox)

npx nx serve enclave-demo

A CLI script that demonstrates core sandbox features: arithmetic, loops, tool calls, and security blocking of disallowed operations.

Streaming Demo (full architecture)

npx nx demo streaming-demo

Starts a 3-server architecture with a web UI, covering embedded, lambda, and direct execution modes:

• Client (port 4100) — Web UI
• Broker (port 4101) — Tool execution & session management
• Runtime (port 4102) — Sandboxed code execution

Read the full documentation →

---

License

Apache-2.0