hermes-gpt

hermes-gpt is a local-first MCP sidecar for Hermes Agent. It exposes selected Hermes capabilities to trusted MCP clients without modifying Hermes Agent source files.

Website · Docs hub · Canonical documentation

Current status

• Repository version: 0.17.0
• GitHub releases: published versions and artifacts
• PyPI: package versions; verify this channel independently
• Python requirement: 3.10+
• MCP SDK (current source): 1.28.1+ or 2.x; see compatibility.
• Deployment posture: local-dev / trusted-machine only
• Remote public hosting: unsupported without a real authenticated private boundary

[!IMPORTANT] GitHub releases and PyPI can temporarily be on different versions. The PyPI badge above is the source of truth for what pip install hermes-gpt installs. The notification relay, Owner inbox acknowledgements and Flight Deck inbox actions, the one-call Mission launch, and hermes-gpt update --version require 0.16.0 or newer. The owner inbox, review assist, and connector tool profiles require 0.15.0 or newer. Declared artifact acceptance and recovery require 0.14.0 or newer. Autopilot requires 0.13.0 or newer and HERMES_GPT_AUTOPILOT=1.

For the current documentation map and source-of-truth rules, start with docs/README.md. Agents working in this repository should also read AGENTS.md.

What v0.17.0 adds

Daily Operations connects bounded Mission launch, durable launch receipts, and evidence review in Flight Deck. Preview a Mission, confirm once, and recover the original attempt after a disconnect. Review pending work from the Owner inbox using exact contract/task references, then explicitly reconcile it. Delivery status is read-only and labels unverified sends honestly.

See Daily Operations for gates and recovery, and v0.17.0 release notes for scope and validation limits. This includes the v0.16.2 finite session protocol and Autopilot terminal-state fix; live Desktop acceptance remains unverified.

What v0.16.0 adds

Close the loop makes what waits on the Owner reach them and lets them resolve it in one place, with no new authority. Every mutating path keeps its existing gates.

1. Notifications (default off) - hermes-gpt-attention-relay sends new Owner inbox items to Hermes targets through hermes send, which reuses the platforms configured in Hermes Agent, or to iMessage through imsg rpc. Messages are notifications only: they never carry approvals or commands, and replies do nothing. Dedupe, digests, and per-target backoff are built in. See attention delivery and the setup quick start.
2. A complete Owner inbox - Work Contracts that still need review acceptance appear as contract_review_pending. Items carry stable ids, and hermes_owner_inbox_ack hides handled items without changing any Mission, plan, contract, or delegation. See owner inbox.
3. Act from Flight Deck - approve a Mission, approve or reject an approval-frontier node, stop Autopilot, or acknowledge an item, through the same gated tools. Browser node transitions require Owner Mode. Cross-site requests to the action route are refused. See Flight Deck actions.
4. One-call Mission launch (Autopilot-gated) - hermes_mission_launch creates the Mission, derives its plan, optionally sets a budget, and starts Autopilot. It is dry run by default, stops at the first refusal, and never approves a Mission. See one-call launch.
5. Safe package upgrade - hermes-gpt update --apply --version 0.16.0 --venv ... --rollback-dir ... upgrades one virtual environment after a digest check and an import check, with a rollback snapshot. See updating.

Also fixed: contract review reads the whole review-acceptance store, so a late acceptance counts. With every optional gate unset the main server registers 139 tools, and 140 with HERMES_GPT_ENABLE_FINANCE=1, the connector acceptance surface. HERMES_GPT_AUTOPILOT=1 adds 4, HERMES_GPT_ATTENTION_DELIVERY=1 adds 1, HERMES_GPT_ENABLE_JEV=1 adds 3, and hermes_review_assess adds 1 more when both Jev and review-assist gates are set. See v0.16.0 release notes and the CHANGELOG.

What v0.15.0 adds

Owner Loop makes Owner decisions faster without adding authority: one read-only list of what is waiting, an advisory review score that never counts as evidence, smaller chat tool surfaces, and safer file-backup configuration. Every mutating path keeps its existing gates.

