Skip to content
docs.microagent.sh

Glossary

Last updated: 2026-06-27

A handful of terms come up often enough that it’s worth pinning them down before you read the rest of the docs. The lifecycle words in particular are easy to confuse - and the distinctions matter for what you can do next.

Project

Section titled “Project”
  • microagent - the project: Go library, CLI, and host supervisors.
  • microagent - the CLI binary. A thin shell over the Go library.
  • library - the Go packages (pkg/workspace, pkg/rootfs, and friends) that do the actual work. Importable from your own program when you’d rather not shell out.

VMs and what’s inside them

Section titled “VMs and what’s inside them”
  • backend - the host-specific path microagent uses to run a microVM. Linux and macOS are supported host targets; WSL is a Linux compatibility lane, and Windows Hyper-V is experimental. See Platform support.
  • microVM - the small, fast VM each workspace runs in. Booted by the backend.
  • guest - the Linux userspace inside the microVM. What your OCI image becomes once it’s booted.
  • rootfs - the ext4 disk image the guest boots from. Built from an OCI image.
  • kernel - the Linux kernel image the microVM boots. Backend-specific; the default is downloaded on first use.
  • workspace - a named, persistent microVM. Disk, identity, and event history all stick around between starts. The thing you create, halt, and restart. See Keep a persistent workspace.
  • agent - the program you run inside a workspace. microagent doesn’t define it or impose a framework; in these docs it means a small LLM loop with tools (see run your first agent).
  • snapshot - a point-in-time checkpoint of a running workspace’s memory and disk. Restore it in place, or fork independent copies from it. See Snapshot and fork workspaces.

Storage and networking

Section titled “Storage and networking”
  • disk - an ext4 image attached to a workspace at a mountpoint, in addition to the rootfs. microagent never exposes host directories; everything the guest reads or writes is a block device. See Storage.
  • bundle - a tar archive (.tar/.tar.gz/.tgz) built into a one-shot ext4 disk at start. The portable way to get a directory’s contents into a workspace. See Use volumes and move data.
  • named volume - a platform-managed ext4 disk addressed by name, with a lifecycle independent of any one workspace. Single-attach (one running workspace at a time); the in-boundary analog of a container volume. Attach with -v name:/mount. See Use volumes and move data.
  • network mode - a workspace has one of two modes: user (the default) gives the guest unprivileged outbound IPv4 plus any published TCP ports; isolated gives it no network device at all. See Networking.

Control

Section titled “Control”
  • supervisor - the host-side helper microagent uses to start, stop, and inspect microVMs on the current platform. Most users never call it directly.
  • mediation channel - a guest-to-host vsock path for the agent’s calls into your host control plane. Declared, required by default, and fail-closed unless you explicitly opt out. Not the same as egress mediation (below); they only share the word “mediation”. See Build agents on the mediation channel.
  • egress mediation - the capture-and-control layer over the guest’s ordinary network egress (the TCP/UDP/DNS it sends out of its network device). On by default (guarded), with strict and off modes. Intercepts TLS with a per-workspace CA, allowlists destinations, and audits every decision. Distinct from the vsock mediation channel above. See Egress mediation.
  • state directory - where workspace records live on the host (default ~/.microagent/).
  • AX mode - the agent-experience output mode (--mode=ax). stdout is structured JSON for agent clients; UX mode is the human-readable default. The MCP endpoint always uses AX output.
  • readiness - structured signals on a status response (guestReady, shellReady, execReady, resultReady, mediationReady) so callers can sequence work without polling files or serial logs. See State and identity.

Lifecycle vocabulary

Section titled “Lifecycle vocabulary”

These six words are not synonyms.

  • halt - clean disk-preserving shutdown. The VM exits, the disk stays. start boots the same disk back up.
  • pause - memory-state suspend, not a shutdown. Freezes a running workspace’s vCPUs while preserving memory and disk; resume thaws it back to running exactly where it left off. exec, connect, and stats are rejected while paused. Unlike halt, nothing is discarded and nothing reboots.
  • stop - graceful shutdown signal. If the VM hasn’t exited after five seconds, stop marks the workspace failed and returns an error; it never escalates on its own - following up with kill is your move.
  • kill - hard termination. For when stop doesn’t return.
  • quarantine - sever host-side network and mediation while preserving disk and event history. The VM may still be running. A forensic state, not a normal stopped state - you must halt, stop, or kill it before you can start it again.
  • delete - remove the workspace and its state. Refuses while a VM process is still running; halt or stop first.