Files
hermenix/docs/INSTALL.md
T
2026-10-09 14:35:12 -04:00

3.3 KiB

Install

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.nix assumes root nixos and ESP ESP. 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