API Reference - Secure Exec

Package Structure

secure-exec is split into focused packages. The umbrella secure-exec package re-exports everything for convenience.

Package	Contents
`@secure-exec/core`	Shared types, utilities, bridge guest code, `NodeRuntime`, `PythonRuntime` classes
`@secure-exec/node`	Node.js V8 isolate runtime driver, `createNodeDriver`, `createNodeRuntimeDriverFactory`
`@secure-exec/browser`	Browser Web Worker runtime driver, `createBrowserDriver`, `createBrowserRuntimeDriverFactory`
`@secure-exec/python`	Pyodide runtime driver, `createPyodideRuntimeDriverFactory`
`@secure-exec/typescript`	Sandboxed TypeScript compiler tools
`secure-exec`	Umbrella barrel — re-exports all of the above

Runtimes

`NodeRuntime`

_{Package: @secure-exec/core (also re-exported from secure-exec)} Sandboxed JavaScript runtime using a V8 isolate.

new NodeRuntime(options: NodeRuntimeOptions)

NodeRuntimeOptions

Option	Type	Description
`systemDriver`	`SystemDriver`	Host capabilities (filesystem, network, permissions). Required.
`runtimeDriverFactory`	`NodeRuntimeDriverFactory`	Creates the isolate execution environment. Required.
`memoryLimit`	`number`	Isolate memory cap in MB.
`cpuTimeLimitMs`	`number`	CPU time budget in ms.
`timingMitigation`	`"off" \| "freeze"`	Timing side-channel mitigation. Default `"freeze"`.
`onStdio`	`StdioHook`	Default console output hook.
`payloadLimits`	`{ base64TransferBytes?: number; jsonPayloadBytes?: number }`	Bridge payload size limits.

Methods

Method	Returns	Description
`exec(code, options?)`	`Promise<ExecResult>`	Execute code without a return value.
`run<T>(code, filePath?)`	`Promise<RunResult<T>>`	Execute code and return the module namespace/default export object.
`network`	`{ fetch, dnsLookup, httpRequest }`	Network access from the host side.
`dispose()`	`void`	Release resources synchronously.
`terminate()`	`Promise<void>`	Terminate the runtime.

TypeScript Tools (`@secure-exec/typescript`)

`createTypeScriptTools(options)`

Creates sandboxed TypeScript project/source helpers backed by a dedicated compiler runtime.

createTypeScriptTools(options: TypeScriptToolsOptions)

TypeScriptToolsOptions

Option	Type	Description
`systemDriver`	`SystemDriver`	Compiler runtime capabilities and filesystem view.
`runtimeDriverFactory`	`NodeRuntimeDriverFactory`	Creates the compiler sandbox runtime.
`memoryLimit`	`number`	Compiler sandbox isolate memory cap in MB. Default `512`.
`cpuTimeLimitMs`	`number`	Compiler sandbox CPU time budget in ms.
`compilerSpecifier`	`string`	Module specifier used to load the TypeScript compiler. Default `"typescript"`.

Methods

Method	Returns	Description
`typecheckProject(options?)`	`Promise<TypeCheckResult>`	Type-check a filesystem-backed TypeScript project using `tsconfig` discovery or `configFilePath`.
`compileProject(options?)`	`Promise<ProjectCompileResult>`	Compile a filesystem-backed project and write emitted files through the configured filesystem like `tsc`.
`typecheckSource(options)`	`Promise<TypeCheckResult>`	Type-check one TypeScript source string without mutating the filesystem.
`compileSource(options)`	`Promise<SourceCompileResult>`	Compile one TypeScript source string and return JavaScript text.

`PythonRuntime`

_{Package: @secure-exec/core (also re-exported from secure-exec)} Sandboxed Python runtime using Pyodide in a Worker thread.

new PythonRuntime(options: PythonRuntimeOptions)

PythonRuntimeOptions