1. Owner inbox (read-only) - hermes_owner_inbox is always registered. It lists Missions awaiting approval, Autopilot runs waiting for the Owner, and controller attention, with source health (complete). It approves, advances, and writes nothing; each item names the existing gated tool to use. See docs/owner-inbox.md.
2. Advisory review assist (default off) - hermes_review_assess asks the pinned Jev adapter for an advisory score of a dispatched Work Contract. It needs both HERMES_GPT_ENABLE_JEV=1 and HERMES_GPT_REVIEW_ASSIST=1, is never review acceptance or Work Contract evidence, and is audited without a task_id. See docs/review-assist.md.
3. Jev decision bridge (default off) - three typed judgments (hermes_jev_yes_no, hermes_jev_choose, hermes_jev_score) reuse the pinned community jev-mcp adapter over local stdio, with no gateway change and no new authority. Owner key provisioning is a separate setup step. See docs/jev.md.
4. Connector tool profiles - HERMES_GPT_TOOL_PROFILE selects full (default), operator (without raw host primitives), or chat-lean (30 status, oversight, and owner-decision tools with every gate off). Profiles only remove tools and never bypass a gate. See MCP compatibility.
5. Safer file backups - HERMES_GPT_OPERATOR_FILE_BACKUPS disables backups only for an explicit 0, false, no, off, or disabled; unset, empty, or unrecognized values keep them on. Thanks to @brunocasado for #85. See Operator mode.

The v0.15.0 connector surface was 138 tools (137 in v0.14.0, plus hermes_owner_inbox). See v0.15.0 release notes and the CHANGELOG for that release's counts and gates.

What v0.14.0 adds

Acceptance and recovery strengthens Autopilot's completion checks and handles confirmed deliverable failures after successful execution.

1. Declare checks before dispatch. Optional node artifact_requirements set minimum/maximum file sizes and expected SHA-256 values. Each attempt's immutable Work Contract carries these checks, and rework preserves them.
2. Recover confirmed failures. Successfully executed work with bad required artifacts gets a durable 30-second delivery grace. If the artifacts still fail and every other required check passes, the delegation fails with validation_failed; Autopilot can use its existing bounded semantic replan. Unreadable evidence, pending review, and ambiguous execution never trigger automatic redispatch.
3. Explain completion. Flight Deck shows check results, fixed artifact failure reasons, delivery grace, and unverified evidence through its read-only supervision panel. No new tools or browser mutation controls are introduced.

Size and digest checks prove the declared requirements; semantic quality still requires review. Autopilot remains default off and final Mission approval remains Owner-only. See v0.14 release notes and Autopilot. Verify PyPI separately before relying on v0.14 features in an installed package.

What v0.13.0 adds

v0.13.0 adds Autopilot: a durable, default-off runtime that drives one Mission through its MissionPlan (place, run in parallel, observe, validate, recover, and stop for approval) without a human re-triggering every node. It is a caller of the existing Mission, plan, placement, Work Contract, delegation, budget, and live-event surfaces and adds no authority of its own. Full guide: docs/autopilot.md.

1. Three gated tools - hermes_autopilot_start, hermes_autopilot_status, and hermes_autopilot_stop exist only when HERMES_GPT_AUTOPILOT=1; with it unset the connector surface is unchanged at 137 tools. Start is dry-run first and needs workspace level, direct apply mode, and confirm=true. A detached worker owns one Mission and survives an MCP server restart.
2. It never crosses an approval boundary - approval nodes and high_impact nodes are never dispatched or advanced; Autopilot reports waiting_for_owner and dispatches nothing past them. It cannot approve or complete a Mission: it stops at awaiting_approval, and only hermes_mission_approve in Owner mode completes it.
3. Evidence, not claims - a node completes only when its Work Contract validates against observed state; a worker's own success report is never accepted, and missing evidence fails closed.
4. Bounded everything - concurrency, attempts per node, replans, and runtime are capped at start; new dispatch is held whenever the Mission's budget envelope is not verifiably within its limit; recovery is decided by the existing failure classifier and only transient failures are retried.
5. Deliverables and supervision - node artifact requirements are enforced in isolated attempt workspaces; unfinished work blocks plan replacement, and independent reconciliation preserves bounded recovery. Flight Deck includes an Autopilot panel and its built assets ship in release wheels.
6. Additive elsewhere - hermes_autopilot_status carries a derived summary without changing any earlier key, Flight Deck gets a read-only Autopilot view, and a failed delegation attempt can now be marked superseded by its successor (see docs/missions.md) without changing any approval rule.

