Minimega

minimega operations and integration

minimega manages KVM virtual machines, Android emulators, and Linux containers on one host or across a mesh-connected cluster. This skill focuses on using minimega and preserving its operational contracts.

File paths in this skill are relative to the minimega repository root. The skill lives at skills/minimega/ inside that repository and may be installed through a symlink, so do not resolve repository paths relative to this file. Read AGENTS.md at the repository root before changing code, configuration, startup flags, deployment defaults, the Docker wrapper, service units, or tests.

Supporting files in this skill directory:

• references/configuration.md: full detail on native flags and environment variables, the Docker wrapper, the systemd unit, precedence, and help output.
• examples/minimal-kvm.mm: a complete, runnable command file.

Execution modes

Full operation requires Linux, root or equivalent device/network permissions, KVM, libpcap, and the external tools needed by the selected feature.

minimega                         # interactive instance
minimega -nostdin &              # daemonized instance
minimega -attach                 # attach to existing instance
minimega -e vm info              # execute one command
minimega -base /path -e vm info  # target a non-default base

-attach and -e connect to <base>/minimega, under /tmp/minimega by default. For scripts and agents, prefer one-shot -e commands over an interactive prompt.

The repository container provides an mm wrapper that runs minimega -e:

docker exec minimega mm vm info

Omit -it for non-interactive automation. The normal container deployment is privileged and mounts host devices; follow docker/README.md.

Configuration and CLI help

Keep every launcher aligned with the flags registered in cmd/minimega/main.go and pkg/minilog/minilog.go. The compiled minimega -h output is authoritative for flag names and defaults. references/configuration.md covers each mode in depth; the essentials are:

• Sources. The native binary reads compiled defaults, MM_* environment variables (mapped in cmd/minimega/environment.go), and command-line flags, in that order of increasing precedence. It does not load YAML, JSON, TOML, or dotenv files. -e, -attach, and -pipe also read MM_BASE from /etc/minimega/minimega.conf when neither MM_BASE nor -base is set.
• Flag syntax. Go flag syntax; parsing stops at the first non-flag argument or --, and the last repeated flag wins. Put -base and -namespace before the command following -e.
• -force and -recover. With -recover=true, recovery runs after mesh initialization even if -force=true. The compiled -h text for -recover says "only if -force is not set"; the implementation disagrees, so treat that help string as stale.
• No startup command file. Server startup ignores positional arguments. Apply runtime configuration afterwards with minimega -e read <file>; the check form validates syntax without executing. read stops at invalid syntax, continues past a command that returns an error, and rejects nested read. See examples/minimal-kvm.mm.
• Docker. docker/start-minimega.sh generates flags from MM_* container environment variables, then /etc/default/minimega, then script defaults. MM_APPEND adds raw flags. Docker defaults differ from native defaults (MM_DEGREE=1, MM_LOGLEVEL=info, MM_FORCE=true, a log file).
• systemd. misc/daemon/minimega.service maps /etc/minimega/minimega.conf to explicit ExecStart flags; MM_APPEND is not supported there.
• Help. minimega -h for startup flags, minimega -e help [command] for runtime commands, minimega -cli for the runtime CLI as JSON. Pass the correct -base=<path> before -e when the daemon uses a non-default base.

Core concepts

Base directory, file path, and context

• -base controls runtime state and the local command socket.
• -filepath controls files served by iomeshage; relative VM image paths resolve beneath it. Use absolute paths when the file is elsewhere. When -base changes and -filepath keeps its default, the file path becomes <base>/files.
• -context separates mesh discovery groups. -degree 0 disables automatic peer discovery; a positive degree maintains that many mesh connections.
• -broadcast and UDP port 9000 control default mesh discovery.

Do not confuse a mesh context with a minimega namespace. Contexts isolate clusters at process startup; namespaces isolate and schedule experiment state inside a running cluster.

Namespaces

The active namespace scopes VMs, taps, captures, VLAN aliases, and other state. The default namespace is minimega.

namespace                         # list namespaces
namespace experiment-a            # create/select namespace
namespace experiment-a vm info    # run one command in a namespace
ns hosts                          # list active namespace hosts
clear namespace                   # return to default namespace
clear namespace experiment-a      # destroy namespace and its resources

A new clustered namespace normally contains mesh nodes except the local head node. With no mesh peers, it contains the local node. ns add-hosts only accepts hosts already present in the mesh.

VM configuration and lifecycle

minimega supports kvm, container, and android VM types. vm config is mutable namespace-local state copied into every subsequently launched VM; it does not retroactively change existing VMs.

vm config                         # inspect current defaults
vm config disk image.qcow2
vm config net LAN
vm launch kvm node1               # create VM in BUILDING state
vm start node1                    # start created VM
.columns name,state vm info
vm stop node1
vm kill node1
clear vm config                   # reset current VM configuration

KVM can boot from a disk, CD-ROM, or kernel/initrd pair. Bare-metal firmware and RTOS guests use KVM with vm config baremetal true. They require a kernel image and reject the miniccc backchannel, bidirectional copy and paste, virtio serial ports, disks, CD-ROMs, migrated VM state, and TPM devices, so clear those from vm config before launching. A bare-metal VM with any vm config net entry must also set vm config baremetal-network-driver <model>, because the board-integrated NIC is not exposed through QEMU device discovery; without the driver, launch fails. QMP lifecycle control, serial sockets, and tap networking remain available.

Containers require a filesystem containing their init executable. Android VMs require an AVD name, KVM, and discoverable emulator and adb tools; android-sdk and android-avd-dir are optional overrides. Disk snapshot mode defaults to true, so writes normally do not modify the source image.

When ns queueing true is active, vm launch <type> <name> queues VMs. Run vm launch with no additional arguments to flush the queue and invoke the scheduler.