Option	Type	Description
`systemDriver`	`SystemDriver`	Host capabilities. Required.
`runtimeDriverFactory`	`PythonRuntimeDriverFactory`	Creates the Pyodide worker. Required.
`cpuTimeLimitMs`	`number`	CPU time budget in ms.
`onStdio`	`StdioHook`	Default console output hook.

Methods

Method	Returns	Description
`exec(code, options?)`	`Promise<ExecResult>`	Execute Python code without a return value.
`run<T>(code, options?)`	`Promise<PythonRunResult<T>>`	Execute Python code and return a value.
`dispose()`	`void`	Release resources synchronously.
`terminate()`	`Promise<void>`	Terminate the runtime.

System Driver Factories

`createNodeDriver(options?)`

_{Package: @secure-exec/node (also re-exported from secure-exec)} Creates a system driver for Node.js environments.

createNodeDriver(options?: NodeDriverOptions): SystemDriver

NodeDriverOptions

Option	Type	Description
`filesystem`	`VirtualFileSystem`	Custom filesystem. Default: host fs with module overlay.
`moduleAccess`	`ModuleAccessOptions`	Node modules overlay config.
`networkAdapter`	`NetworkAdapter`	Network implementation.
`commandExecutor`	`CommandExecutor`	Child process executor.
`permissions`	`Permissions`	Access control rules. Deny-by-default.
`useDefaultNetwork`	`boolean`	Enable default Node.js network adapter.
`processConfig`	`ProcessConfig`	Process metadata (cwd, env, argv, etc.).
`osConfig`	`OSConfig`	OS metadata (platform, arch, homedir, etc.).

`createBrowserDriver(options?)`

_{Package: @secure-exec/browser (also re-exported from secure-exec)} Creates a system driver for browser environments. Returns a promise because OPFS initialization is async.

createBrowserDriver(options?: BrowserDriverOptions): Promise<SystemDriver>

BrowserDriverOptions

Option	Type	Description
`filesystem`	`"opfs" \| "memory"`	Filesystem backend. Default: `"opfs"`.
`permissions`	`Permissions`	Access control rules. Deny-by-default.
`useDefaultNetwork`	`boolean`	Enable browser fetch network adapter.

Runtime Driver Factories

`createNodeRuntimeDriverFactory(options?)`

_{Package: @secure-exec/node (also re-exported from secure-exec)} Creates a factory for Node.js V8 isolate runtime drivers.

createNodeRuntimeDriverFactory(options?: {
  createIsolate?(memoryLimit: number): unknown;
}): NodeRuntimeDriverFactory

`createBrowserRuntimeDriverFactory(options?)`

_{Package: @secure-exec/browser (also re-exported from secure-exec)} Creates a factory for browser Worker-based runtime drivers.

createBrowserRuntimeDriverFactory(options?: {
  workerUrl?: URL | string;
}): NodeRuntimeDriverFactory

`createPyodideRuntimeDriverFactory()`

_{Package: @secure-exec/python (also re-exported from secure-exec)} Creates a factory for Pyodide-based Python runtime drivers.

createPyodideRuntimeDriverFactory(): PythonRuntimeDriverFactory

Filesystem

`createInMemoryFileSystem()`

_{Package: @secure-exec/core (also re-exported from secure-exec)} Creates a fully in-memory filesystem backed by Maps.

createInMemoryFileSystem(): InMemoryFileSystem

`createOpfsFileSystem()`

_{Package: @secure-exec/browser (also re-exported from secure-exec)} Creates an OPFS-backed filesystem (browser only).

createOpfsFileSystem(): Promise<VirtualFileSystem>

`NodeFileSystem`

Thin wrapper around Node.js fs/promises.

new NodeFileSystem()

`VirtualFileSystem` interface

