hermes - ✅(Solved) Fix [Bug]: SSH ControlMaster socket path exceeds macOS limit with IPv6 hosts [1 pull requests, 1 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#11840Fetched 2026-04-18 05:58:37
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
Participants
Timeline (top)
cross-referenced ×2referenced ×2commented ×1labeled ×1

Error Message

RuntimeError: SSH connection failed: unix_listener: path "/var/folders/2t/wbkw5yb158jc3zhswgl7tz9c0000gn/T/hermes-ssh/hermes@9373:9b91:4480:558d:708e:e601:24e8:d8d0:22.sock.O4Mllpst3K7uFRmH" too long for Unix domain socket

Root Cause

Root Cause Analysis (optional)

Fix Action

Fixed

PR fix notes

PR #11851: fix(ssh): hash ControlMaster socket filename to avoid macOS 104-char limit

Description (problem / solution / changelog)

Problem

Closes #11840.

When connecting to hosts with long names — especially IPv6 addresses like 2001:0db8:85a3:0000:0000:8a2e:0370:7334 — the SSH ControlMaster socket path (/tmp/hermes-ssh/user@host:port.sock) exceeds the macOS AF_UNIX sun_path limit of 104 bytes, causing ControlMaster to fail silently.

Fix

Replace the raw user@host:port.sock filename with a truncated SHA-256 hash: h-<16 hex chars>.sock (24 chars total). This keeps the full path safely under both macOS (104) and Linux (108) limits while remaining deterministic.

Tests

Added 5 unit tests in TestSocketFilename:

  • Short host, IPv6 address, 200+ char hostname → all under limit
  • Deterministic output for same inputs
  • Different ports produce different filenames

Changed files

  • tests/tools/test_ssh_environment.py (modified, +39/-0)
  • tools/environments/ssh.py (modified, +19/-1)

Code Example

RuntimeError: SSH connection failed: unix_listener: path "/var/folders/2t/wbkw5yb158jc3zhswgl7tz9c0000gn/T/hermes-ssh/hermes@9373:9b91:4480:558d:708e:e601:24e8:d8d0:22.sock.O4Mllpst3K7uFRmH" too long for Unix domain socket

---



---

self.control_socket = self.control_dir / f"{user}@{host}:{port}.sock"

---

import hashlib

# In __init__:
socket_id = hashlib.sha256(f"{user}@{host}:{port}".encode()).hexdigest()[:12]
self.control_socket = self.control_dir / f"{socket_id}.sock"
RAW_BUFFERClick to expand / collapse

Bug Description

On macOS, Unix domain socket paths are limited to 104 characters. When connecting to an SSH host via IPv6, the ControlMaster socket path generated by SSHEnvironment exceeds this limit, causing all terminal/file operations to fail immediately.

Steps to Reproduce

  1. Configure Hermes with an SSH environment pointing to an IPv6 address
  2. Start Hermes
  3. Any tool call fails immediately

Expected Behavior

Hermes can connect and use tools on remote server.

Actual Behavior

Any command or tool requiring remote execution is not available.

Affected Component

Setup / Installation, Tools (terminal, file ops, web, code execution, etc.)

Messaging Platform (if gateway-related)

No response

Debug Report

RuntimeError: SSH connection failed: unix_listener: path "/var/folders/2t/wbkw5yb158jc3zhswgl7tz9c0000gn/T/hermes-ssh/hermes@9373:9b91:4480:558d:708e:e601:24e8:d8d0:22.sock.O4Mllpst3K7uFRmH" too long for Unix domain socket

Operating System

macOS Sequoia 15.7.3

Python Version

3.14.3

Hermes Version

v0.10.0

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

In tools/environments/ssh.py, the control socket path embeds the full host address literally:

self.control_socket = self.control_dir / f"{user}@{host}:{port}.sock"

macOS's long temp directory (/var/folders/.../T/) + the IPv6 address + SSH's random suffix easily exceeds the 104-char Unix socket path limit.

Proposed Fix (optional)

Use a hash of the connection parameters instead of embedding them literally:

import hashlib

# In __init__:
socket_id = hashlib.sha256(f"{user}@{host}:{port}".encode()).hexdigest()[:12]
self.control_socket = self.control_dir / f"{socket_id}.sock"

Are you willing to submit a PR for this?

  • I'd like to fix this myself and submit a PR

extent analysis

TL;DR

Use a shortened socket path, such as a hash of the connection parameters, to avoid exceeding the 104-character Unix domain socket path limit on macOS.

Guidance

  • Identify the source of the long socket path in the SSHEnvironment class, specifically the line where the control_socket path is generated.
  • Consider using a hash function like hashlib to shorten the socket path, as proposed in the issue.
  • Verify that the new socket path is within the 104-character limit by logging or printing the path before attempting to use it.
  • Test the modified SSHEnvironment class with an IPv6 address to ensure that the issue is resolved.

Example

import hashlib

# In __init__:
socket_id = hashlib.sha256(f"{user}@{host}:{port}".encode()).hexdigest()[:12]
self.control_socket = self.control_dir / f"{socket_id}.sock"

Notes

This fix assumes that the issue is solely caused by the long socket path and that shortening it will resolve the problem. However, additional testing may be necessary to ensure that the shortened path does not introduce other issues, such as socket path collisions.

Recommendation

Apply the proposed workaround using a hash of the connection parameters to shorten the socket path, as it is a straightforward and effective solution to the problem.

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 [Bug]: SSH ControlMaster socket path exceeds macOS limit with IPv6 hosts [1 pull requests, 1 comments, 2 participants]