NAME

ash - spawn agent VMs with virtle

DESCRIPTION

ash coordinates NixOS agent VMs through virtle. It reads its space config, evaluates a NixOS flake host, writes a virtle manifest, and manages spawn, attach, copy, mount, stop, and cleanup flows.

STATE

Named VMs keep ash state under XDG_STATE_HOME/ASH_NAME/NAME/ or ~/.local/state/ASH_NAME/NAME/. ASH_NAME defaults to ash. State includes the saved ash config, generated virtle manifest, SSH keys, hotmount staging data, and VM runtime data.

GLOBAL OPTIONS

The options --log-level=LEVEL, --virtle=PATH, and -v/--verbose are shared by commands that use them. --log-level is the minimum diagnostic level written to stderr (debug, info, warn, or error; default info; ASH_LOG_LEVEL env); it never affects command results.

Output is split by stream: results the command was asked to produce (ssh/command output, ash ls/inspect tables, started VM lines, mount-space confirmations) go to stdout and are always printed; ash's own diagnostics go to stderr and are gated by --log-level.

REQUIREMENTS

ash assumes host tools are available as needed: nix, virtle, virtiofsd, bindfs, ssh, scp, systemd-ssh-proxy, systemd-run, systemctl, journalctl, ssh-keygen, agent-portal-host, /bin/sh, mountpoint, and du.

Some paths can be resolved or overridden: virtle comes from --virtle, ASH_VIRTLE, or PATH; ssh and systemd-ssh-proxy default to the selected NixOS config unless overridden.

Guest-side operations assume QEMU Guest Agent plus standard NixOS tools under /run/current-system/sw/bin, including sh, mount, mountpoint, install, stat, mkdir, chown, chmod, grep, date, printf, ss, awk, and who.

EXAMPLES

ash spawn --name work -f ../my-nix#agent

ash spawn --name tmp -f ../my-nix#agent --attach

ash spawn --name work -f ../my-nix#agent --attach --keep

ash attach work

SEE ALSO

Use ash COMMAND --help for command-specific help.

Generated from ash Cmdliner manpage metadata.