Method	Returns	Description
`readFile(path)`	`Promise<Uint8Array>`	Read file as bytes.
`readTextFile(path)`	`Promise<string>`	Read file as text.
`readDir(path)`	`Promise<string[]>`	List directory entries.
`readDirWithTypes(path)`	`Promise<DirEntry[]>`	List entries with type info.
`writeFile(path, content)`	`Promise<void>`	Write file.
`createDir(path)`	`Promise<void>`	Create directory.
`mkdir(path)`	`Promise<void>`	Create directory (alias).
`exists(path)`	`Promise<boolean>`	Check if path exists.
`stat(path)`	`Promise<StatInfo>`	Get file metadata.
`removeFile(path)`	`Promise<void>`	Delete a file.
`removeDir(path)`	`Promise<void>`	Delete a directory.
`rename(old, new)`	`Promise<void>`	Rename a file or directory.

Network

`createDefaultNetworkAdapter()`

_{Package: @secure-exec/node (also re-exported from secure-exec)} Creates a network adapter with real fetch, DNS, and HTTP support (Node.js only).

createDefaultNetworkAdapter(): NetworkAdapter

`createBrowserNetworkAdapter()`

_{Package: @secure-exec/browser (also re-exported from secure-exec)} Creates a fetch-only network adapter for browser environments. No DNS support.

createBrowserNetworkAdapter(): NetworkAdapter

`NetworkAdapter` interface

Method	Returns	Description
`fetch(url, options?)`	`Promise<FetchResponse>`	HTTP fetch.
`dnsLookup(hostname)`	`Promise<DnsResult>`	DNS resolution.
`httpRequest(url, options?)`	`Promise<HttpResponse>`	Low-level HTTP request.
`httpServerListen?(options)`	`Promise<{ address }>`	Start a loopback HTTP server.
`httpServerClose?(serverId)`	`Promise<void>`	Close a loopback HTTP server.

Permissions

_{Package: @secure-exec/core (also re-exported from secure-exec)}

Pre-built helpers

Export	Description
`allowAll`	Allow all operations.
`allowAllFs`	Allow all filesystem operations.
`allowAllNetwork`	Allow all network operations.
`allowAllChildProcess`	Allow all child process spawning.
`allowAllEnv`	Allow all environment variable access.

`Permissions` type

type Permissions = {
  fs?: PermissionCheck<FsAccessRequest>;
  network?: PermissionCheck<NetworkAccessRequest>;
  childProcess?: PermissionCheck<ChildProcessAccessRequest>;
  env?: PermissionCheck<EnvAccessRequest>;
};

Each field accepts a PermissionCheck, which is either a boolean or a function (request) => boolean | Promise<boolean>.

Execution Types

`ExecOptions`

Option	Type	Description
`filePath`	`string`	Script filename for error messages.
`env`	`Record<string, string>`	Override environment variables.
`cwd`	`string`	Working directory.
`stdin`	`string`	Stdin data.
`cpuTimeLimitMs`	`number`	CPU budget override.
`timingMitigation`	`"off" \| "freeze"`	Timing mitigation override.
`onStdio`	`StdioHook`	Per-execution stdio hook.

`ExecResult`

{ code: number; errorMessage?: string }

`RunResult<T>`

{ code: number; errorMessage?: string; exports?: T }

`PythonRunResult<T>`

{ code: number; errorMessage?: string; value?: T; globals?: Record<string, unknown> }

`PythonRunOptions`

Extends ExecOptions with:

Option	Type	Description
`globals`	`string[]`	Python globals to return.

`StdioHook`

type StdioHook = (event: { channel: "stdout" | "stderr"; message: string }) => void;

`ProjectCompilerOptions`

{
  cwd?: string;
  configFilePath?: string;
}

`SourceCompilerOptions`

{
  sourceText: string;
  filePath?: string;
  cwd?: string;
  configFilePath?: string;
  compilerOptions?: Record<string, unknown>;
}

`TypeCheckResult`

{
  success: boolean;
  diagnostics: TypeScriptDiagnostic[];
}

`ProjectCompileResult`

{
  success: boolean;
  diagnostics: TypeScriptDiagnostic[];
  emitSkipped: boolean;
  emittedFiles: string[];
}

`SourceCompileResult`

