Lifo
Try Demo

Sandbox API reference

Every option and method on Sandbox — create, run commands, the fs helper, snapshots, and direct kernel/shell access.

Sandbox is the high-level entry point. Sandbox.create() builds a fully wired box; the returned object exposes commands, fs, env, cwd, and direct kernel / shell handles.

Sandbox.create(options?)

const sandbox = await Sandbox.create(options);

SandboxOptions:

OptionTypeDefaultNotes
persistbooleanfalsePersist the disk to IndexedDB (browser).
envRecord<string, string>—Extra env, merged with defaults.
cwdstring/home/userInitial working directory.
filesRecord<string, string | Uint8Array>—Pre-populate the disk.
terminalITerminal | HTMLElement | string—Attach a terminal (element/selector lazily creates xterm.js).
mountsArray<{ virtualPath; hostPath; readOnly?; fsModule? }>—Mount host directories (Node).

sandbox.commands

sandbox.commands.run(cmd: string, options?: RunOptions): Promise<CommandResult>;
sandbox.commands.register(name: string, handler: Command): void;

RunOptions: cwd, env, signal (AbortSignal), timeout (ms), onStdout(chunk), onStderr(chunk), stdin (string).

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

const { stdout, exitCode } = await sandbox.commands.run("ls -la", { cwd: "/tmp" });

sandbox.commands.register("greet", async (ctx) => {
  ctx.stdout.write("hi\n");
  return 0;
});

See Commands for the Command / CommandContext contract.

sandbox.fs

A promise-based, node:fs-shaped helper over the VFS:

sandbox.fs.readFile(path): Promise<string>;
sandbox.fs.readFile(path, null): Promise<Uint8Array>;    // binary
sandbox.fs.writeFile(path, content): Promise<void>;
sandbox.fs.readdir(path): Promise<Array<{ name; type }>>;
sandbox.fs.stat(path): Promise<{ type; size; mtime }>;
sandbox.fs.mkdir(path, { recursive? }): Promise<void>;
sandbox.fs.rm(path, { recursive? }): Promise<void>;
sandbox.fs.exists(path): Promise<boolean>;
sandbox.fs.rename(oldPath, newPath): Promise<void>;
sandbox.fs.cp(src, dest): Promise<void>;
sandbox.fs.writeFiles(files): Promise<void>;             // batch

Snapshots

sandbox.fs.exportSnapshot(): Promise<Uint8Array>;   // tar.gz of the whole disk
sandbox.fs.importSnapshot(data: Uint8Array): Promise<void>;

sandbox.env, sandbox.cwd

env is the box's environment object; cwd is the current working directory (reflecting cd within the shell session).

Escape hatches: kernel and shell

For anything the high-level API doesn't cover, sandbox.kernel and sandbox.shell are exposed directly:

sandbox.kernel.vfs;               // synchronous VFS
sandbox.kernel.processRegistry;   // the process table
sandbox.kernel.networkStack;      // interfaces, ports, DNS
sandbox.kernel.serviceManager;    // systemctl-backed services

See The kernel, Processes, and Networking for what those expose.

Tip

Prefer commands.run() and fs for most work — they're stable and environment-agnostic. Reach into kernel / shell only for lower-level control.