Minimega

@nblair2/minimegav2026.05.30.1· 1d agoMODELS

01README

Full minimega control via its command socket (or minimega -e), split into eight models — vm, vmconfig, namespace, network, cc, disk, mesh and host: VM lifecycle (launch/start/stop/kill, info, tags, net, screenshots), the launch config template, namespaces and the scheduler, networking (bridges, taps, VLANs, QoS, captures, router, dnsmasq), command-and-control (miniccc), disk images, the mesh/deploy fabric, and host/system ops (host, check, version, files, vnc, logging) plus a generic command passthrough.

02Models8

@nblair2/minimega/vmv2026.05.30.1vm.ts

fn vm_info()

List all VMs (`vm info`), storing each as a `vm` resource

fn vm_launch(type: enum, names: string)

Launch (or, in namespace mode, queue) VMs of a type from the active

Argument	Type	Required	Description
type	enum	yes	VM type to launch
names	string	yes	VM name(s) or a count (e.g. 'web-1', 'web[1-10]', or '10')

fn vm_launch_flush()

Flush the namespace's queued launches (bare `vm launch`)

fn vm_start(target: string)

Start (boot/resume) the selected VM(s)

Argument	Type	Required	Description
target	string	yes	VM selector: a name, id, range (e.g. vm[0-9]), or 'all'

fn vm_stop(target: string)

Stop (pause) the selected VM(s)

Argument	Type	Required	Description
target	string	yes	VM selector: a name, id, range (e.g. vm[0-9]), or 'all'

fn vm_kill(target: string)

Kill the selected VM(s)

Argument	Type	Required	Description
target	string	yes	VM selector: a name, id, range (e.g. vm[0-9]), or 'all'

fn vm_flush()

Remove all VMs in the QUIT or ERROR state (`vm flush`)

fn vm_save(name: string, target: string)

Save the selected VM(s)' configuration under a name

Argument	Type	Required	Description
name	string	yes	Name to save the VM configuration under
target	string	yes	VM selector to save the config of

fn vm_screenshot(vm: string, max?: number)

Capture a PNG screenshot of a VM's console

Argument	Type	Required	Description
vm	string	yes	VM name or id
max?	number	no	Maximum image dimension in pixels (scales the screenshot down)

fn vm_top()

Read live per-VM resource usage (`vm top`)

fn vm_tag(vm: string, key?: string, value?: string)

Get or set a VM tag: with a value sets it; with only a key reads it;

Argument	Type	Required	Description
vm	string	yes	VM name or id
key?	string	no	Tag key; omit to read all tags
value?	string	no	Tag value to set; omit (with key) to read a single tag

fn vm_net_connect(vm: string, index: number, vlan: string)

Connect a VM interface to a VLAN at runtime

Argument	Type	Required	Description
vm	string	yes	VM name or id
index	number	yes	Interface index to connect
vlan	string	yes	VLAN id or alias to connect the interface to

fn vm_net_disconnect(vm: string, index: number)

Disconnect a VM interface from its VLAN at runtime

Argument	Type	Required	Description
vm	string	yes	VM name or id
index	number	yes	Interface index to disconnect

fn vm_cdrom(action: enum, vm: string, path?: string)

Eject or change a VM's cdrom image

Argument	Type	Required	Description
action	enum	yes	Eject or change the cdrom
vm	string	yes	VM name or id
path?	string	no	Image path (required for 'change')

fn vm_hotplug(action: enum, vm: string, file?: string, id?: string)

Add, remove, or show hotplug devices on a VM

Argument	Type	Required	Description
action	enum	yes	Hotplug operation
vm	string	yes	VM name or id
file?	string	no	Disk/USB file path (for 'add')
id?	string	no	Device id, or 'all' (for 'remove')

fn vm_qmp(vm: string, command: string)

Send a raw QMP command to a KVM VM

Argument	Type	Required	Description
vm	string	yes	VM name or id
command	string	yes	Raw QMP JSON command (e.g. {"execute":"query-status"})

Resources

vm(infinite)— A minimega VM and its current state (from `vm info`)

operation(7d)— Outcome of a one-shot VM action (launch, power, tag, net, qmp, etc.)

@nblair2/minimega/vmconfigv2026.05.30.1vmconfig.ts

fn config_show()

Read the active `vm config` launch template

