@machinen/runtime

The TypeScript API behind machinen. Reach for this when you want to drive microVMs from your own Node.js code instead of through the CLI.

What you can build with it

• Run a Linux workload in a VM with first-class control: stream stdout/stderr, exec commands inside, write files in, await exit.
• Snapshot a running process to disk and resume it later — possibly on a different machine. Heap, sockets, and open file descriptors come back intact.
• Clone a running VM into a sibling. Both copies run independently from the same instant, diverging from a shared heap. Useful for branching warmed-up state into N parallel runs.
• Bake reusable images. provision() runs your apt/curl/copy steps inside a real VM and archives the result as a tarball you can boot over and over.
• Multiplex many VMs from one host process with per-sandbox stdio routing.

If you want a CLI rather than a library, see @machinen/cli.

Install

npm i @machinen/runtime

You also need a native package with the VMM and host tools. The matching one for your host (@machinen/native-arm64-darwin, @machinen/native-arm64-linux, or @machinen/native-x64-linux) is pulled in automatically as an optional dependency. If you'd rather install it explicitly:

npm i @machinen/native-arm64-darwin    # or native-arm64-linux / native-x64-linux

First boot fetches the matching kernel + base rootfs from the public companion GitHub release over HTTPS; no gh auth login is needed.

A taste

import { boot } from "@machinen/runtime";

const vm = await boot({
  image: "./rootfs-debian-arm64.tar.gz", // or rootfs-debian-amd64.tar.gz on amd64 Linux
  cmd: ["/bin/sh"],
});

await vm.exec("echo hello from inside");

const { code } = await vm.wait();
process.exit(code ?? 0);

For a longer walkthrough — provision an image, boot it, snapshot, hand off — see the Quickstart and the guides for end-to-end recipes (mounts, networking, fork patterns, lifecycle).

Reference

The full API surface — every function, every option, every error class, with line-linked source pointers — is generated by typedoc and lives in API.md. It's regenerated on release; treat it as the source of truth for shapes and types.

A flyover of what's there:

• provision, boot, restore, attach — the four lifecycle functions.
• VmHandle — what boot/restore/attach return: exec, execRaw, execPty, writeFile, snapshot, fork, wait, kill, detach.
• MachinenError and the typed-error tree (BootError, ExecError, SnapshotError, …) plus isMachinenError / formatMachinenError.
• list, runGc, validatePid, RegistryEntry — registry and lifecycle helpers.
• bootPty / PtyVmHandle — boot straight into a PTY for terminal-aware workloads.
• VsockExec, VsockFiles, VsockSecrets, VsockWinsize — the vsock protocol clients underneath the higher-level API.
• Sandboxes, Supervisor — multi-VM hosts.
• LogEvent, OnLog — the streaming-log event shape.

Debugging

Set DEBUG=machinen:* to stream internal diagnostics to stderr. Uses the debug package, so it's zero-overhead when unset and supports the usual comma-separated namespace patterns.

| Namespace | Covers | | ---------------------- | --------------------------------------------------------------- | | machinen:boot | boot() lifecycle — VMM spawn, vsock bridge, registry | | machinen:provision | provision() steps — install hook, tar-to-disk, repack | | machinen:exec | vsock exec — connect retries, frames, exit codes | | machinen:snapshot | CRIU dump trigger, wait, console-log inspection | | machinen:attach | attach lookup, VM resolution | | machinen:registry | ~/.machinen/vms/ reads, writes, stale-entry pruning | | machinen:gvproxy | sidecar spawn, port-forward setup | | machinen:mkinitramfs | rootfs/bundle pack steps | | machinen:cli | @machinen/cli argv parsing and command dispatch | | machinen:vmm | tee VMM stderr to host stderr (replaces MACHINEN_BUILD_DEBUG) |

DEBUG=machinen:* npx machinen boot ./rootfs.tar.gz -- /bin/sh
DEBUG=machinen:exec,machinen:registry node script.js
DEBUG=machinen:gvproxy* pnpm smoke-tests

License

FSL-1.1-MIT — converts to MIT two years after each release.