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

# Worker Pool

> OS-level memory isolation using worker threads for enhanced security

For OS-level memory isolation, use the worker threads adapter. This provides stronger isolation than the default VM context by running code in separate Node.js worker threads.

## Basic Usage

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

const enclave = new Enclave({
  adapter: 'worker_threads',
  workerPoolConfig: {
    minWorkers: 2,
    maxWorkers: 8,
    memoryLimitPerWorker: 256 * 1024 * 1024, // 256MB
  },
});
```

## Worker Pool Features

* **Pool management** - Auto-scaling with min/max workers
* **Memory monitoring** - Workers recycled when exceeding limits
* **Hard halt** - Force terminate via `worker.terminate()`
* **Rate limiting** - Message flood protection
* **Dual-layer sandbox** - Worker thread + VM context isolation

## Worker Pool Presets

| Setting                | STRICT | SECURE | STANDARD | PERMISSIVE |
| ---------------------- | ------ | ------ | -------- | ---------- |
| maxWorkers             | 4      | 8      | 16       | 32         |
| memoryLimitPerWorker   | 64MB   | 128MB  | 256MB    | 512MB      |
| maxExecutionsPerWorker | 100    | 500    | 1,000    | 5,000      |
| maxQueueSize           | 20     | 50     | 100      | 500        |
| maxMessagesPerSecond   | 100    | 500    | 1,000    | 5,000      |

## Using Presets

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

// Use STRICT preset for maximum isolation
const enclave = new Enclave({
  adapter: 'worker_threads',
  workerPoolConfig: WorkerPoolPresets.STRICT,
});

// Or customize from a preset
const customEnclave = new Enclave({
  adapter: 'worker_threads',
  workerPoolConfig: {
    ...WorkerPoolPresets.SECURE,
    maxWorkers: 16, // Override specific setting
  },
});
```

## Configuration Options

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface WorkerPoolConfig {
  // Pool sizing
  minWorkers: number;        // Minimum workers to keep warm
  maxWorkers: number;        // Maximum concurrent workers

  // Resource limits
  memoryLimitPerWorker: number;  // Memory limit per worker (bytes)
  maxExecutionsPerWorker: number; // Executions before worker recycle

  // Queue management
  maxQueueSize: number;      // Maximum pending executions
  queueTimeout: number;      // Queue wait timeout (ms)

  // Rate limiting
  maxMessagesPerSecond: number;  // Message flood protection

  // Lifecycle
  idleTimeout: number;       // Time before idle worker shutdown
  gracefulShutdownTimeout: number; // Shutdown wait time
}
```

## Memory Isolation Benefits

Worker threads provide stronger isolation than VM contexts alone:

1. **Separate V8 heap** - Each worker has its own memory space
2. **Hard memory limits** - OS-level enforcement via `--max-old-space-size`
3. **Process-like isolation** - Worker crash doesn't affect main process
4. **Clean termination** - `worker.terminate()` guarantees cleanup

## When to Use Worker Pool

Use the worker pool adapter when:

* Running code from completely untrusted sources
* Memory isolation is critical
* You need hard termination guarantees
* Processing many concurrent executions

Use the default VM adapter when:

* Memory isolation is less critical
* You need lower latency
* Running trusted or semi-trusted code
* Simpler deployment is preferred

## Dual-Layer Sandbox

The worker pool provides two layers of isolation:

```mermaid theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8a045', 'primaryTextColor': '#fff', 'primaryBorderColor': '#c78935', 'lineColor': '#c78935', 'secondaryColor': '#f0b865', 'tertiaryColor': '#fff5e6'}}}%%
flowchart TB
    subgraph main["Main Process"]
        subgraph worker["Worker Thread"]
            subgraph vm["VM Context (User Code Runs)"]
                code["Sandboxed Code"]
            end
        end
    end
    style main fill:#fff5e6,stroke:#c78935,color:#333
    style worker fill:#f0b865,stroke:#c78935,color:#333
    style vm fill:#e8a045,stroke:#c78935,color:#fff
    style code fill:#c78935,stroke:#c78935,color:#fff
```

1. **Worker Thread** - OS-level process isolation
2. **VM Context** - JavaScript-level sandboxing

## Monitoring Worker Health

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  adapter: 'worker_threads',
  workerPoolConfig: {
    maxWorkers: 8,
    memoryLimitPerWorker: 256 * 1024 * 1024,

    // Callback when worker is recycled
    onWorkerRecycled: (reason) => {
      console.log('Worker recycled:', reason);
    },

    // Callback for pool stats
    onStatsUpdate: (stats) => {
      console.log('Active workers:', stats.activeWorkers);
      console.log('Queue depth:', stats.queueDepth);
    },
  },
});
```

## Related

* [Security Levels](/enclave/core-libraries/enclave-vm/security-levels) - Security presets
* [Double VM](/enclave/core-libraries/enclave-vm/double-vm) - Additional security layer
* [Configuration](/enclave/core-libraries/enclave-vm/configuration) - All configuration options