See CHANGELOG.md for the complete v0.13.0 change list.

What v0.12.0 adds

v0.12.0 is the vNext slice-2 release: the two designed-but-deferred mutation paths gain a gated execution rung — budget D3 hard-block enforcement and the controller L2 rung — and both are DEFAULT OFF, so every existing read-only, dry-run, and shadow surface stays byte-identical until an operator arms the gates.

1. Budget D3 hard-block enforcement (gated, default off) - operator_mission_budget.enforce_budget_breaker executes the on-crossing action set: pause the Mission through the existing transition (reason budget_breaker), emit one fleet-attention INTERRUPT envelope through the existing controller attention spool (the delivery broker delivers it — the server never self-sends), and append one budget_events break row. It acts only when the per-call confirm, the HERMES_GPT_BUDGET_HARD_BLOCK=1 machine gate, live Operator policy (enabled plus direct apply mode), and the per-mission hard_block_enabled plus pause_on_cross flags all hold. An anti-TOCTOU policy re-snapshot before acting, idempotent repeat (already_enforced, at most one spool entry), fail-closed need_attention when the Mission is not pausable, bounded record fields, and loud spool failures are covered by tests. hermes_budget_check gains keyword-only enforce / confirm; the default enforce=False result is byte-identical to the previous read-only evaluation.
2. Controller L2 rung and placement-informed dispatch (gated, default off) - hermes_controller_reconcile can execute at most one action per pass: the pass's smallest computed recovery action, dispatched through the existing Work Contract and delegation authority surfaces rather than a new dispatch mechanism. Execution requires the per-call confirm, the HERMES_GPT_CONTROLLER_EXECUTE=1 machine gate, live Operator policy (enabled, direct apply mode, and workspace level), and dry_run=false. The action is idempotency-keyed and a pre-dispatch intent row is written first, so a crash reconciles fail-closed instead of re-dispatching. Any other combination stays decision-only and names a stable refusal reason; hermes_controller_status reports execution_enabled plus an executions rollup.
3. The §7.7 prohibitions still bind at L2 - the rung never completes work, approves anything, weakens evidence, auto-redispatchs reconciling work, rewrites a plan, retries without bound, places without authority, or touches secrets. no_capable_target still escalates through the attention spool, and high-impact authorization classes keep their human gate.
4. No new tools, and no change while disabled - the connector surface stays pinned at 137 tools with no duplicate registration, the new confirm parameter on defaults to , and with the machine gates unset the reconcile envelope is byte-identical to v0.11.0 ( false, no member).

See CHANGELOG.md for the complete v0.12.0 change list.

What v0.11.0 adds

v0.11.0 is a compatibility-and-reach release on top of the vNext slice-1 foundation: a verified Google Gemini Spark custom-app client profile, MCP Python SDK 2.x support, profile-aware Bot Chat and session delivery, and the post-v0.10 security remediation — with no change to the read-only / dry-run / shadow authority ladder and no new mutating surface enabled by default.

1. Gemini Spark custom-app support (opt-in client profile) - HERMES_GPT_OAUTH_GEMINI_ENABLE=1 registers a second, isolated confidential OAuth client (_CLIENT_ID / _CLIENT_SECRET / _REDIRECT_URI) with its own secret and exact-match redirect allowlist; the primary ChatGPT client is untouched, and single-client behavior is byte-identical when the profile is disabled. Verified end-to-end against Google's consumer Gemini Apps connector with a read-only profile. Setup guide: docs/gemini-spark.md.
2. MCP Python SDK 2.x support - the server runs on mcp 1.28.1+ or 2.x with identical transport, auth, and Operator-gate behavior; CI tests both families with wire-level negotiation assertions. See docs/mcp-compatibility.md.
3. Profile-aware Bot Chat and session delivery - session history/control resolve the selected Hermes profile (allowlist-validated), and hermes_bot_chat_get / hermes_bot_chat_send deliver the canonical Bot Chat directly. The cross-process token-store lock is now portable on Windows.
4. Security and reliability remediation - signed OAuth access tokens require durable-store presence, revocation advances a durable epoch transactionally, refresh rotation is atomic, controller reconcile persistence is gated behind workspace + direct apply mode, and ledger pagination uses per-source watermark cursors. Fleet loopback Agent Cards and unknown-manifest-peer admission (lowest ceiling) smooth machine enrollment.

