Skip to main content

Crate supermachine

Crate supermachine 

Source
Expand description

supermachine — run any OCI/Docker image as a hardware-isolated microVM on macOS HVF (Linux KVM and Windows WHP in progress).

§Quick start

use supermachine::{Image, Vm, VmConfig};

// Load an already-baked snapshot (use the `supermachine` CLI to
// bake one once: `supermachine run nginx:1.27-alpine --no-push`).
let image = Image::from_snapshot("snapshots/nginx/restore.snap")?;

// Spin up a microVM. Default VmConfig: 256 MiB, 1 vCPU,
// auto-discovered kernel + init shim.
let vm = Vm::start(&image, &VmConfig::new())?;

// Talk to the guest via the host-side vsock-mux unix socket.
// Bytes you write here proxy through to the first TSI listener
// inside the guest (typically the workload's `:80`).
let mut sock = vm.connect()?;
use std::io::Write;
sock.write_all(b"GET / HTTP/1.0\r\nHost: workload\r\n\r\n")?;

vm.stop()?;

§Three integration patterns

  1. Shell out to the CLI — exec supermachine run IMAGE.
  2. Long-lived router daemon — start supermachine-router, talk HTTP to it. Process-isolated from your app.
  3. Embed this library directly (this crate) — lowest latency, in-process VMM. Requires codesigning your binary; see assets::ENTITLEMENTS_PLIST and the cargo-supermachine plugin (cargo install supermachine).

Re-exports§

pub use assets::AssetPaths;
pub use exec::ExecBuilder;
pub use exec::ExecChild;
pub use exec::ExecEof;
pub use exec::ExecOutcome;
pub use exec::ExecSignaler;
pub use exec::ExecStderr;
pub use exec::ExecStdin;
pub use exec::ExecStdout;

Modules§

assets
Locate the runtime assets that supermachine needs to start a microVM: the Linux kernel image, the in-VM init shim source + prebuilt binary, and the HVF entitlements plist.
cli
Worker-binary CLI parsing helpers.
codesign
First-run codesign autopilot.
dedup
Linux/other stub — sibling-snapshot block dedup is an APFS clonefile optimization (host disk space, not VM latency). No-op where the snapshot FS has no reflink (e.g. ext4); a FICLONE-based dedup for btrfs/XFS hosts is a future enhancement. Callers stay platform-agnostic.
exec
Host-side framing for the in-guest exec agent.
internal
Unstable internals. Subject to breaking changes on every minor. The stable embedder API is at the crate root: Image, Vm, VmConfig, AssetPaths, Error.
memory_admission
Process-wide memory admission control for microVM workers.
snapshot_dedup
Cross-platform golden-base selection for snapshot dedup (macOS clonefile + Linux/KVM golden-base diff snapshots). Cross-platform golden-base selection for snapshot dedup.
spawn_concurrency
Process-wide spawn-concurrency gate (boot-rate limiter).
trace
Unified TRACE category gate (0.7.39+).
wire
Internal wire-format helpers exposed for sibling crates that need to talk to the in-guest agent directly (specifically the napi binding in npm/supermachine-core/). The action JSON shape these support is internal — outside embedders should prefer Vm::write_file / Vm::read_file / Vm::exec which call these for you.

Structs§

Image
OciImageBuilder
Every setter that affects the workload’s behavior (env, cmd, memory, guest_port) is part of the bake’s input fingerprint: changing it forces a re-bake and produces a different snapshot. Use distinct with_name values if you want side-by-side snapshots for the same image ref with different configs.
Pool
Explicit, configured worker pool. Returned by PoolBuilder::build. Pool is Clone (Arc-shared); dropping every clone tears the pool down.
PoolBuilder
Configurable bake of an OCI image. Built via Image::builder; terminate with OciImageBuilder::build to produce an Image. Builder for an explicitly configured worker pool. Started with Image::pool; terminated with PoolBuilder::build.
PoolStats
Snapshot of pool state at a point in time. Cheap to fetch — one mutex acquire — so it’s safe to graph at modest rates.
PooledVm
A Vm checked out of an Image’s hidden pool. Derefs to Vm, so every method on Vm is callable. On Drop the VM returns to the pool — the next Image::acquire gets a freshly snapshot-restored worker in ~5 ms.
TcpForwarder
Owns the accept-loop thread for a Vm::expose_tcp forwarder.
Vm
Linux/KVM backend Vm: holds the RunningVm control handle (vCPU threads + on-demand snapshot/stop) plus the shared vsock socket paths. The agnostic exec/file/forward methods operate against the same fields as the macOS Vm.
VmConfig
Configuration for Vm::start. Built via the chainable VmConfig::with_* methods or constructed directly:
VolumeSpec
A --volume HOST_FILE:GUEST_PATH entry. The host file is the canonical store; on first use init-oci formats it ext4. Once formatted, the same file persists across runs and across snapshot restores. Snapshots don’t capture the volume contents (they live on the host); they only capture the mapping.

Enums§

Error
All errors the high-level API can return. Designed to be matchable: the variants name what failed, not which internal type produced it.
PullPolicy
How Image::from_oci decides whether to talk to the registry or use a locally-cached snapshot. Same semantics as Docker’s --pull flag.
SymlinkPolicy
Per-mount symlink policy. Picks the right shape of symlink support for the trust level of what’s running in the VM.