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, installs the toolchain, starts Executor, registers its authenticated HTTP MCP endpoint with Claude and Codex, and runs health checks. On failure, the command attempts verified cleanup only for a VM proven to have been created by that invocation.

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. It uses open on macOS and xdg-open or gio on Linux. Set BOX_BROWSER to another graphical opener when needed; it receives the secret authenticated URL as its sole argument, so do not use a wrapper that logs arguments. box save pauses Executor, validates the archive, encrypts it, verifies it, and writes it under backups/.

Daily use

Inside the box

hb status
hb versions
hb doctor
hb logs executor

Executor normally runs continuously. Use hb down for a deliberate pause and hb up to resume it. The workload respects the pause instead of immediately restarting the daemon.

Backup and restore

Create a backup

./box save alpha

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

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

The mode-0600 runtime manifest is atomically published at ~/.config/hermes-box/runtime-manifest. Host and guest plaintext temporaries are removed on failure or signals, and guest plaintext is removed before Executor resumes. Do not actively edit workspace files during the save. Executor is quiesced, but arbitrary editor and agent processes are not frozen.

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 created. The destination is provisioned, restored with fail-fast extraction while Executor is paused, refreshed with current managed assets, rewired, and health-checked. A failed or HUP/INT/TERM-interrupted operation attempts cleanup only for a VM proven to have been created by that invocation. Registry metadata is removed only after VM absence is verified; cleanup failures preserve metadata and print recovery guidance. A same-named unmanaged or ambiguous smolvm machine is preserved.

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 pauses Executor, refreshes packages and repository-owned guest assets, resumes the daemon, repairs MCP wiring, and runs the doctor. It can contact upstream installers and may install newer releases.

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.
• 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.

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.

Validate the repository

make check

This requires ShellCheck, Python 3, and jq, then runs Bash syntax checks, static contracts, protocol-health regressions, encrypted archive round-trip tests, validation-before-VM tests, temporary-file cleanup checks, and mock failure rollback.