See CHANGELOG.md for the complete v0.11.0 change list.

What v0.10.0 adds

v0.10.0 is the vNext slice-1 release: additive, decision-only derived mission views plus a shadow/observe mission controller, preserving the read-only / dry-run / shadow authority ladder. It adds ~27 MCP tools; none can mutate a Mission, dispatch work, or approve anything in this release.

1. MissionPlan (decomposition DAG) - hermes_plan_create/get/list/validate/decompose/review/node_transition/set_status: a deterministic, bounded decomposition DAG over a MissionSpec. Plan create/node-transition/set-status mutate only the isolated plan store (dry-run-first) and are read-only with respect to the Mission lifecycle.
2. Derived capability-manifest and mission-ledger views (read-only) - hermes_capability_manifest, hermes_mission_ledger, hermes_mission_ledger_replay: a queryable capability index and a merged, replayable, cursor-paginated per-mission event timeline, both with explicit read-only hints and no mutation path.
3. Mission budget envelope (dry-run) - hermes_budget_set/get/check/record: a per-mission spend envelope and read-only budget_check evaluation surface. The D3 hard-block path is designed but flag-default-off.
4. Deterministic placement scoring (dry-run) - hermes_placement_score/candidates/get/list: filter-and-score over the derived capability index; decision output only (would_assign always False), no assignment executes.
5. Semantic failure classification + recovery matrix - hermes_failure_classify, hermes_failure_taxonomy, hermes_recovery_matrix, hermes_controller_plan_list: the Ops 8-class taxonomy and deterministic smallest-first recovery matrix; decision output only (would_execute always False).
6. Supervised mission controller — shadow/observe reconciler loop - hermes_controller_reconcile/status/lease_list/trigger: a T1-T5 trigger model, per-mission pass lease, and a single shadow reconcile pass that emits the smallest recovery action as a proposal only. controller_telemetry reports deterministic GREEN / YELLOW / RED health.

See CHANGELOG.md for the complete v0.10 change list; the vNext design notes are in docs/design/ and the manifest/ledger guide is docs/vnext-capability-manifest-and-mission-ledger.md.

What v0.9.0 adds

v0.9.0 completes the control-plane layer with first-class durable Missions, a unified delegation lifecycle, and a durable live-event bus:

1. First-class Mission lifecycle - a bounded, restart-safe parent record that groups an objective, acceptance criteria, bounded context references, an explicit skills manifest, Swarm/work/delegation attachments, and a final Owner approval that defaults on. Tools: hermes_mission_create/get/list/update/attach/transition/reconcile/approve. See Missions (v0.9).
2. Unified delegation lineage - a durable, normalized delegation lifecycle (hermes_delegation_dispatch/get/list/reconcile/cancel) above existing Work Contract and runner/Fabric execution. It is lineage/state metadata, not a second execution authority; terminal success stays reconciling until the matching immutable contract has a SATISFIED verdict. Adds opencode as a first-class local runner backend. See Delegations (v0.9).
3. Durable live events - an authenticated, bounded event bus with hermes_live_events_cursor / hermes_live_events_since plus an /events/ws WebSocket stream, for completion and wake-up delivery without polling every underlying store. Events are notifications, never proof. See Live events (v0.9).
4. Runner-neutral job supervision - hermes_job_status / hermes_job_wait background-job polling regardless of backend.
5. Bounded Finance bridge - opt-in hermes_finance_analyze for the local finance profile (HERMES_GPT_ENABLE_FINANCE=1).

See CHANGELOG.md for the complete v0.9 change list and the individual surface guides linked below.

What v0.8.0 adds

v0.8.0 "Fabric" turns the v0.7 control plane into a local-first distributed execution fabric:

