doc clean
This commit is contained in:
1 parent
c2a7f94821
commit
30427e3975
34 files changed
+1119
-1758
No files matched your search
+117
@@ -0,0 +1,117 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user