hermes - ✅(Solved) Fix Gateway mode: checkpoints not working despite config enabled (missing AIAgent params) [1 pull requests, 2 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#18841Fetched 2026-05-03 04:53:56
View on GitHub
Comments
2
Participants
2
Timeline
6
Reactions
0
Timeline (top)
labeled ×3commented ×2cross-referenced ×1

When running Hermes in gateway mode, the /rollback command shows "Checkpoints are not enabled" even though checkpoints.enabled: true is set in config.yaml.

Even after enabling checkpoints in config, the /rollback command lists no checkpoints and cannot restore any filesystem state, making the feature useless in gateway mode.

Error Message

Read checkpoint config

cp_cfg = {} try: import yaml as _y _cfg_path = _hermes_home / "config.yaml" if _cfg_path.exists(): with open(_cfg_path, encoding="utf-8") as _f: _data = _y.safe_load(_f) or {} cp_cfg = _data.get("checkpoints", {}) if isinstance(cp_cfg, bool): cp_cfg = {"enabled": cp_cfg} except Exception: pass

Then in AIAgent creation:

agent = AIAgent( model=turn_route["model"], **turn_route["runtime"], # ... existing params ... checkpoints_enabled=cp_cfg.get("enabled", False), checkpoint_max_snapshots=cp_cfg.get("max_snapshots", 50), )

Root Cause

In gateway/run.py, when creating the main AIAgent instance (line ~12276), the checkpoints_enabled and checkpoint_max_snapshots parameters are NOT passed to the AIAgent constructor:

# gateway/run.py - line ~12276 (current code)
agent = AIAgent(
    model=turn_route["model"],
    **turn_route["runtime"],
    max_iterations=max_iterations,
    # ... other params ...
    fallback_model=self._fallback_model,
    # ❌ MISSING: checkpoints_enabled and checkpoint_max_snapshots
)

Compare with cli.py (lines 3609-3610) which correctly passes these parameters:

# cli.py - correct implementation
agent = AIAgent(
    # ...
    checkpoints_enabled=self.checkpoints_enabled,
    checkpoint_max_snapshots=self.checkpoint_max_snapshots,
)

As a result:

  • The AIAgent instance in gateway mode always uses default values (checkpoints_enabled=False)
  • CheckpointManager.ensure_checkpoint() is never called before file operations
  • Shadow repos (.hermes-shadow) are never created
  • /rollback has nothing to restore

Fix Action

Fix / Workaround

Reproduction Steps

  1. Set in config.yaml:
    checkpoints:
      enabled: true
      max_snapshots: 50
  2. Start Hermes in gateway mode
  3. Perform file operations (e.g., write_file, patch)
  4. Run /rollback command
  5. Observe: "No checkpoints found for /root"

PR fix notes

PR #18843: fix(gateway): pass checkpoints config to AIAgent in gateway mode

Description (problem / solution / changelog)

Summary

Gateway mode did not pass checkpoints_enabled or checkpoint_max_snapshots to AIAgent when creating agent instances, causing the /rollback command to always report "Checkpoints are not enabled" even when checkpoints.enabled: true was set in config.yaml.

The CheckpointManager.ensure_checkpoint() was never called before file-mutating tool calls, so shadow repos (.hermes-shadow/) were never created and /rollback had nothing to restore.

Root Cause

  • cli.py (line 3618) correctly passes checkpoints_enabled=self.checkpoints_enabled and checkpoint_max_snapshots=self.checkpoint_max_snapshots to AIAgent.__init__
  • gateway/run.py had two AIAgent construction sites (async tool run at ~line 8558, main message handler at ~line 12403) that did NOT pass these parameters
  • Default value of checkpoints_enabled in AIAgent.__init__ is False, so checkpoints were always disabled in gateway mode

Fix

  1. Added _load_checkpoint_config() static method to GatewayRunner that mirrors how cli.py reads checkpoint config from config.yaml
  2. Store self._checkpoints_enabled and self._checkpoint_max_snapshots in GatewayRunner.__init__
  3. Pass both parameters to both AIAgent construction sites in gateway/run.py

Testing

  • Syntax check passes (python3 -m py_compile gateway/run.py)
  • The /rollback handler in gateway already reads checkpoint config correctly (line 8439) — this fix ensures the agent also gets the config at construction time

Fixes #18841

Changed files

  • gateway/run.py (modified, +28/-0)

Code Example

checkpoints:
     enabled: true
     max_snapshots: 50

---

# gateway/run.py - line ~12276 (current code)
agent = AIAgent(
    model=turn_route["model"],
    **turn_route["runtime"],
    max_iterations=max_iterations,
    # ... other params ...
    fallback_model=self._fallback_model,
    # ❌ MISSING: checkpoints_enabled and checkpoint_max_snapshots
)

---

# cli.py - correct implementation
agent = AIAgent(
    # ...
    checkpoints_enabled=self.checkpoints_enabled,
    checkpoint_max_snapshots=self.checkpoint_max_snapshots,
)

---

# Read checkpoint config
cp_cfg = {}
try:
    import yaml as _y
    _cfg_path = _hermes_home / "config.yaml"
    if _cfg_path.exists():
        with open(_cfg_path, encoding="utf-8") as _f:
            _data = _y.safe_load(_f) or {}
        cp_cfg = _data.get("checkpoints", {})
        if isinstance(cp_cfg, bool):
            cp_cfg = {"enabled": cp_cfg}
except Exception:
    pass

# Then in AIAgent creation:
agent = AIAgent(
    model=turn_route["model"],
    **turn_route["runtime"],
    # ... existing params ...
    checkpoints_enabled=cp_cfg.get("enabled", False),
    checkpoint_max_snapshots=cp_cfg.get("max_snapshots", 50),
)
RAW_BUFFERClick to expand / collapse

Bug: Gateway mode checkpoints not working despite checkpoints.enabled: true in config

Description

When running Hermes in gateway mode, the /rollback command shows "Checkpoints are not enabled" even though checkpoints.enabled: true is set in config.yaml.

Even after enabling checkpoints in config, the /rollback command lists no checkpoints and cannot restore any filesystem state, making the feature useless in gateway mode.

Reproduction Steps

  1. Set in config.yaml:
    checkpoints:
      enabled: true
      max_snapshots: 50
  2. Start Hermes in gateway mode
  3. Perform file operations (e.g., write_file, patch)
  4. Run /rollback command
  5. Observe: "No checkpoints found for /root"

Root Cause

In gateway/run.py, when creating the main AIAgent instance (line ~12276), the checkpoints_enabled and checkpoint_max_snapshots parameters are NOT passed to the AIAgent constructor:

# gateway/run.py - line ~12276 (current code)
agent = AIAgent(
    model=turn_route["model"],
    **turn_route["runtime"],
    max_iterations=max_iterations,
    # ... other params ...
    fallback_model=self._fallback_model,
    # ❌ MISSING: checkpoints_enabled and checkpoint_max_snapshots
)

Compare with cli.py (lines 3609-3610) which correctly passes these parameters:

# cli.py - correct implementation
agent = AIAgent(
    # ...
    checkpoints_enabled=self.checkpoints_enabled,
    checkpoint_max_snapshots=self.checkpoint_max_snapshots,
)

As a result:

  • The AIAgent instance in gateway mode always uses default values (checkpoints_enabled=False)
  • CheckpointManager.ensure_checkpoint() is never called before file operations
  • Shadow repos (.hermes-shadow) are never created
  • /rollback has nothing to restore

Expected Behavior

When checkpoints.enabled: true is set in config.yaml, the gateway-mode agent should:

  1. Initialize CheckpointManager with correct enabled=True
  2. Call ensure_checkpoint() before file-mutating tool calls
  3. Create shadow repos and save checkpoints
  4. Allow /rollback to list and restore checkpoints

Suggested Fix

In gateway/run.py, update the AIAgent instantiation (~line 12276) to pass checkpoint config:

# Read checkpoint config
cp_cfg = {}
try:
    import yaml as _y
    _cfg_path = _hermes_home / "config.yaml"
    if _cfg_path.exists():
        with open(_cfg_path, encoding="utf-8") as _f:
            _data = _y.safe_load(_f) or {}
        cp_cfg = _data.get("checkpoints", {})
        if isinstance(cp_cfg, bool):
            cp_cfg = {"enabled": cp_cfg}
except Exception:
    pass

# Then in AIAgent creation:
agent = AIAgent(
    model=turn_route["model"],
    **turn_route["runtime"],
    # ... existing params ...
    checkpoints_enabled=cp_cfg.get("enabled", False),
    checkpoint_max_snapshots=cp_cfg.get("max_snapshots", 50),
)

Environment

  • Hermes version: (check with hermes --version)
  • Python version: 3.11
  • OS: WSL2 (Ubuntu)
  • Gateway mode: yes
  • Config: checkpoints.enabled: true

Additional Context

  • CLI mode works correctly (cli.py passes the parameters)
  • The /rollback command code itself is correct - it properly initializes CheckpointManager when invoked
  • The bug is that the agent never creates checkpoints during execution
  • Related: The CheckpointManager design doc says it should be called by AIAgent, but gateway mode doesn't wire it up

extent analysis

TL;DR

Update the AIAgent instantiation in gateway/run.py to pass the checkpoint configuration from config.yaml.

Guidance

  • Verify that the checkpoints.enabled and checkpoints.max_snapshots values are correctly read from config.yaml in gateway/run.py.
  • Update the AIAgent creation to include the checkpoints_enabled and checkpoint_max_snapshots parameters, as shown in the suggested fix.
  • Confirm that the CheckpointManager is initialized with the correct enabled value and that ensure_checkpoint() is called before file operations.
  • Test the /rollback command to ensure it can list and restore checkpoints.

Example

The suggested fix provides an example of how to update the AIAgent instantiation:

agent = AIAgent(
    model=turn_route["model"],
    **turn_route["runtime"],
    # ... existing params ...
    checkpoints_enabled=cp_cfg.get("enabled", False),
    checkpoint_max_snapshots=cp_cfg.get("max_snapshots", 50),
)

Notes

This fix assumes that the config.yaml file is correctly formatted and contains the checkpoints section with enabled and max_snapshots values.

Recommendation

Apply the suggested workaround by updating the AIAgent instantiation in gateway/run.py to pass the checkpoint configuration from config.yaml, as this should resolve the issue with checkpoints not being created in gateway mode.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - ✅(Solved) Fix Gateway mode: checkpoints not working despite config enabled (missing AIAgent params) [1 pull requests, 2 comments, 2 participants]