{
  success: boolean;
  diagnostics: TypeScriptDiagnostic[];
  outputText?: string;
  sourceMapText?: string;
}

`TypeScriptDiagnostic`

{
  code: number;
  category: "error" | "warning" | "suggestion" | "message";
  message: string;
  filePath?: string;
  line?: number;
  column?: number;
}

Configuration Types

`ProcessConfig`

Field	Type	Default
`platform`	`string`
`arch`	`string`
`version`	`string`
`cwd`	`string`	`"/root"`
`env`	`Record<string, string>`
`argv`	`string[]`
`execPath`	`string`
`pid`	`number`
`ppid`	`number`
`uid`	`number`
`gid`	`number`
`stdin`	`string`
`timingMitigation`	`"off" \| "freeze"`
`frozenTimeMs`	`number`

`OSConfig`

Field	Type	Default
`platform`	`string`
`arch`	`string`
`type`	`string`
`release`	`string`
`version`	`string`
`homedir`	`string`	`"/root"`
`tmpdir`	`string`	`"/tmp"`
`hostname`	`string`

`SystemDriver`

type SystemDriver = {
  filesystem?: VirtualFileSystem;
  network?: NetworkAdapter;
  commandExecutor?: CommandExecutor;
  permissions?: Permissions;
  runtime: DriverRuntimeConfig;
};

`CommandExecutor` interface

Method	Returns	Description
`spawn(command, args, options?)`	`SpawnedProcess`	Spawn a child process.

Getting Started

Runtimes

System Drivers

Features

Kernel

Reference

​Package Structure

​Runtimes

​NodeRuntime

​TypeScript Tools (@secure-exec/typescript)

​createTypeScriptTools(options)

​PythonRuntime

​System Driver Factories

​createNodeDriver(options?)

​createBrowserDriver(options?)

​Runtime Driver Factories

​createNodeRuntimeDriverFactory(options?)

​createBrowserRuntimeDriverFactory(options?)

​createPyodideRuntimeDriverFactory()

​Filesystem

​createInMemoryFileSystem()

​createOpfsFileSystem()

​NodeFileSystem

​VirtualFileSystem interface

​Network

​createDefaultNetworkAdapter()

​createBrowserNetworkAdapter()

​NetworkAdapter interface

​Permissions

​Pre-built helpers

​Permissions type

​Execution Types

​ExecOptions

​ExecResult

​RunResult<T>

​PythonRunResult<T>

​PythonRunOptions

​StdioHook

​ProjectCompilerOptions

​SourceCompilerOptions

​TypeCheckResult

​ProjectCompileResult

​SourceCompileResult

​TypeScriptDiagnostic

​Configuration Types

​ProcessConfig

​OSConfig

​SystemDriver

​CommandExecutor interface

Package Structure

Runtimes

`NodeRuntime`

TypeScript Tools (`@secure-exec/typescript`)

`createTypeScriptTools(options)`

`PythonRuntime`

System Driver Factories

`createNodeDriver(options?)`

`createBrowserDriver(options?)`

Runtime Driver Factories

`createNodeRuntimeDriverFactory(options?)`

`createBrowserRuntimeDriverFactory(options?)`

`createPyodideRuntimeDriverFactory()`

Filesystem

`createInMemoryFileSystem()`

`createOpfsFileSystem()`

`NodeFileSystem`

`VirtualFileSystem` interface

Network

`createDefaultNetworkAdapter()`

`createBrowserNetworkAdapter()`

`NetworkAdapter` interface

Permissions

Pre-built helpers

`Permissions` type

Execution Types

`ExecOptions`

`ExecResult`

`RunResult<T>`

`PythonRunResult<T>`

`PythonRunOptions`

`StdioHook`

`ProjectCompilerOptions`

`SourceCompilerOptions`

`TypeCheckResult`

`ProjectCompileResult`

`SourceCompileResult`

`TypeScriptDiagnostic`

Configuration Types

`ProcessConfig`

`OSConfig`

`SystemDriver`

`CommandExecutor` interface