1. Cross-machine Swarm execution - bounded stages can execute through an authenticated hermes-gpt-fabric-peer while the coordinator remains authoritative.
2. Capability-aware auto routing - placement uses current node health/freshness, backend capability, profile/workspace policy, and authority ceilings, with explicit overrides preserved.
3. Remote evidence and artifacts - remote evidence is admitted into the existing Work Contract boundary; missing required evidence fails closed and artifact bytes are hash-verified.
4. Restart/timeout/cancel reconciliation - recoverable ambiguity reconciles the original attempt, with single-writer/write-epoch protections for mutation-capable paths.
5. Fabric Flight Deck visibility - read-only node, placement, attempt, evidence, and routing views expose the authoritative selected-route fields.

The final Fabric implementation passed fresh real two-machine G6 acceptance and independent review; the authoritative acceptance record is on issue #37. G7 Owner ship authorization is recorded on issue #27. See the v0.8.0 release notes for the acceptance boundary, known presentation limitation, and additional changes included since v0.7.0.

What v0.7.0 adds

v0.7.0 "Flight Deck" adds four coordinated capabilities on top of the v0.6 control plane:

1. Production review evidence - hermes_review_accept, an owner-gated writer with distinct-reviewer enforcement, feeding hermes_contract_validate.
2. Structured event history - hermes_events_query / hermes_events_tail, a read-only redacted timeline over audit/swarm/codex/cron/kanban.
3. Durable encrypted token storage - OAuth credentials survive restarts (AES-256-GCM envelope) with hermes_oauth_status / hermes_oauth_revoke.
4. Restart reconciliation - hermes_swarm_reconcile marks interrupted swarm stages blocked (never auto-advances); stage advance is idempotent.

Plus the MCP compatibility manifest, cross-machine seam interfaces (stretch, interfaces only), and a CI hermeticity fix. See the v0.7.0 release notes, the MCP compatibility manifest, and retention policy.

What v0.6.0 adds

v0.6.0 adds three coordinated control-plane layers on top of the existing Operator and Codex integrations:

1. Mission Control - bounded, audited, read-only operational views through hermes_mission_*.
2. Work Contracts - declarative hermes_contract_* work orders whose completion is validated from observed state rather than worker self-report.
3. Swarm Orchestration - bounded hermes_swarm_* DAG workflows with explicit ownership, capped concurrency, fail-closed validation, review gates, and final human approval.

See the v0.6.0 release notes and retention policy.

Choose the path you need

Goal	Start here
Understand the repository and current docs	Documentation map
Run Hermes GPT locally	Local quickstart
Connect ChatGPT/OpenAI privately without publishing Hermes GPT	OpenAI Secure MCP Tunnel
Authenticate a remote MCP connector	OAuth and bearer authentication
Connect Google Gemini (consumer Custom apps)	Gemini Spark custom app
Verify the MCP protocol surface	MCP compatibility manifest
Use Codex as an MCP client	Codex guide
Use ChatGPT or another trusted client to operate Hermes	Operator Mode
Group and approve a larger objective under one lifecycle	Missions (v0.9)
Understand unified delegation lineage across runners	Delegations (v0.9)
See what is waiting on the Owner, read-only

Local quickstart

Install from PyPI

python -m pip install hermes-gpt

Check the PyPI badge before relying on version-specific features.

Run the current source checkout

git clone https://github.com/asimons81/hermes-gpt.git
cd hermes-gpt
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
source .venv/bin/activate
python -m pip install .
hermes-gpt

The source install above supports the MCP server. To include the optional browser UI in a source-built wheel, build its assets before installing/building the Python package:

cd web
npm ci
npm run build
cd ..
python -m pip install .

The locked UI build requires Node ^20.19.0 || >=22.12.0 (Node 24 works); it is also required separately when enabling the Jev bridge. Installing a package does not install Hermes Agent or activate optional gates. Release wheels include built UI assets; an unbuilt source checkout can serve MCP while /ui reports missing assets. See UI configuration.