fn config_set(memory?: number, cores?: number, sockets?: number, threads?: number, cpu?: string, machine?: string, snapshot?: boolean, disks?: string, kernel?: string, initrd?: string, append?: string, cdrom?: string, networks?: string, uuid?: string, vga?: string, schedule?: string, coschedule?: number, colocate?: string, filesystem?: string, hostname?: string, init?: string)

Set one or more common vm config fields (memory, cores, disks,

Argument	Type	Required	Description
memory?	number	no	Memory in MB
cores?	number	no	vCPU cores
sockets?	number	no	CPU sockets
threads?	number	no	Threads per core
cpu?	string	no	QEMU CPU model (e.g. host, qemu64)
machine?	string	no	QEMU machine type
snapshot?	boolean	no	Run disks in snapshot mode
disks?	string	no	Disk image(s), space-separated (e.g. 'a.qcow2 b.qcow2')
kernel?	string	no	Kernel image path
initrd?	string	no	Initrd image path
append?	string	no	Kernel command-line append string
cdrom?	string	no	CD-ROM image path
networks?	string	no	Network interface spec(s), space-separated (e.g. '100 200')
uuid?	string	no	UUID to assign the VM
vga?	string	no	VGA device type
schedule?	string	no	Pin the next VM to a host
coschedule?	number	no	Max VMs to co-schedule on the same host (-1 for unlimited)
colocate?	string	no	Co-locate with another VM
filesystem?	string	no	Container root filesystem path
hostname?	string	no	Container hostname
init?	string	no	Container init command

fn config_set_field(field: string, value: string)

Set an arbitrary vm config field (`vm config <field> <value>`) — the

Argument	Type	Required	Description
field	string	yes	vm config subcommand/field name (e.g. 'serial-ports', 'qemu-append')
value	string	yes	Value(s) to set (space-separated for lists)

fn config_save(name: string)

Save the active config under a name (`vm config save`)

Argument	Type	Required	Description
name	string	yes	Saved-config name

fn config_restore(name: string)

Restore a saved config into the active template

Argument	Type	Required	Description
name	string	yes	Saved-config name

fn config_clone(vm: string)

Clone a running VM's configuration into the active template

Argument	Type	Required	Description
vm	string	yes	VM to copy the configuration from

fn config_clear()

Reset the active vm config to defaults (`clear vm config`)

Resources

vmConfig(infinite)— The active vm config launch template for the namespace

operation(7d)— Outcome of a one-shot vm config change (set/save/clear/etc.)

@nblair2/minimega/namespacev2026.05.30.1namespace.ts

fn namespace_info()

Read the active namespace's settings (`ns`)

fn namespace_active()

Show the daemon's currently active namespace (`namespace`)

fn namespace_create(name: string)

Create and activate a namespace (`namespace <name>`)

Argument	Type	Required	Description
name	string	yes	Namespace name

fn namespace_delete(name: string)

Delete a namespace and its VMs (`clear namespace <name>`)

Argument	Type	Required	Description
name	string	yes	Namespace name

fn ns_hosts()

List the namespace's member hosts (`ns hosts`)

fn ns_add_hosts(hosts: string)

Add host(s) to the namespace (`ns add-hosts`)

Argument	Type	Required	Description
hosts	string	yes	Host(s) to add/remove, as a name or range (e.g. 'ccc[1-10]')

fn ns_del_hosts(hosts: string)

Remove host(s) from the namespace (`ns del-hosts`)

Argument	Type	Required	Description
hosts	string	yes	Host(s) to add/remove, as a name or range (e.g. 'ccc[1-10]')

fn ns_load(metric?: enum)

Read or set the scheduler load metric (`ns load`)

Argument	Type	Required	Description
metric?	enum	no	Scheduler load metric to set; omit to read the current value

fn ns_queueing(enabled: boolean)

Enable or disable VM launch queueing (`ns queueing`)

Argument	Type	Required	Description
enabled	boolean	yes	Whether to queue VMs instead of launching

fn ns_queue()

Show the queued (not-yet-scheduled) VMs (`ns queue`)

fn ns_schedule(dryRun?: boolean)

Schedule (or dry-run) the queued VMs across hosts

Argument	Type	Required	Description
dryRun?	boolean	no	Preview the placement without launching

fn ns_run(command: string)

Run a minimega command on every namespace host (`ns run`)

Argument	Type	Required	Description
command	string	yes	minimega command to run on every host

fn ns_bridge(bridge: string, netmask?: string)

Configure the namespace's tunnel bridge (`ns bridge`)

Argument	Type	Required	Description
bridge	string	yes	Tunnel bridge name for the namespace
netmask?	string	no	Optional bridge netmask

Resources

namespace(infinite)— A minimega namespace and its settings (from `ns`)

operation(7d)— Outcome of a one-shot namespace/scheduler action (hosts, load,

@nblair2/minimega/networkv2026.05.30.1network.ts

fn bridge_info()

List OpenVSwitch bridges (`bridge`)

fn tap_list()

List host taps (`tap`)

fn tap_create(vlan: string, bridge?: string, ip?: string, name?: string)

Create a host tap on a VLAN (`tap create`)

Argument	Type	Required	Description
vlan	string	yes	VLAN id or alias to attach the tap to
bridge?	string	no	Bridge to create the tap on
ip?	string	no	Tap IP: 'dhcp' or a CIDR address (e.g. 10.0.0.1/24)
name?	string	no	Explicit tap interface name

fn tap_delete(tap: string)

Delete a host tap (`tap delete`)

Argument	Type	Required	Description
tap	string	yes	Tap name to delete, or 'all'

fn vlans_list()

List VLAN aliases (`vlans`)

fn vlans_add(alias: string, vlan: string)

Add a VLAN alias (`vlans add`)

Argument	Type	Required	Description
alias	string	yes	Human-readable VLAN alias
vlan	string	yes	Numeric VLAN id

fn vlans_clear(alias?: string)

Remove a VLAN alias, or all of them (`clear vlans`)

Argument	Type	Required	Description
alias?	string	no	Alias to clear; omit to clear all

fn qos_add(tap: string, property: enum, value: string)

Apply a QoS constraint to a tap (`qos add`)

Argument	Type	Required	Description
tap	string	yes	Tap interface to shape
property	enum	yes	QoS property
value	string	yes	Value: loss '%', delay duration (e.g. 50ms), or rate (e.g. 10mbit)

fn qos_clear(tap: string)

Remove QoS constraints from a tap (`clear qos`)

Argument	Type	Required	Description
tap	string	yes	Tap interface to clear QoS on

fn capture_list()

List active captures (`capture`)

fn capture_pcap(mode: enum, name: string, filename: string, interface?: number)

Start a pcap capture on a VM interface or a bridge

Argument	Type	Required	Description
mode	enum	yes	Capture a VM interface or a bridge
name	string	yes	VM name or bridge name
filename	string	yes	Output pcap file path
interface?	number	no	Interface index (required for mode=vm)

fn capture_netflow(bridge: string, filename: string, mode: enum)

Start a netflow capture on a bridge

Argument	Type	Required	Description
bridge	string	yes	Bridge to capture netflow on
filename	string	yes	Output file path
mode	enum	yes	Record format

fn capture_clear()

Stop and clear all captures (`clear capture`)

fn router_show(vm: string)

Show a router VM's configuration (`router <vm>`)

Argument	Type	Required	Description
vm	string	yes	Router VM name

fn router_config(vm: string, statement: string)

Apply a configuration statement to a router VM

Argument	Type	Required	Description
vm	string	yes	Router VM name
statement	string	yes	Router statement (e.g. 'interface 0 10.0.0.1/24', 'dhcp 10.0.0.0 ...')

fn router_commit(vm: string)

Commit a router VM's pending configuration

Argument	Type	Required	Description
vm	string	yes	Router VM name

fn dnsmasq_list()

List running dnsmasq servers (`dnsmasq`)

fn dnsmasq_start(listen?: string, low?: string, high?: string)

Start a dnsmasq DHCP/DNS server (`dnsmasq start`)

Argument	Type	Required	Description
listen?	string	no	IP to listen on
low?	string	no	DHCP range low address
high?	string	no	DHCP range high address

fn dnsmasq_configure(id: string, option: string)

Add a configuration directive to a dnsmasq server

Argument	Type	Required	Description
id	string	yes	dnsmasq server id
option	string	yes	Configuration directive (e.g. 'dhcp-option ...', 'dns <ip> <host>')

Resources

bridge(infinite)— An OpenVSwitch bridge (from `bridge`)

tap(infinite)— A host tap interface (from `tap`)

vlan(infinite)— A VLAN alias (from `vlans`)

capture(infinite)— An active packet capture (from `capture`)

operation(7d)— Outcome of a one-shot networking action (tap/vlan/qos/capture/

@nblair2/minimega/ccv2026.05.30.1cc.ts

fn cc_clients()

List connected cc clients (`cc clients`)

fn cc_commands()

List queued cc commands (`cc commands`)

fn cc_exec(command: string)

Run a command on matching clients (`cc exec`)

Argument	Type	Required	Description
command	string	yes	Command to run on matching clients

fn cc_background(command: string)

Run a command in the background on matching clients

Argument	Type	Required	Description
command	string	yes	Command to run on matching clients

fn cc_send(file: string)

Queue a file to send to matching clients (`cc send`)

Argument	Type	Required	Description
file	string	yes	File path (relative to the cc file root)

fn cc_recv(file: string)

Queue a file to receive from matching clients (`cc recv`)

Argument	Type	Required	Description
file	string	yes	File path (relative to the cc file root)

fn cc_filter(filter?: string)

Read or set the cc client filter (`cc filter`)

Argument	Type	Required	Description
filter?	string	no	Client filter to set (e.g. 'os=linux', 'tag=role:web'); omit to read

fn cc_responses(id: string)

Read command responses (`cc responses <id|all>`)

Argument	Type	Required	Description
id	string	yes	Command id to read responses for, or 'all'

fn cc_prefix(prefix?: string)

Read or set the cc command prefix (`cc prefix`)

Argument	Type	Required	Description
prefix?	string	no	Command prefix to set; omit to read

fn cc_process(action: enum, target: string)

List or kill processes on clients (`cc process`)

Argument	Type	Required	Description
action	enum	yes	List or kill processes
target	string	yes	VM/'all' (for list) or PID (for kill)

fn cc_tunnel(uuid: string, src: number, host: string, dst: number)

Open a forward tunnel through a client (`cc tunnel`)

Argument	Type	Required	Description
uuid	string	yes	Target client UUID
src	number	yes	Source port
host	string	yes	Destination host
dst	number	yes	Destination port

fn cc_rtunnel(uuid: string, src: number, host: string, dst: number)

Open a reverse tunnel through a client (`cc rtunnel`)

Argument	Type	Required	Description
uuid	string	yes	Target client UUID
src	number	yes	Source port
host	string	yes	Destination host
dst	number	yes	Destination port

fn cc_mount(uuid?: string, path?: string)

Mount a client's filesystem, or list mounts (`cc mount`)

Argument	Type	Required	Description
uuid?	string	no	Client UUID to mount; omit to list
path?	string	no	Local mount path

fn cc_clear()

Reset cc state: filters, commands, responses (`clear cc`)

Resources

ccClient(infinite)— A connected cc (miniccc) client (from `cc clients`)

ccCommand(infinite)— A queued cc command (from `cc commands`)

operation(7d)— Outcome of a one-shot cc action (exec, send/recv, filter, responses,

@nblair2/minimega/diskv2026.05.30.1disk.ts

fn disk_info(image: string)

Inspect a disk image (`disk info`), storing it as a resource

Argument	Type	Required	Description
image	string	yes	Disk image path

fn disk_create(format: enum, image: string, size: string)

Create a blank qcow2/raw disk image (`disk create`)

Argument	Type	Required	Description
format	enum	yes	Image format
image	string	yes	Path for the new image
size	string	yes	Image size (e.g. 10G, 512M)

fn disk_snapshot(src: string, dst: string)

Create a copy-on-write overlay of a backing image

Argument	Type	Required	Description
src	string	yes	Backing image to snapshot from
dst	string	yes	Path for the new copy-on-write overlay

fn disk_commit(image: string)

Commit an overlay's changes into its backing image

Argument	Type	Required	Description
image	string	yes	Disk image path

fn disk_resize(image: string, size: string)

Resize a disk image (`disk resize`)

Argument	Type	Required	Description
image	string	yes	Disk image to resize
size	string	yes	New size (e.g. 20G)

Resources

disk(infinite)— A disk image and its metadata (from `disk info`)

operation(7d)— Outcome of a one-shot disk action (create, snapshot, commit, resize)

@nblair2/minimega/meshv2026.05.30.1mesh.ts

fn mesh_list()

List mesh nodes and their connections (`mesh list`)

fn mesh_status()

Show mesh status: size, degree, peers (`mesh status`)

fn mesh_dial(node: string)

Dial (connect to) a mesh node (`mesh dial`)

Argument	Type	Required	Description
node	string	yes	Mesh node name

fn mesh_hangup(node: string)

Hang up (disconnect) a mesh node (`mesh hangup`)

Argument	Type	Required	Description
node	string	yes	Mesh node name

fn mesh_send(node: string, command: string)

Run a minimega command on remote mesh node(s) (`mesh send`)

Argument	Type	Required	Description
node	string	yes	Target node (name, range, or 'all')
command	string	yes	minimega command to run on the node(s)

fn mesh_degree(degree?: number)

Read or set the mesh connection degree (`mesh degree`)

Argument	Type	Required	Description
degree?	number	no	Desired connection degree to set; omit to read

fn mesh_timeout(timeout?: number)

Read or set the mesh message timeout (`mesh timeout`)

Argument	Type	Required	Description
timeout?	number	no	Message timeout in seconds to set; omit to read

fn mesh_dot(file: string)

Export the mesh topology as a graphviz .dot file (`mesh dot`)

Argument	Type	Required	Description
file	string	yes	Output path for the graphviz .dot file

fn deploy_launch(args?: string)

Deploy and launch minimega on mesh nodes (`deploy launch`)

Argument	Type	Required	Description
args?	string	no	Arguments to `deploy launch` (e.g. host list and flags); omit for none

Resources

meshNode(infinite)— A node in the meshage cluster fabric (from `mesh list`)

operation(7d)— Outcome of a one-shot mesh action (status, dial/hangup, send, degree,

@nblair2/minimega/hostv2026.05.30.1host.ts

fn host_info()

Report per-host resources (`host`)

fn check()

Validate minimega's external dependencies (`check`)

fn version()

Read the minimega version (`version`)

fn nuke()

Reset minimega: kill all VMs and clear state (`nuke`)

fn optimize()

Show current VM optimizations (`optimize`)

fn optimize_clear()

Disable all VM optimizations (`clear optimize`)

fn file_list(path?: string)

List files in the mesh-wide file store (`file list`)

Argument	Type	Required	Description
path?	string	no	Subdirectory to list; omit for the root

fn file_get(file: string)

Fetch a file from another mesh node (`file get`)

Argument	Type	Required	Description
file	string	yes	File path within the mesh file store

fn file_delete(file: string)

Delete a file from the file store (`file delete`)

Argument	Type	Required	Description
file	string	yes	File path within the mesh file store

fn vnc_list()

List active VNC recordings/playbacks (`vnc`)

fn vnc_record(vm: string, file: string)

Record a VM's VNC session to a file (`vnc record`)

Argument	Type	Required	Description
vm	string	yes	VM name to record/playback
file	string	yes	Recording file path

fn vnc_playback(vm: string, file: string)

Play a recorded VNC session back into a VM (`vnc playback`)

Argument	Type	Required	Description
vm	string	yes	VM name to record/playback
file	string	yes	Recording file path

fn vnc_clear()

Stop all VNC recordings/playbacks (`clear vnc`)

fn log_level(level?: enum)

Read or set the minimega log level (`log level`)

Argument	Type	Required	Description
level?	enum	no	Log level to set; omit to read the current level

fn log_filter(filter: string)

Add a log filter to suppress matching lines (`log filter`)

Argument	Type	Required	Description
filter	string	yes	Substring filter to suppress from logs

fn read(file: string)

Run a minimega script file (`read <file>`)

Argument	Type	Required	Description
file	string	yes	Path to a minimega script file to run

fn command_run(command: string)

Run an arbitrary minimega command and store its responses — the

Argument	Type	Required	Description
command	string	yes	Raw minimega command to run (the escape hatch for unmodeled commands)

Resources

host(infinite)— A minimega host and its resource usage (from `host`)

operation(7d)— Outcome of a one-shot host/system action (check, version, nuke,

03Stats

100 / 100

Downloads

Archive size

71.6 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/nblair2/swamp-minimega

04Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

05Labels

#minimega #sandia #vm #kvm #container #namespace #network-emulation #cyber-range #miniccc #orchestration #infrastructure