Reference

The `provium` global is the entry point to every Provium API. It is itself a Lab, so every method documented on Lab is reachable directly off provium.

The `json` global — encode and decode JSON between Lua values and strings, backed by serde_json.

A VM userdata represents one guest. You get one from lab:vm("name", "profile") and use it to drive lifecycle, run commands, do file I/O, perform syscalls, attach disks and NICs, snapshot, and stream from the guest.

A Bridge userdata wraps a Linux bridge with TAP attachments. Use it to wire VMs together, partition the network, inject latency or drops, capture packets, isolate VMs, or NAT outbound traffic.

A Lab owns a set of VMs, bridges, and sub-labs, plus per-file resource claims and barriers. The `provium` global is the root Lab; sub-labs are scoped subsets you create with provium:lab().

A Disk userdata represents one virtio-blk disk attached to a VM. Use it to read and write sectors directly, inject I/O faults (EIO read, EIO write, slow I/O), or detach the disk from the live guest.

A Nic userdata is a per-(bridge, vm) handle. Use it to read NIC counters, capture per-NIC pcap, or simulate link-down / link-up on a single attachment.

A File userdata wraps an open file descriptor inside the guest. Use it to read, write, seek, tell, fd-to-int, tail, and close. Mirrors POSIX semantics.

A Process userdata is a handle to an async-spawned guest process. Use it to wait, kill, signal, write stdin, stream stdout/stderr, and query exit status.

A Worker userdata gives a test concurrent agent connections to the same guest VM, so you can drive multiple ops in parallel without spinning up another VM.

Provium has three stream userdata types — Tail, Capture, and ConsoleStream — that share next/read_until/expect/drain/close/eof. They're returned by tail_file, fd_stream, file:tail_stream, bridge:capture, nic:capture, console:read, and proc stdout/stderr_stream.

A Console userdata is the host's view of the guest's serial console. Use it to read the boot log, stream the chardev, expect a substring, write input, or close cleanly.

A Clock userdata reads and manipulates the guest's wall clock. Use it to set, advance, sleep, or query in seconds or nanoseconds — the guest sees a controllable time axis.

Snapshot and LabSnapshot userdata wrap the on-disk artefacts that `vm:snapshot()` and `lab:snapshot()` produce. Use them to introspect, restore, or delete cached snapshots.

The test() function registers tests, the t context object provides assertions and skip / fail / log, todo() declaratively skips a whole file, and wait_until() polls a predicate to truthy.

The optional second arg to test() is a metadata table. Provium inspects a handful of well-known keys (slow, skip, tags, timeout, spec) for filtering, gating, and event emission; arbitrary keys are passed through to consumers like provium-coverage.

Every flag, subcommand, environment variable, and exit code for the `provium` binary.

Provium emits a stream of structured msgpack events covering file lifecycle, test outcomes, VM spawns, pool state, claims, and fixture builds. This page documents every event variant and field.

PROTOCOL_VERSION pins the wire shape of the host-agent protocol and the observability event stream. This page explains what it pins, when it bumps, and how the conformance pin tests catch silent breakage.