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

87 lines
4.0 KiB
Markdown

# Hermenix
<img src="assets/logo.jpg" alt="Logo" width="300px">
[Hermes Agent](https://github.com/NousResearch/hermes-agent) in a NixOS VM that
owns its own bootloader and `/nix/store`, on two btrfs-backed disks, under an
unprivileged hardened QEMU.
**THE ULTIMATE WAY TO RUN HERMES**!
The agent can rebuild its own system and update itself, durably. It shares no
filesystem with the host, and reaches **nothing** on your network unless **you
say so**.
Hermes product behavior (CLI, providers, gateway, skills, memory) lives in
**upstream Hermes docs** — this repo documents the VM, host module, and
`hermenix` CLI around it.
## Quickstart
```bash
nix run git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermenix -- setup
```
Paste the printed module snippet into your host flake, then:
```bash
sudo nixos-rebuild switch
hermenix vm console
hermenix vm ssh # labels, determinate-nixd login, flake lock — see install doc
```
Full path: **[docs/INSTALL.md](docs/INSTALL.md)**.
## CLI
| | For |
| -------------------------------- | ---------------------------------------------- |
| `hermenix setup` | host provisioning |
| `hermenix migrate <src>` | existing `HERMES_HOME` → guest |
| `hermenix migrate connections` | connection files only |
| `hermenix remote <host> "<cmd>"` | `setup`/`migrate` over SSH |
| `hermenix vm <sub>` | VM lifecycle, snapshots, backups |
| `hermenix ctl <sub>` | host bridge into guest files / unit / `hermes` |
| `hermenix version` | package version |
**[docs/CLI.md](docs/CLI.md)**.
## Documentation
| Doc | Contents |
| ------------------------------------------------------------ | -------------------------------------------------- |
| [docs/CONCEPTS.md](docs/CONCEPTS.md) | disks, boundary, seed-once, vsock, Determinate Nix |
| [docs/INSTALL.md](docs/INSTALL.md) | guided setup, module, first boot, remote |
| [docs/MANUAL_SETUP.md](docs/MANUAL_SETUP.md) | hand-run `setup` |
| [docs/CLI.md](docs/CLI.md) | `vm` / `ctl` |
| [docs/NETWORK.md](docs/NETWORK.md) | NAT vs bridged, allowlists |
| [docs/PASSTHROUGH.md](docs/PASSTHROUGH.md) | PCI/USB, virtual devices |
| [docs/RECOVERY.md](docs/RECOVERY.md) | generations, snapshots, backups, `--clean` |
| [docs/MIGRATE.md](docs/MIGRATE.md) | carry over an existing home |
| [docs/DEVELOP.md](docs/DEVELOP.md) | devenv, tests |
| [docs/ROUGH_EDGES.md](docs/ROUGH_EDGES.md) | known issues |
| [GUIDELINES.md](GUIDELINES.md) | coding-agent rules for this repo |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | upstream product docs |
## Boundary (short)
| | Default |
| -------------------- | ------------------------ |
| Public internet | yes |
| Host Nix cache | yes (one port) |
| Host / LAN / inbound | deny, unless allowlisted |
| Host hardware | none, unless passthrough |
[docs/NETWORK.md](docs/NETWORK.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md)
## Hacking
```bash
direnv allow
runtest
runvmtest
```
Agents: builds **only** via `bin/runtest` / `bin/runvmtest` (`-debug` ok).
[GUIDELINES.md](GUIDELINES.md) · [docs/DEVELOP.md](docs/DEVELOP.md)