Kernel API Reference

import { createKernel } from "@secure-exec/kernel";

const kernel = createKernel({
  filesystem: vfs,
  permissions: allowAll,
  env: { HOME: "/root", PATH: "/bin:/usr/bin" },
  cwd: "/root",
});

await kernel.mount(createWasmVmRuntime({ wasmBinaryPath: "..." }));
await kernel.mount(createNodeRuntime());

// WasmVM registers "node" as a stub
await kernel.mount(createWasmVmRuntime({ wasmBinaryPath: "..." }));
// Node driver overrides the "node" command
await kernel.mount(createNodeRuntime());

// "node" now routes to the Node driver
const result = await kernel.exec('node -e "console.log(42)"');

const result = await kernel.exec("echo hello && ls /tmp", {
  timeout: 10000,
  env: { DEBUG: "true" },
});

console.log(result.exitCode); // 0
console.log(result.stdout);   // "hello\n..."
console.log(result.stderr);   // ""

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

const proc = kernel.spawn("node", ["-e", "console.log('hi')"], {
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
  env: { NODE_ENV: "production" },
});

console.log(proc.pid); // e.g. 42
const exitCode = await proc.wait();

const shell = kernel.openShell({
  command: "sh",
  cols: 80,
  rows: 24,
  env: { TERM: "xterm-256color" },
});

shell.onData = (data) => process.stdout.write(data);
shell.write("echo hello\n");
shell.resize(120, 40); // SIGWINCH to foreground pgid

const exitCode = await shell.wait();

// One-liner interactive shell
const exitCode = await kernel.connectTerminal();
process.exit(exitCode);

// With options
const exitCode = await kernel.connectTerminal({
  command: "node",
  args: ["--interactive"],
  onData: (data) => myTerminal.write(data), // custom output handler
});

await kernel.dispose();
// All subsequent calls throw "disposed"

await kernel.writeFile("/tmp/data.txt", "hello");
const data = await kernel.readFile("/tmp/data.txt");     // Uint8Array
await kernel.mkdir("/tmp/subdir");
const entries = await kernel.readdir("/tmp");             // ["data.txt", "subdir"]
const stat = await kernel.stat("/tmp/data.txt");          // { size, mode, ... }
const exists = await kernel.exists("/tmp/data.txt");      // true

// Map of command name → driver name
kernel.commands; // Map { "sh" => "wasmvm", "node" => "node", ... }

// Map of PID → process info
kernel.processes; // Map { 1 => { pid: 1, status: "running", ... }, ... }

const proc = kernel.spawn("cat", []);

proc.writeStdin(new TextEncoder().encode("hello\n"));
proc.closeStdin();
proc.kill(15); // SIGTERM

const exitCode = await proc.wait();

const shell = kernel.openShell();

shell.onData = (data) => terminal.write(data);
shell.write("ls -la\n");
shell.resize(120, 40);
shell.kill(15);

const exitCode = await shell.wait();

interface RuntimeDriver {
  name: string;
  commands: string[];
  init(kernel: KernelInterface): Promise<void>;
  spawn(command: string, args: string[], ctx: ProcessContext): DriverProcess;
  dispose(): Promise<void>;
}

// Open a file, returns FD number
const fd = ki.fdOpen(pid, "/tmp/file.txt", O_RDONLY, 0o644);

// Read up to 1024 bytes
const data: Uint8Array = await ki.fdRead(pid, fd, 1024);

// Write bytes, returns bytes written
const written: number = ki.fdWrite(pid, fd, new TextEncoder().encode("hello"));

// Seek (returns new cursor position as bigint)
const pos: bigint = await ki.fdSeek(pid, fd, 0n, SEEK_SET);

// Close
ki.fdClose(pid, fd);

// Duplicate
const fd2 = ki.fdDup(pid, fd);
ki.fdDup2(pid, oldFd, newFd);

// Stat an open FD
const stat = ki.fdStat(pid, fd);
// { filetype, flags, rights }

// Read 5 bytes at offset 0 — cursor stays where it was
const data: Uint8Array = await ki.fdPread(pid, fd, 5, 0n);

// Write at offset 10 — cursor stays where it was
const written: number = await ki.fdPwrite(pid, fd, new TextEncoder().encode("world"), 10n);

// Pipe FDs reject positional I/O with ESPIPE
await ki.fdPread(pid, pipeFd, 10, 0n); // throws ESPIPE

// Spawn a child process (cross-runtime dispatch)
const child: ManagedProcess = ki.spawn(command, args, {
  ppid: parentPid,
  env: { ... },
  cwd: "/app",
  onStdout: (data) => { ... },
  onStderr: (data) => { ... },
});

// Wait for child
const { pid, status } = await ki.waitpid(childPid);

// Send signal
ki.kill(childPid, 15); // SIGTERM

