@capsuleos/microvm-supervisor

This package is the unprivileged Node.js boundary to a privileged Linux microVM supervisor. It contains a transport-independent interface and a local Unix-socket client. Firecracker and libkrun provider packages depend on the interface; they do not load a VMM library or manipulate KVM, TAP devices, namespaces, cgroups, disks, or jailer state inside the application process.

The supervisor owns those host resources and must authenticate its client, fence every operation by owner and allocation generation, persist only safe resource metadata, and reconcile native state after restart. Guest process and file traffic upgrades one authenticated control connection to an opaque byte stream and then uses CapsuleOS guest protocol v1 over virtio-vsock.

The Unix protocol is versioned and length-prefixed. It is suitable only for a local, permissioned socket. Socket permissions and Linux peer-credential authorization remain supervisor responsibilities.

import { createUnixMicrovmSupervisorClient } from "@capsuleos/microvm-supervisor";

const supervisor = createUnixMicrovmSupervisorClient({
  socketPath: "/run/capsuleos/hostd.sock",
  maxControlFrameBytes: 1024 * 1024,
});

The client opens one connection per operation and owns no provider SDK or daemon lifecycle. An optional operation deadline is sent on the wire and an AbortSignal immediately closes the local connection. guest.open preserves bytes coalesced with the upgrade response and exposes a pull-controlled Web stream.

The exact wire contract is documented in api/microvm-supervisor-v1.md.