# Install ## Guided (recommended) The `hermenix` CLI is a flake package — no checkout needed: ```bash nix run git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermenix -- setup ``` Or install once: ```bash 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](MANUAL_SETUP.md). ## Add the module ```nix # 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 ]; }; }; } ``` ```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; }; ``` ```bash sudo nixos-rebuild switch hermenix vm console # watch it boot ``` ## First boot (hermenix side) ```bash 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](https://github.com/NousResearch/hermes-agent). From the host you can drive the guest install/gateway unit once it exists: ```bash 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: ```bash 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](CONCEPTS.md#quote-multi-word-subcommands). Runs `nix run #hermenix -- …` on the remote (no checkout). Remote needs SSH access to Gitea. Override URL with `--flake`. Uses `ssh -t` for prompts. ## Next - [CLI.md](CLI.md) — day-to-day `vm` / `ctl` - [NETWORK.md](NETWORK.md) — allowlists / bridged - [MIGRATE.md](MIGRATE.md) — existing `HERMES_HOME` - [RECOVERY.md](RECOVERY.md) — snapshots / unbootable guest