The v0.16.0 wheel and sdist are attached to the GitHub v0.16.0 release, with SHA256SUMS; see v0.16.0 release notes for Close the Loop. The v0.15.0 wheel and sdist are attached to the GitHub v0.15.0 release, with SHA256SUMS; see v0.15.0 release notes for the Owner loop. The v0.14.0 wheel and sdist are also attached to the GitHub v0.14.0 release. See v0.14 release notes for acceptance and recovery, and Autopilot for setup and limits. The v0.11.0 release notes cover the opt-in Gemini Spark client profile, MCP Python SDK 2.x support, and profile-aware Bot Chat; the v0.10.0 release notes cover the vNext slice-1 surfaces (MissionPlan DAG, derived capability-manifest and mission-ledger views, budget envelope, placement scoring, failure semantics, and the shadow controller); the v0.8.0 release notes cover the Fabric surfaces (hermes-gpt-fabric-peer, capability-aware routing, remote evidence admission, reconciliation); the v0.9 surfaces (Missions hermes_mission_*, delegations hermes_delegation_*, live events hermes_live_events_*, hermes_job_status/wait) are documented in docs/missions.md, docs/delegations.md, and docs/live-events.md. Operator diagnostics and recovery tools (hermes_operator_doctor, , , ) are documented in .

Default local MCP surface

With every optional feature gate unset, the main server registers 139 tools. Setting HERMES_GPT_ENABLE_FINANCE=1 (the connector acceptance surface) registers 140. The five core read-oriented tools are:

• hermes_read_file(path, offset=1, limit=500)
• hermes_search_files(pattern, target="content", path=".", file_glob=None, limit=50)
• hermes_memory(action="search", target="memory", content=None, old_text=None)
• hermes_skill_list()
• hermes_skill_view(name)

Operator, Mission, contract, budget, controller and other policy-gated tools are also registered so callers can discover them and receive explicit refusals when authority is missing. Registration does not authorize mutation; the default policy remains read-only. See Operator Mode. Optional gates add to this inventory, so counts depend on the selected surface and configuration.

Optional legacy feature gates remain available for compatibility:

| Capability | Gate | Default | | --- | --- | | File write / patch | HERMES_GPT_ENABLE_WRITE=1 | hidden | | Memory mutation | HERMES_GPT_ENABLE_MEMORY_WRITE=1 | disabled | | Session search/history | HERMES_GPT_ENABLE_SESSION_SEARCH=1 | hidden | | Session control | HERMES_GPT_ENABLE_SESSION_CONTROL=1 | hidden | | Terminal execution | HERMES_GPT_ENABLE_TERMINAL=1 | hidden | | Vision | HERMES_GPT_ENABLE_VISION=1 | hidden | | Web search / extraction | HERMES_GPT_ENABLE_WEB=1 | hidden |

For new automation and maintenance work, prefer Operator Mode instead of enabling broad legacy write gates.

To shrink the advertised tool list for chat clients, set HERMES_GPT_TOOL_PROFILE to operator or chat-lean. The default is full (unset or empty); profiles only remove tools and never add authority. See connector tool profiles.

Session history and control

Session history and session control are independent, opt-in surfaces.

With HERMES_GPT_ENABLE_SESSION_SEARCH=1, Hermes GPT exposes four bounded read-only history tools: hermes_session_search, hermes_session_list, hermes_session_read, and hermes_session_export, plus hermes_bot_chat_get for canonical Bot Chat resolution. The default transcript roles are user and assistant; system, tool, and function content additionally requires HERMES_GPT_ENABLE_SESSION_INTERNAL_CONTENT=1. Export stays in memory, is size/message bounded, creates no files or paths, and lineage export fails closed.

With HERMES_GPT_ENABLE_SESSION_CONTROL=1, Hermes GPT exposes hermes_session_continue, hermes_session_send, hermes_session_job_status, and hermes_session_job_result. Control jobs are bounded, use fixed argv with shell=False, allow only one active job per session, persist prompt length/hash rather than raw prompts, and return bounded redacted results. A server restart fails closed by marking unowned running jobs orphaned rather than signaling a persisted PID.

See session history and session control. Treat transcript data as private local data.

Run modes

Stdio

For a local MCP client that can launch a subprocess:

hermes-gpt

or from a checkout:

python server.py

Local streamable HTTP

python server.py --http --host 127.0.0.1 --port 7677

