Files
2026-10-09 14:35:12 -04:00

118 lines
3.3 KiB
Markdown

# 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 <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](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