3.3 KiB
Install
Guided (recommended)
The hermenix CLI is a flake package — no checkout needed:
nix run git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermenix -- setup
Or install once:
nix profile install git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermenix
hermenix setup
setup walks host-side steps: prerequisites, disks, cache signing key,
/etc/hermenix/local.nix from your SSH keys, bootstrap image build, write to
the system disk. It prints the module snippet to paste into your configuration
(uplink filled in).
Safe to re-run — steps skip what's done; nothing destructive without
confirmation. It never runs nixos-rebuild (that's your config).
Hand-run equivalent: MANUAL_SETUP.md.
Add the module
# flake.nix
{
inputs.hermenix.url = "git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git";
outputs = { nixpkgs, hermenix, ... }: {
nixosConfigurations.myserver = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ hermenix.nixosModules.default ./configuration.nix ];
};
};
}
# configuration.nix
services.hermenix = {
enable = true;
disk.baseDir = "/var/lib/hermes-vm";
network.externalInterface = "eno1"; # your uplink
# network.bridged = true; # see docs/NETWORK.md
vcpu = 4;
mem = 8192;
};
sudo nixos-rebuild switch
hermenix vm console # watch it boot
First boot (hermenix side)
hermenix vm ssh
# Labels must match guest/hardware.nix BEFORE any guest rebuild
lsblk -f
# FlakeHub Cache (device-code flow — approve URL from any browser)
determinate-nixd login
sudo nix flake lock /etc/nixos
The Hermes CLI installs unattended on first boot (hermes-install.service;
a few minutes for native modules). After that, configure Hermes itself with
its own CLI — provider, keys, gateway, etc. That is upstream Hermes, not
hermenix; see the Hermes Agent docs.
From the host you can drive the guest install/gateway unit once it exists:
hermenix ctl units
hermenix ctl status
Check labels before the first guest
nixos-rebuild.guest/hardware.nixassumes rootnixosand ESPESP. Wrong labels → unbootable system after the agent's first self-rebuild.
Guest NixOS changes are durable via
sudo nixos-rebuild switch --flake /etc/nixos#hermes inside the VM. Hermes
self-updates are upstream (hermes update); use hermenix ctl only as a
vsock passthrough if you prefer running them from the host.
Remote host
setup / migrate act on the machine they run on. hermenix remote SSHs:
hermenix remote fwdesk.lab.internal setup
hermenix remote fwdesk.lab.internal "setup --clean"
hermenix remote fwdesk.lab.internal "migrate /var/lib/hermes"
Quote subcommand + flags as one string when more than a bare name — CONCEPTS.md.
Runs nix run <flake>#hermenix -- … on the remote (no checkout). Remote needs
SSH access to Gitea. Override URL with --flake. Uses ssh -t for prompts.
Next
- CLI.md — day-to-day
vm/ctl - NETWORK.md — allowlists / bridged
- MIGRATE.md — existing
HERMES_HOME - RECOVERY.md — snapshots / unbootable guest