Endpoint:

http://127.0.0.1:7677/mcp

Keep the server on loopback. A remote client such as ChatGPT cannot use your machine's 127.0.0.1 directly.

For supported OpenAI products, prefer OpenAI Secure MCP Tunnel when it is available for the target account or workspace. It keeps Hermes GPT on loopback and uses an outbound-only tunnel-client connection instead of publishing a public Hermes GPT hostname. Secure MCP Tunnel alone does not require a public HERMES_GPT_ALLOWED_HOSTS entry.

For other remote clients, use a deliberately configured private/authenticated HTTPS boundary. The existing Cloudflare Tunnel deployment is a public-proxy path with a different Host/authentication boundary. Do not publish an unauthenticated Operator endpoint to the internet.

Hermes GPT can enforce either a strong static bearer token or a built-in, confidential-client OAuth authorization-code flow with rotating refresh tokens. One statically configured client is the default; optional additional client profiles (for example Gemini Spark) can be registered alongside it. With Secure MCP Tunnel, static bearer authentication can be used as an optional local-hop defense in depth. Built-in OAuth requires deliberate browser-facing authorization-server reachability because the authorization server itself is not automatically tunneled. See OpenAI Secure MCP Tunnel and OAuth and bearer authentication; authentication does not activate Operator mutation or Owner Mode.

Operator Mode

Operator Mode is the policy-gated control plane for trusted clients. Tool visibility does not grant mutation authority.

Level	Adds
read_only	status, policy, audit, list/view/diff, Mission Control
cron	cron run/pause/copy/move
skills	skill create/edit/patch/write/copy/sync/delete
skills_config	non-secret config and environment writes
workspace	scoped workspace reads/writes/tests, bounded binary export, gateway restart, Codex jobs, contract/swarm dispatch
owner	break-glass raw command/file operations and final swarm approval; secret paths remain denied

Mutation requires both the server and the individual call to opt in:

HERMES_GPT_OPERATOR_ENABLED=1
HERMES_GPT_OPERATOR_APPLY_MODE=direct

and the mutating call must use dry_run=false. Tools that require explicit confirmation also require confirm=true.

Owner Mode additionally requires:

HERMES_GPT_OWNER_ACTIVE=1
HERMES_GPT_OWNER_ACK=I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE

Workspace/Owner file patch and overwrite tools create a timestamped .bak.* copy by default. Set HERMES_GPT_OPERATOR_FILE_BACKUPS=0 to disable those copies when the workspace already has its own version-control/rollback strategy; atomic replace writes remain enabled.

hermes_export_file(path) is a workspace-authorized, read-only transfer surface for existing local binary files. It requires a non-empty HERMES_GPT_OPERATOR_ALLOWED_PATHS, preserves denied secret paths, defaults to a 4 MiB limit with a 16 MiB hard ceiling, and returns bytes as an MCP embedded resource rather than base64 text. See Binary file export for the complete limits and client-rendering contract.

See docs/operator-mode.md for the complete policy model and exact gates.

Mission Control

Mission Control is structurally read-only. It exposes bounded operational summaries for:

overview, health, profiles, fleet, codex, cron, delegations, failures, approvals, vault, usage, and audit.

Important authorization semantics for HERMES_GPT_MISSION_ALLOWED_SURFACES:

• unset: all read-only Mission Control surfaces are available;
• set to a comma-separated list: only listed valid surfaces are available;
• set to an empty value: all Mission Control surfaces are denied.

Mission Control excludes raw message, memory, transcript, request-dump, credential, token, and profile-secret bodies. Prompt-like content is surfaced only as bounded metadata such as length and SHA-256. Free-text operational fields receive conservative redaction / PII stripping before they leave the host.

Work Contracts

The hermes_contract_* family makes completion verifiable instead of trusting a worker's done claim.

• hermes_contract_define validates and canonicalizes a contract.
• hermes_contract_dispatch is workspace-level and dry-run-first.
• hermes_contract_validate checks observed runs, artifacts, audit evidence, tests, and review evidence.
• hermes_contract_status links a contract to bounded observed state.

