Hermes Airlock

Hermes Airlock is a local-only safety checkpoint for Hermes Agent.

It helps Hermes operators pause before risky experiments: create a production snapshot, create a clean quarantine profile, run work locally inside that quarantine profile, scan what changed since quarantine creation, and copy a redacted Markdown report for manual review before promoting anything.

Airlock v1 is preview/report-first. It does not automatically promote changes, restore production, mutate production memory, invoke Hermes Agent, or start a Hermes chat.

What Airlock helps you do

1. Create a production snapshot before risky experiments. Capture safe metadata and allowlisted profile files so you have a review point before testing something new.
2. Create a clean quarantine profile. Generate a real airlock-* Hermes profile for testing agents, skills, prompts, or plugins away from your production profile. Airlock also captures that profile's clean creation baseline.
3. Run work inside the quarantine profile. Copy the generated local commands and run them manually. Airlock shows HERMES_HOME="<profile_path>" hermes setup first, then HERMES_HOME="<profile_path>" hermes, then HERMES_HOME="<profile_path>" hermes dashboard --host 127.0.0.1 --port 9121 --no-open; it never launches Hermes for you. Credentials are not copied into quarantine. Run setup first to choose a model/provider for this profile.
4. Scan drift since quarantine creation. Compare the quarantine profile's current state against its own creation baseline, then flag risky-looking changes.
5. Copy or export a Markdown review report. Produce a redacted report that an operator can review before making any manual production change.

Dashboard actions in plain English

Action	What it does
Create Snapshot	Creates a real snapshot under airlock/snapshots/ using safe, allowlisted Hermes profile files and metadata. It does not copy .env or raw state.db.
Create Quarantine Profile	Creates a real clean Hermes profile under profiles/airlock-*, captures its baseline, and returns copyable local commands. Credentials are not copied; run hermes setup first to choose a model/provider for this profile.
Scan Drift	Compares the quarantine profile's current files against its own creation baseline. A fresh quarantine profile should report zero drift, and normal runtime files such as logs, caches, sessions, state databases, and default Hermes skill bootstrap files are ignored.
Copy Markdown Report	Copies/exports a redacted review report with findings and drift summary for manual review.

Recommended workflow:

Snapshot → Create Quarantine Profile → Configure Quarantine → Launch CLI/Dashboard → Scan Drift → Copy Markdown Report

Practical use cases

• Test a new Hermes skill before trusting it in production.
• Try a weird or experimental agent profile without polluting production memory.
• Run risky prompt experiments in a clean quarantine profile.
• Debug memory contamination after a bad session or suspicious instruction drift.
• Create a concise report for manual review before copying any change back to production.

What Airlock is not

• It is not a full security sandbox.
• It does not automatically promote quarantine changes.
• It does not automatically restore production.
• It does not automatically mutate production memories.
• It does not replace operator review.

What is included

• Native dashboard plugin structure under plugin/hermes-airlock/dashboard/
• Local Python backend core in airlock_cli/
• Vendored plugin backend core in plugin/hermes-airlock/dashboard/_airlock_core/
• Polished Airlock dashboard UI (dist/index.js, dist/style.css)
• Airlock Glass theme (theme/airlock-glass.yaml)
• Safe demo fixture generator (demo/generate_demo.py)
• Safe install/uninstall scripts with --home support
• Standard-library tests

Safety guarantees

• No Hermes Agent invocation.
• No Hermes chat startup.
• No external network calls from the plugin.
• No cloud services.
• No .env, API key, OAuth token, cookie, or credential-file copying.
• No API key/provider auto-configuration in quarantine; run hermes setup inside the quarantine profile to choose a model/provider manually.
• .env and secret-like files are path/type findings only and are not read into reports.
• state.db is metadata-only and is never copied.
• Browser profiles, cookies, OAuth tokens, credential stores, keychains, and secret-bearing files are forbidden.
• Tests use temp fixtures or /tmp/hermes-airlock-demo.
• Promotion and restore are preview/report-only.
• In a development checkout, Airlock refuses the user's real default Path.home() / ".hermes" and any of its descendants.
• In an installed production dashboard plugin, Airlock may operate on the exact resolved Hermes home only when plugin_api.py is loaded from <HERMES_HOME>/plugins/hermes-airlock/dashboard/.
• The dashboard backend rejects arbitrary user-supplied folders; accepted backend homes are the installed plugin's own Hermes home, /tmp/hermes-airlock-demo, or test fixtures.
• Airlock-owned writes are constrained to <HERMES_HOME>/airlock/snapshots/, <HERMES_HOME>/airlock/reports/, and <HERMES_HOME>/profiles/airlock-*.
• Airlock does not automatically mutate production memories; promotion and restore remain report/preview-only.

Hermes home resolution is generic and user-local: explicit hermes_home payload first, then HERMES_HOME, then Path.home() / ".hermes". Airlock never relies on a specific username or machine path.

Demo quickstart

python3 demo/generate_demo.py --home /tmp/hermes-airlock-demo --force
./install.sh --home /tmp/hermes-airlock-demo
HERMES_HOME=/tmp/hermes-airlock-demo python3 plugin/hermes-airlock/dashboard/plugin_api.py dashboard_state

Uninstall from demo home:

./uninstall.sh --home /tmp/hermes-airlock-demo

Test

python3 -m unittest discover -s tests -v
node --check plugin/hermes-airlock/dashboard/dist/index.js
python3 -m compileall -q airlock_cli demo tests plugin/hermes-airlock/dashboard

Install

For a demo or test home:

./install.sh --home /tmp/hermes-airlock-demo

For a real Hermes install, run intentionally:

./install.sh --home "$HOME/.hermes"

The installer copies only:

• manifest.json
• plugin_api.py
• dist/index.js
• dist/style.css
• _airlock_core/*.py
• theme/airlock-glass.yaml

It does not copy fixtures, .env, snapshots, reports, profiles, or secrets.

Project structure

airlock_cli/                         # local backend core
plugin/hermes-airlock/dashboard/      # Hermes dashboard plugin
theme/airlock-glass.yaml              # dashboard theme tokens
demo/                                 # safe demo fixture generator
docs/                                 # product/spec/submission docs
tests/                                # unittest regression suite

Status

See docs/STATUS_REPORT.md for phase-by-phase implementation evidence and verification output.