createFirecrackerSandboxProvider

Purpose and behavior

Create a remote provider that boots a Firecracker microVM from your kernel, root filesystem and TAP device, and reaches the guest over SSH. It needs Linux with /dev/kvm and a guest with Node.js 24+, git, setsid and tar. One provider runs one VM at a time; release stops it and deletes its private rootfs copy.

Complete example and detailed rules.

Parameters and properties

• optionsRequired
  FirecrackerOptions
  Host boot assets, TAP network, guest SSH access, resources and optional jailer. Invalid paths or values fail with code configuration at creation.
• options.binaryRequired
  string
  Absolute host path of the firecracker executable.
• options.kernelRequired
  string
  Absolute host path of the guest kernel image.
• options.rootfsRequired
  string
  Absolute host path of the guest root filesystem image; each VM boots from a private copy.
• options.tapRequired
  string
  Existing host TAP device for the guest network, at most 15 letters, digits, dots, hyphens or underscores. A provider owns it, so it runs one VM at a time.
• options.guestMacRequired
  string
  MAC address of the guest network interface, as six hexadecimal pairs.
• options.bootArgsRequired
  string
  Kernel boot arguments supplied to Firecracker.
• options.sshRequired
  { readonly host: string; readonly user: string; readonly identity: string; readonly knownHosts: string; readonly port?: number; readonly binary?: string; }
  How Outpost reaches the guest: host, user, identity file, trusted known_hosts file, optional port (default 22) and ssh binary.
• options.rootOptional
  string | undefined
  Repository directory in the guest, default /workspace.
• options.homeRequired
  string
  Agent home in the guest; it must match the guest user’s HOME or the boot check never succeeds.
• options.cpusOptional
  number | undefined
  Guest vCPUs, default 2. It does not cap host CPU; jailer.cpuQuotaUs does.
• options.memoryMbOptional
  number | undefined
  Guest memory in MiB, default 2048; jailer.memoryMaxMb must exceed it.
• options.bootDeadlineMsOptional
  number | undefined
  Time allowed for the guest to answer over SSH with its prerequisites, default 60000. Past it acquisition fails with code timeout and the VM stops.
• options.variablesOptional
  Readonly<Record<string, string>> | undefined
  Environment variables set for every command in the sandbox, as literal values. A key the agent also declares fails with code configuration.
• options.jailerOptional
  { readonly binary: string; readonly directory: string; readonly cgroup: string; readonly uid: number; readonly gid: number; readonly cpuQuotaUs: number; readonly memoryMaxMb: number; readonly processes: number; } | undefined
  Launch through the Firecracker jailer: root-owned binary and paths, a dedicated cgroup v2 parent with cpu, memory and pids controllers enabled, non-root uid and gid, cpuQuotaUs per 100000 microseconds (at least 1000), memoryMaxMb above guest memory and processes (at least 16). Outpost must already run as root and never calls sudo; without jailer, Firecracker runs as the calling user.

Returns

SandboxProvider

Signature

export declare function createFirecrackerSandboxProvider(
  options: FirecrackerOptions,
): SandboxProvider;

Related contracts

• FirecrackerOptions
• SandboxProvider