Validation is fail-closed. Missing evidence cannot become SATISFIED. Since v0.7.0, required review evidence can be recorded through the owner-gated hermes_review_accept writer (distinct reviewer enforced at write time); before v0.7.0 it had to already exist through an authorized external review path or human approval reference.

Swarm Orchestration

The hermes_swarm_* family runs bounded DAG workflows on top of Work Contracts.

Typical shape:

research -> architecture -> implementation/tests/docs
         -> integration review -> Codex review
         -> acceptance validation -> HUMAN APPROVAL

Key properties:

• explicit stage ownership;
• validated dependencies and cycle rejection;
• default caps of 3 concurrent stages per workflow, 4 per board, and 12 stages per workflow;
• one bounded rework retry before blocking for human attention;
• Codex can review but is never an implementation owner;
• final approval is an Owner-level human gate.

Codex integration

Hermes GPT supports two different Codex relationships. Keep them conceptually separate:

1. Codex as MCP client - install the curated Hermes GPT MCP toolset into Codex. See docs/codex.md.
2. Codex CLI as delegated worker/reviewer - a trusted Hermes GPT client can start bounded async Codex jobs through hermes_codex_*. This requires Operator workspace level, an approved work directory, HERMES_GPT_ENABLE_CODEX_RUNNER=1, direct mode for execution, confirm=true, and dry_run=false.

HERMES_GPT_ALLOW_CODEX_WRITE=1 is required only for workspace-write jobs.

Delegated Codex jobs default to execution_mode="normal". Trusted clients may opt into job-scoped execution_mode="nolo", which adds Codex's -a never approval policy while retaining the requested read-only or workspace-write sandbox. NOLO does not enable danger-full-access, does not bypass Hermes workspace/confirmation gates, and does not create persistent global approval-bypass state.

Tool-name note

The main Hermes GPT server and the curated Codex MCP server have one intentional naming difference:

• main server web extraction: hermes_web_extract
• Codex-focused MCP extraction: hermes_extract_page

Do not silently substitute one name for the other when generating tool calls.

Fleet routing

When Hermes already has authenticated peers in its local A2A registry, Hermes GPT can route bounded work to named peers through hermes_fleet_*.

Callers cannot provide arbitrary peer URLs or bearer tokens. Real dispatch remains constrained by Operator level, direct mode, confirmation, the local registry, and the server-controlled fleet authority manifest. See Operator Mode.

Security invariants

These rules are part of the product contract, not optional recommendations:

• loopback is the default network boundary;
• public unauthenticated hosting is unsupported;
• Operator Mode is not a sandbox;
• mutations are off by default and dry-run-first when enabled;
• secret-looking paths such as .env, auth.json, token stores, .ssh, .aws, and vault secrets remain denied;
• subprocesses use fixed argv and shell=False on protected execution paths;
• raw prompts are not written into Operator audit records;
• Mission Control never exposes raw messages, memory bodies, transcripts, request dumps, or credentials;
• Owner Mode does not disable secret-path protections.

Use OS-level isolation for untrusted input.

Updating

Updates are check-first:

hermes-gpt update

Apply only after reviewing the result:

hermes-gpt update --apply

Git checkout updates require a clean checkout on the default branch and use fast-forward-only behavior. Installed-package updates use pip only when a newer package version is available. See docs/updating.md.

Documentation

Current operational documentation:

• Documentation map and source-of-truth rules
• Runtime provenance and update verification
• Reuse / do-not-rebuild boundary
• OpenAI Secure MCP Tunnel
• OAuth and bearer authentication
• Gemini Spark custom app
• Operator Mode
• Owner inbox (v0.15, acknowledgements and actions in v0.16)
• Attention delivery (v0.16, default off)
• Missions (v0.9)
• Delegations (v0.9)
• Live events (v0.9)
• Codex integration
• Windows ChatGPT -> Codex deployment

Historical release notes and pre-release design / risk / planning artifacts remain in the repository for provenance. They are not authoritative instructions for current runtime behavior. See docs/README.md before using them as implementation guidance.

Development and verification

python -m pip install -r requirements-dev.txt
python -m pytest
python tools/check_package_hygiene.py dist/*

Release-specific checks are listed in RELEASE_CHECKLIST.md.

License

MIT. See LICENSE.