Machine

api object

The machine handle obtained from lab.machine/vm/container: the entry point to lifecycle, snapshots, input, screen matching and the guest agent, for a VM or a container alike.

A Machine handle is returned by lab.machine(name), lab.vm(name), lab.container(name) and their plural forms. There is one handle for both kinds, and every method below is available on all of them. Its methods fall into five groups, each documented as its own reference:

• Lifecycle & state — start/stop/restart, state, readiness, IPs.
• Snapshots — take, restore, list and delete snapshots.
• Keyboard & mouse — send keys, type text, move/click/drag the mouse.
• Screen, image matching & OCR — screenshot, wait-for-image, OCR and text matching.
• Guest agent — exec commands, copy files in and out, interactive send/expect terminals, and guest stats.

What a machine cannot do is reported at call time and names the capability. screenshot on a machine with no display fails with *"machine api has no display"* — not "no such method", and not a claim that its kind could never have one. That is deliberate: the day a container reports a display, the same script works unchanged.

Fallible calls return Result[..., string]; the matched screen hits return a Match and exec returns an ExecResult.