secure-exec/docs/api-reference.mdx at 63f62aec6a6928ef3689c69f45802445839d5ba6 · rivet-dev/secure-exec

title	API Reference
description	Complete reference for all secure-exec exports.

Package Structure

Package	Contents
`secure-exec`	Main package — `createKernel`, `createNodeRuntime`, `NodeRuntime`, system drivers, filesystem, network, and permissions
`@secure-exec/core`	Kernel, types, VFS, permission helpers, shared utilities
`@secure-exec/nodejs`	Node.js runtime driver, bridge, execution driver, system driver factory
`@secure-exec/python`	Python/Pyodide runtime driver
`@secure-exec/typescript`	Sandboxed TypeScript compiler tools

Kernel

`createKernel(options)`

_{Exported from secure-exec}

Creates a kernel that manages a virtual filesystem, process table, file descriptor table, pipes, PTYs, and permissions. Mount runtime drivers to execute code.

createKernel(options: KernelOptions): Kernel

KernelOptions

Option	Type	Description
`filesystem`	`VirtualFileSystem`	Virtual filesystem for the kernel. Required.
`permissions`	`Permissions`	Access control rules. Deny-by-default.
`env`	`Record<string, string>`	Environment variables.
`cwd`	`string`	Working directory. Default `"/root"`.
`maxProcesses`	`number`	Maximum concurrent processes.

Kernel methods

Method	Returns	Description
`mount(driver)`	`Promise<void>`	Mount a runtime driver.
`exec(command, options?)`	`Promise<KernelExecResult>`	Execute a command string through the shell.
`spawn(command, args, options?)`	`ManagedProcess`	Spawn a process directly (no shell).
`openShell(options?)`	`ShellHandle`	Open an interactive shell on a PTY.
`connectTerminal(options?)`	`Promise<number>`	Wire a shell to process.stdin/stdout.
`readFile(path)`	`Promise<Uint8Array>`	Read a file from VFS.
`writeFile(path, content)`	`Promise<void>`	Write a file to VFS.
`mkdir(path)`	`Promise<void>`	Create a directory.
`readdir(path)`	`Promise<string[]>`	List directory entries.
`stat(path)`	`Promise<VirtualStat>`	Get file metadata.
`exists(path)`	`Promise<boolean>`	Check if a path exists.
`dispose()`	`Promise<void>`	Dispose the kernel and all mounted drivers.

KernelExecResult

{ exitCode: number; stdout: string; stderr: string }

`createNodeRuntime(options?)`

_{Exported from secure-exec}

Creates a Node.js runtime driver that can be mounted into a kernel via kernel.mount().

createNodeRuntime(options?: {
  memoryLimit?: number;
  moduleAccessPaths?: string[];
  permissions?: Partial<Permissions>;
}): RuntimeDriver

Option	Type	Description
`memoryLimit`	`number`	Memory limit in MB for each V8 isolate. Default `128`.
`moduleAccessPaths`	`string[]`	Host filesystem paths for module resolution.
`permissions`	`Partial<Permissions>`	Bridge permissions for isolate processes.

Runtimes

`NodeRuntime`

_{Exported from secure-exec}

Convenience class for direct JavaScript code execution in a V8 isolate. For the kernel-first approach, use createKernel() + createNodeRuntime() instead.

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 `"/root/node_modules/typescript/lib/typescript.js"`.

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.

System Driver Factories

`createNodeDriver(options?)`

_{Exported from secure-exec}

Creates a system driver for Node.js environments. Used with NodeRuntime.

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

Filesystem

`createInMemoryFileSystem()`

_{Exported from secure-exec}

Creates a fully in-memory filesystem backed by Maps.

createInMemoryFileSystem(): InMemoryFileSystem

`NodeFileSystem`

_{Exported from secure-exec}

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()`

_{Exported from secure-exec}

Creates a network adapter with real fetch, DNS, and HTTP client support (Node.js only).

createDefaultNetworkAdapter(): 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.

Permissions

_{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` (NodeRuntime)

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` (NodeRuntime)

{ code: number; errorMessage?: string }

`RunResult<T>`

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

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

Used internally by NodeRuntime. For the kernel-first approach, use createKernel() instead.

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Package Structure

Kernel

`createKernel(options)`

`createNodeRuntime(options?)`

Runtimes

`NodeRuntime`

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

`createTypeScriptTools(options)`

System Driver Factories

`createNodeDriver(options?)`

Filesystem

`createInMemoryFileSystem()`

`NodeFileSystem`

`VirtualFileSystem` interface

Network

`createDefaultNetworkAdapter()`

`NetworkAdapter` interface

Permissions

Pre-built helpers

`Permissions` type

Execution Types

`ExecOptions` (NodeRuntime)

`ExecResult` (NodeRuntime)

`RunResult<T>`

`StdioHook`

`ProjectCompilerOptions`

`SourceCompilerOptions`

`TypeCheckResult`

`ProjectCompileResult`

`SourceCompileResult`

`TypeScriptDiagnostic`

Configuration Types

`ProcessConfig`

`OSConfig`

`SystemDriver`

`CommandExecutor` interface

FilesExpand file tree

api-reference.mdx

Latest commit

History

api-reference.mdx

File metadata and controls

Package Structure

Kernel

createKernel(options)

createNodeRuntime(options?)

Runtimes

NodeRuntime

TypeScript Tools (@secure-exec/typescript)

createTypeScriptTools(options)

System Driver Factories

createNodeDriver(options?)

Filesystem

createInMemoryFileSystem()

NodeFileSystem

VirtualFileSystem interface

Network

createDefaultNetworkAdapter()

NetworkAdapter interface

Permissions

Pre-built helpers

Permissions type

Execution Types

ExecOptions (NodeRuntime)

ExecResult (NodeRuntime)

RunResult<T>

StdioHook

ProjectCompilerOptions

SourceCompilerOptions

TypeCheckResult

ProjectCompileResult

SourceCompileResult

TypeScriptDiagnostic

Configuration Types

ProcessConfig

OSConfig

SystemDriver

CommandExecutor interface

`createKernel(options)`

`createNodeRuntime(options?)`

`NodeRuntime`

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

`createTypeScriptTools(options)`

`createNodeDriver(options?)`

`createInMemoryFileSystem()`

`NodeFileSystem`

`VirtualFileSystem` interface

`createDefaultNetworkAdapter()`

`NetworkAdapter` interface

`Permissions` type

`ExecOptions` (NodeRuntime)

`ExecResult` (NodeRuntime)

`RunResult<T>`

`StdioHook`

`ProjectCompilerOptions`

`SourceCompilerOptions`

`TypeCheckResult`

`ProjectCompileResult`

`SourceCompileResult`

`TypeScriptDiagnostic`

`ProcessConfig`

`OSConfig`

`SystemDriver`

`CommandExecutor` interface