118 lines
3.3 KiB
Markdown
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
|