// Kill all processes in a process group (negative PID)
ki.kill(-pgid, 15); // SIGTERM to all in group

// Create a pipe
const { readFd, writeFd } = ki.pipe(parentPid);

// Get/set process group ID
const pgid = ki.getpgid(pid);
ki.setpgid(pid, newPgid);

// Create new session (pid becomes session leader)
const sid = ki.setsid(pid); // returns new sid === pid

// Get session ID
const sid = ki.getsid(pid);

// Kill all processes in a group
ki.kill(-pgid, 2); // SIGINT to all in group

// Allocate a PTY master/slave pair
const { masterFd, slaveFd, path } = ki.openpty(pid);
// path: "/dev/pts/0"

// Check if FD is a terminal
ki.isatty(pid, slaveFd);  // true (slave FDs are terminals)
ki.isatty(pid, masterFd); // false (master FDs are not)
ki.isatty(pid, pipeFd);   // false

// Set line discipline (low-level)
ki.ptySetDiscipline(pid, slaveFd, {
  canonical: true,  // buffer until newline
  echo: true,       // echo input back
  isig: true,       // ^C → SIGINT, ^Z → SIGTSTP
});

// Set foreground process group for signal delivery
ki.ptySetForegroundPgid(pid, slaveFd, pgid);

// Get current terminal attributes (returns deep copy)
const termios: Termios = ki.tcgetattr(pid, slaveFd);
// { icanon: true, echo: true, isig: true, cc: { vintr: 0x03, ... } }

// Switch to raw mode
ki.tcsetattr(pid, slaveFd, { icanon: false, echo: false, isig: false });

// Set foreground process group
ki.tcsetpgrp(pid, slaveFd, pgid);

// Get foreground process group
const fgPgid: number = ki.tcgetpgrp(pid, slaveFd);

// Open /dev/fd/N — equivalent to dup(N)
const fd2 = ki.fdOpen(pid, "/dev/fd/5", O_RDONLY);
// fd2 is a new FD sharing the same file description as FD 5

// List open FDs for a process
const fds: string[] = ki.devFdReadDir(pid);
// ["0", "1", "2", "5", "6"]

// Stat the underlying file for /dev/fd/N
const stat = await ki.devFdStat(pid, 5);
// Returns VirtualStat of the file behind FD 5

ki.vfs.readFile(path);
ki.vfs.writeFile(path, content);
ki.vfs.readDir(path);
ki.vfs.stat(path);
ki.vfs.mkdir(path);
ki.vfs.exists(path);
ki.vfs.removeFile(path);
ki.vfs.rename(oldPath, newPath);
ki.vfs.symlink(target, linkPath);
ki.vfs.readlink(path);
// ... full POSIX VFS surface

interface ProcessContext {
  pid: number;
  ppid: number;
  env: Record<string, string>;
  cwd: string;
  fds: { stdin: number; stdout: number; stderr: number };
  onStdout?: (data: Uint8Array) => void;
  onStderr?: (data: Uint8Array) => void;
}

interface DriverProcess {
  writeStdin(data: Uint8Array): void;
  closeStdin(): void;
  kill(signal: number): void;
  wait(): Promise<number>;
  onExit: ((code: number) => void) | null;
  onStdout: ((data: Uint8Array) => void) | null;
  onStderr: ((data: Uint8Array) => void) | null;
}

import { defaultTermios } from "@secure-exec/kernel";
import type { Termios, TermiosCC } from "@secure-exec/kernel";

const termios = defaultTermios();
// {
//   icanon: true,   // canonical mode (line buffering)
//   echo: true,     // echo input back
//   isig: true,     // signal generation from control chars
//   cc: { vintr: 0x03, vquit: 0x1c, vsusp: 0x1a, veof: 0x04, verase: 0x7f }
// }

import { KernelError } from "@secure-exec/kernel";
import type { KernelErrorCode } from "@secure-exec/kernel";

try {
  ki.fdRead(pid, 999, 1024);
} catch (err) {
  if (err instanceof KernelError) {
    console.log(err.code);    // "EBADF"
    console.log(err.message); // "EBADF: bad file descriptor"
  }
}

import { SIGTERM, SIGKILL, SIGINT, SIGQUIT, SIGTSTP, SIGWINCH } from "@secure-exec/kernel";

import { allowAll, allowAllFs, allowAllNetwork, allowAllChildProcess, allowAllEnv } from "@secure-exec/kernel";

const kernel = createKernel({
  filesystem: vfs,
  permissions: allowAll,        // everything allowed
});

const kernel = createKernel({
  filesystem: vfs,
  permissions: {
    fs: allowAllFs,              // filesystem only
    network: false,              // block network
    childProcess: allowAllChildProcess,
    env: (req) => ["HOME", "PATH"].includes(req.name),
  },
});