Hermes Box Lite

Quick start

Run these commands from the hermes-box-lite repository on macOS, or on x86_64/arm64 Linux with KVM available and your user allowed to access /dev/kvm. Install smolvm, GPG, curl, jq, tar, awk, and standard Bash command-line tools first.

On Linux, verify virtualization access before creating a box:

test -r /dev/kvm -a -w /dev/kvm
smolvm machine ls

1. Create and verify a box

./box new alpha
./box doctor alpha

Creation boots Ubuntu with configurable CPU, memory, and a 64 GiB default overlay, installs the toolchain and the latest Hermes release through its official installer, starts Executor, registers its authenticated HTTP MCP endpoint with Claude and Codex, and runs health checks. Hermes begins durably disabled until setup or a migration cutover is complete.

2. Enter and authenticate

./box enter alpha

You enter as agent in a persistent tmux session under ~/workspace. Authenticate the tools you intend to use:

hermes setup --portal
claude
codex

3. Open Executor and save the state

./box open alpha
./box save alpha

box open waits for the authenticated forwarded endpoint, then launches the Executor UI without printing its bearer token. box save quiesces Hermes and Executor, checkpoints and verifies SQLite, excludes transient/native caches and locks, validates and encrypts the archive, then selectively restores the prior service state.

Daily use

The full command reference (every box subcommand and what it does) lives in the README's Commands table — kept there as the single source of truth so it can't drift out of sync with this page.

Inside the box

hb status
hb versions
hb doctor
hb logs executor
hb logs hermes
hb verify-state
hb acknowledge-active-paths
hb cutover-ready

The workload supervises Executor and the Hermes gateway without duplicate processes. Doctor is read-only and treats deliberate quiescence as policy, while start and repair remain explicit mutations. Gateway enable requires the full single-writer confirmation phrase printed by hb gateway-enable.

Backup and restore

The exact guarantees each of these commands makes — what gets quiesced, validated, excluded, and verified, step by step — are documented once, in README's Backup and restore guarantees, so they can't quietly drift out of sync with this walkthrough. What follows here is the practical "what do I actually type" version.

Create a backup

./box save alpha

By default, this creates backups/alpha-<timestamp>.tar.gz.gpg and refuses to overwrite an existing destination. Set a passphrase in the environment for unattended use:

BOX_PASSPHRASE='your-local-secret' ./box save alpha

Restore into a new box

./box load backups/alpha-20260625-120000.tar.gz.gpg beta

The archive is decrypted and validated before a VM is even created. The Hermes gateway stays disabled afterward, so a restore rehearsal can never accidentally claim a live messaging identity.

Import from Eventide or another Hermes host

./box import-hermes alpha hermes-backup.zip --map /Users/davis=/data/home/agent

Validates and atomically imports native Hermes state with the gateway left disabled. Review the import manifest, run hb acknowledge-active-paths, then require hb cutover-ready before enabling the gateway — see the README link above for exactly what the import does and skips.

Inspect a backup without a VM

./box extract backups/alpha-20260625-120000.tar.gz.gpg

Extraction validates the archive and writes to a new directory under backups/. Treat extracted contents as sensitive: they can contain credentials, sessions, private work, and Executor data.

Health and repair

Start with the doctor whenever a box feels partly broken:

./box doctor alpha

Doctor performs a bounded, authenticated MCP handshake through the guest-local endpoint and, when web exposure is enabled, the forwarded host endpoint. It uses jq to validate the HTTP 200 JSON initialize result, negotiated protocol version, response content type, and session ID, sends the initialized notification, then closes the session best-effort. A bare listener, malformed result, 404, or HTTP 500 response fails health. Without an exposed port, doctor reports the host check as skipped.

If managed tools, profiles, or MCP wiring need repair, re-run provisioning:

./box repair alpha

Repair quiesces Hermes and Executor, refreshes packages and repository-owned guest assets, preserves the installed Hermes layout, resumes the prior service policy, repairs MCP wiring, and runs the doctor.

Remove a box safely

./box rm alpha

The command reports whether it can find a recent backup and requires the exact box name as confirmation. For intentional non-interactive deletion:

./box rm alpha --force

Configuration

Edit box.env before creating or repairing a box.

Provisioning installs a root-owned copy at /etc/hermes-box.env, so guest helpers use the same settings as the host workflow.

Security model

• The VM has no host filesystem mounts.
• Executor's forwarded web port is host-loopback-only.
• Hermes API forwarding is disabled by default and host-loopback-only when enabled.
• Networking is always enabled for provisioning and agent tools.
• Claude, Codex, Hermes, Executor, and plugins share one guest account and credential set.
• The agent user has passwordless sudo inside the guest.
• Encrypted backups and extracted state should be handled as secret material.

The VM is the host-protection boundary. Tools inside a box are not isolated from one another. A compromised tool, plugin, MCP source, or prompt-injected agent may access the other tools' credentials and workspace.

Troubleshooting

Executor or MCP is unhealthy

./box doctor alpha
./box repair alpha

Inside the box, inspect hb status and hb logs executor. Run hb wire-mcp to replace stale legacy stdio wiring with the authenticated HTTP configuration.

box open reports success but no browser appears

This is expected on a headless host reached over SSH or Tailscale rather than at its console — see README's Executor and MCP section for how to reach the UI from a separate client machine instead.

An operation says the box is locked

Another mutation may be running. Locks contain an owning PID and stale locks are recovered automatically after that process exits. Do not manually remove a lock while a save, load, repair, or delete is active.

A restore fails before VM creation

The passphrase may be incorrect, or the decrypted archive may be corrupt or unsafe. This failure intentionally occurs before provisioning so it does not leave an orphan VM.

box new fails while installing Hermes

Provisioning uses Hermes's current official installer. Check the installer output and upstream release status, then retry once any upstream or network failure is resolved.

Validate the repository

make check

This requires ShellCheck, Python 3, and jq, then runs Bash/Python syntax checks, static contracts, protocol-health regressions, encrypted archive round trips, native Hermes ZIP/import safety tests, validation-before-VM tests, cleanup checks, and mock failure rollback.