@capsuleos/libkrun

Experimental Linux microVM provider for CapsuleOS, backed by an application-owned @capsuleos/microvm-supervisor service. It is intentionally not enabled by a default or ambient configuration path.

The v1 compatibility profile is pinned to libkrun 1.18.0 and libkrunfw 5.4.0. Construction requires the exact acceptance string shown below, and every create preflight verifies the supervisor-reported runtime, firmware, architecture, isolation mode, and host capabilities before allocation.

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

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

const capsule = createCapsule({
  providers: {
    local: libkrun({
      supervisor,
      namespace: "preview-agents",
      experimental: {
        accept: "libkrun-1.18.0+libkrunfw-5.4.0",
      },
      image: {
        template: "agent-linux",
        reference: "registry.example.invalid/agent-linux",
        version: "2026-08-02",
        manifestDigest: "sha256:...",
        architecture: "x86_64",
      },
      guestTokenProvider: (sandboxId) => issueGuestTokenFor(sandboxId),
    }),
  },
});

Security and lifecycle profile

• The supervisor must report worker-frozen retention, supervisor-isolated jailer mode, KVM, cgroup v2, the cgroup freezer, and a network namespace.
• Suspend freezes the exact worker generation. Resume thaws that same generation. The provider never allocates a replacement while resuming.
• The configured provider image is fixed. OCI images, image drift, privileged settings, host access, devices, GPUs, dynamic disks, and restricted egress are rejected before allocation.
• Capsule's guest protocol runs over a length-prefixed supervisor byte stream. No public ingress, public vsock, or snapshot capability is exposed.
• The current supervisor protocol has no create-time environment or secret channel. Non-empty spec.env and inputs.secrets are rejected instead of being ignored. Per-process environment values still travel through the authenticated guest process API, and archives remain supported by Capsule's post-create bootstrap.
• Idempotency keys, image identities, ownership, generation fences, guest endpoints, runtime digests, and firmware digests are checked on every authoritative record.

This package is experimental because libkrun does not provide Firecracker-style VM pause or snapshot primitives in this profile. Retention relies on freezing the isolated supervisor worker, so host upgrades and supervisor behavior remain part of the trust boundary.

The provider still works with AI SDK Harness without public ingress: its authenticated guest process service advertises stdin, so the Harness adapter selects the loopback process tunnel.