quickjs

@execbox/quickjs

QuickJS executor backend for @execbox/core, supporting inline, worker-hosted, and process-hosted execution.

Docs: https://execbox.aallam.com

Choose QuickJS When

• you want the easiest execbox backend to install
• you do not want a native addon in CI or local development
• you want fresh runtimes, captured console.* output, and JSON-only tool boundaries
• you want to move from inline execution to worker or child-process hosts without changing packages

Security Notes

• Each execution gets a fresh QuickJS runtime with no ambient Node globals injected by execbox.
• Tool calls cross a JSON-only bridge, and executor timeouts propagate abort signals to in-flight provider work.
• In the default deployment model, provider definitions are controlled by the host application, while hostile users control guest code and tool inputs.
• This package is designed for host-controlled deployments and does not by itself create a hard isolation boundary for hostile code.
• If you need a stronger boundary, use host: "process", move execution behind @execbox/remote, or place the runtime behind a container or VM.

Architecture Docs

• Execbox architecture overview
• Execbox executors
• Execbox MCP adapters and protocol

Examples

• Basic provider execution
• Process-hosted QuickJS execution
• Worker-backed QuickJS execution
• MCP provider wrapping
• MCP server wrapper
• Full examples index

Install

npm install @execbox/core @execbox/quickjs

Advanced consumers can also import the reusable QuickJS runner from @execbox/quickjs/runner. Hosted worker/process execution and @execbox/remote also reuse the shared QuickJS protocol endpoint from @execbox/quickjs/runner/protocol-endpoint.

Usage

import { resolveProvider } from "@execbox/core";
import { QuickJsExecutor } from "@execbox/quickjs";

const provider = resolveProvider({
  tools: {
    echo: {
      execute: async (input) => input,
    },
  },
});

const executor = new QuickJsExecutor();
const result = await executor.execute("await codemode.echo({ ok: true })", [
  provider,
]);

Each execution runs in a fresh QuickJS runtime with timeout handling, captured logs, and JSON-only result and tool boundaries.

QuickJsExecutor defaults to inline execution. Set host: "worker" when you want pooled worker-shell reuse, or host: "process" when you want pooled child-process reuse with a stronger lifecycle split.

const executor = new QuickJsExecutor({
  host: "worker",
  pool: {
    maxSize: 4,
    prewarm: true,
  },
});

await executor.prewarm();