Hermes Box Lite

A practical guide to creating, using, backing up, restoring, and repairing isolated agent boxes.

The operating model

Tools are replaceable; state is precious. Claude Code, Codex, Hermes, Executor, and Neovim live in an isolated smolvm VM. User state lives under /data and travels through encrypted backups.

Quick start

Run these commands from the hermes-box-lite repository on a Mac with smolvm, GPG, and standard command-line tools installed.

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. A failed creation is removed automatically.

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 launches the authenticated Executor UI without printing its bearer token. box save pauses Executor, validates the archive, encrypts it, verifies it, and writes it under backups/.

Daily use

Common commands
Command	Purpose
`./box ls`	List managed boxes, their state, and Executor URLs.
`./box enter alpha`	Start the box and attach its persistent tmux session.
`./box open alpha`	Open the authenticated Executor UI.
`./box stop alpha`	Stop the VM without deleting its state.
`./box start alpha`	Start a stopped VM.
`./box doctor alpha`	Check tools, Executor, MCP wiring, durable state, and host forwarding.

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

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 while Executor is paused, refreshed with current managed assets, rewired, and health-checked. An incomplete destination is removed after failure.

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.

Backups preserve state, not an exact machine

A later restore installs then-current upstream tool releases before applying saved state. The archive includes a runtime-version manifest for diagnosis, but it is not an offline, reproducible machine image.

Health and repair

Start with the doctor whenever a box feels partly broken:

./box doctor alpha

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.

Important settings
Setting	Effect
`BASE_IMAGE`	OCI image used for new boxes.
`NODE_MAJOR`	NodeSource major line installed during provisioning.
`INSTALL_HERMES`	Enable or disable Hermes installation.
`INSTALL_EXECUTOR`	Enable or disable Executor installation.
`EXPOSE_EXECUTOR_WEB`	Forward Executor to a unique loopback-only host port.
`EXECUTOR_PORT_LO` / `HI`	Range used for unique host ports.
`WIRE_EXECUTOR_MCP`	Register Executor's authenticated HTTP MCP endpoint with Claude and Codex.

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 runs Bash syntax checks, ShellCheck, static contracts, encrypted archive round-trip tests, validation-before-VM tests, temporary-file cleanup checks, and mock failure rollback.