Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: keep Hermes MCP servers in unsloth start hermes (#16949)

Nilay4030f3fc66f8
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index 5c3ac0bd305..c53cfbcce52 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -63,6 +63,7 @@ _HERMES_ENV_KEY = "UNSLOTH_API_KEY"
# Not "unsloth": Hermes strips a `<provider>/` prefix, so unsloth/<repo> stops matching model.default.
_HERMES_PROVIDER = "unsloth-studio"
_HERMES_LEGACY_PROVIDER = "unsloth"
+_HERMES_MCP_MANIFEST = "unsloth_mcp_servers.json"
# Skip the installer's interactive setup wizard: `unsloth start hermes` runs this hint unattended and then writes its own session-scoped Hermes config, so the wizard's global API-key/model prompts would block the launch and point the user at a different provider than the one Unsloth just configured. Both installers expose a skip flag: `-SkipSetup` (PowerShell) and `--skip-setup` (POSIX, passed to the piped script via `bash -s --`). Pin both the fetched script and the repository checkout it performs to the same full commit so a later change to either upstream branch cannot silently replace code that Unsloth executes with the user's privileges.
_HERMES_INSTALL_COMMIT = "f1af945f6c576eccb126fa955edc9be258b33020"
_HERMES_INSTALL_BASE = (
@@ -5996,11 +5997,122 @@ def _set_hermes_provider(
}
+def _hermes_mcp_manifest(home: Path) -> tuple:
+ try:
+ state = json.loads((home / _HERMES_MCP_MANIFEST).read_text(encoding = "utf-8"))
+ origin, servers = state.get("origin"), set(state["servers"])
+ owned = set(state.get("env", ()))
+ except (OSError, ValueError, TypeError, KeyError, AttributeError):
+ return None, set(), set()
+ return (origin if isinstance(origin, str) else None), servers, owned
+
+
+def _hermes_mcp_servers(home: Path) -> Optional[dict]:
+ import yaml
+
+ try:
+ config = yaml.safe_load((home / "config.yaml").read_text(encoding = "utf-8"))
+ except OSError:
+ return {}
+ except (yaml.YAMLError, ValueError):
+ return None
+ servers = config.get("mcp_servers") if isinstance(config, dict) else None
+ return servers if isinstance(servers, dict) else {}
+
+
+def _with_user_hermes_mcp_servers(config: dict, home: Path) -> None:
+ home_key = home.resolve(strict = False)
+ configured = os.environ.get("HERMES_HOME", "").strip()
+ built = None
+ if configured:
+ configured = str(Path(configured).expanduser().resolve(strict = False))
+ origin = _hermes_mcp_manifest(Path(configured))[0]
+ if origin is not None:
+ # A home Unsloth built (the recipe exports HERMES_HOME=home) points back at its origin.
+ built, configured = Path(configured), origin
+ source = _hermes_user_home(configured)
+ if source.resolve(strict = False) == home_key:
+ configured = ""
+ source = _hermes_user_home()
+ if source.resolve(strict = False) == home_key:
+ return
+ servers = _hermes_mcp_servers(source)
+ if servers is None:
+ return
+ if built is not None and built.resolve(strict = False) != home_key:
+ # Servers added in that saved home (hermes mcp add in the recipe shell); the origin wins a clash.
+ inherited = _hermes_mcp_manifest(built)[1]
+ local = _hermes_mcp_servers(built) or {}
+ servers = {
+ **{n: v for n, v in local.items() if n not in inherited and n not in servers},
+ **servers,
+ }
+ carried = _hermes_mcp_manifest(home)[1]
+ current = config.get("mcp_servers")
+ # Only replace what came from the user's config; servers added in this home stay.
+ kept = {
+ name: spec
+ for name, spec in (current.items() if isinstance(current, dict) else ())
+ if name not in carried and name not in servers
+ }
+ if kept or servers:
+ config["mcp_servers"] = {**kept, **servers}
+ else:
+ config.pop("mcp_servers", None)
+ sources = ((source, set()), (built, _hermes_mcp_manifest(built)[2] if built else set()))
+ owned = _carry_hermes_mcp_env(home, config.get("mcp_servers", {}), sources)
+ (home / _HERMES_MCP_MANIFEST).write_text(
+ json.dumps({"origin": configured, "servers": sorted(servers), "env": owned}) + "\n",
+ encoding = "utf-8",
+ )
+
+
+def _hermes_env_key(line: str) -> str:
+ return line.strip().removeprefix("export ").partition("=")[0].strip()
+
+
+def _carry_hermes_mcp_env(home: Path, servers: dict, sources: tuple) -> list:
+ # Hermes fills ${VAR} in mcp_servers from HERMES_HOME/.env (hermes mcp add --auth bearer keeps tokens there): copy only those lines, verbatim, so Hermes parses them itself.
+ path = home / ".env"
+ try:
+ current = path.read_text(encoding = "utf-8").splitlines()
+ except (OSError, ValueError):
+ current = []
+ owned = _hermes_mcp_manifest(home)[2]
+ found = {_hermes_env_key(line) for line in current} - owned
+ wanted = set()
+ for ref in re.findall(r"\$\{([^}]+)\}", json.dumps(servers)):
+ ref = ref.strip()
+ wanted.add(ref[4:].strip() if ref.startswith("env:") else ref)
+ carried, local = [], set(found)
+ # A saved home's own copies are skipped so a key removed at the origin stays removed.
+ for source, skip in sources:
+ if source is None or source.resolve(strict = False) == home.resolve(strict = False):
+ continue
+ try:
+ lines = (source / ".env").read_text(encoding = "utf-8").splitlines()
+ except (OSError, ValueError):
+ continue
+ keys = {_hermes_env_key(line) for line in lines} & (wanted - found - skip)
+ carried += [line for line in lines if _hermes_env_key(line) in keys]
+ found |= keys
+ lines = [line for line in current if _hermes_env_key(line) in local] + carried
+ if lines != current:
+ if lines:
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+ with os.fdopen(fd, "w", encoding = "utf-8") as handle:
+ handle.write("\n".join(lines) + "\n")
+ else:
+ path.unlink(missing_ok = True)
+ return sorted(found - local)
+
+
def write_hermes_config(
base: str,
model: dict,
path: Path,
request_body: Optional[dict] = None,
+ keep_mcp_servers: bool = False,
) -> None:
import yaml
@@ -6026,6 +6138,8 @@ def write_hermes_config(
)
return
_set_hermes_provider(config, base, model, request_body)
+ if keep_mcp_servers:
+ _with_user_hermes_mcp_servers(config, path.parent)
text = yaml.safe_dump(config, sort_keys = False)
if not path.exists() or path.read_text(encoding = "utf-8") != text:
path.parent.mkdir(parents = True, exist_ok = True)
@@ -7109,20 +7223,29 @@ def _openclaw_app_target(max_tokens: Optional[int] = None) -> _AppTarget:
return _AppTarget("openclaw", "OpenClaw app", path, updates)
-def _hermes_app_target(request_body: Optional[dict] = None) -> _AppTarget:
- # Hermes Desktop follows the sticky active profile.
- home = Path.home() / ".hermes"
- if sys.platform == "win32":
+def _hermes_user_home(configured: str = "") -> Path:
+ if configured:
+ home = Path(configured).expanduser()
+ if home.parent.name == "profiles":
+ return home
+ elif sys.platform == "win32":
# Hermes' Windows default home (hermes_constants._get_platform_default_hermes_home).
local = os.environ.get("LOCALAPPDATA", "").strip()
home = (Path(local) if local else Path.home() / "AppData" / "Local") / "hermes"
+ else:
+ home = Path.home() / ".hermes"
try:
profile = (home / "active_profile").read_text(encoding = "utf-8").strip()
except OSError:
profile = ""
- path = home / "config.yaml"
if profile != "default" and re.fullmatch(r"[A-Za-z0-9_][A-Za-z0-9._-]*", profile):
- path = home / "profiles" / profile / "config.yaml"
+ return home / "profiles" / profile
+ return home
+
+
+def _hermes_app_target(request_body: Optional[dict] = None) -> _AppTarget:
+ # Hermes Desktop follows the sticky active profile.
+ path = _hermes_user_home() / "config.yaml"
def updates(text, path, base, key, entry):
settings: dict = {}
@@ -8187,7 +8310,13 @@ def hermes(
return
with _session_config("hermes", launch, persist = persist) as home:
# HERMES_HOME relocates hermes' whole home dir (config.yaml, sessions, state) like CODEX_HOME, so the user's ~/.hermes is left untouched for the session.
- write_hermes_config(base, entry, home / "config.yaml", server_options.request_body())
+ write_hermes_config(
+ base,
+ entry,
+ home / "config.yaml",
+ server_options.request_body(),
+ keep_mcp_servers = True,
+ )
env = {_HERMES_ENV_KEY: key, "HERMES_HOME": str(home)}
_run(base, entry, env, command, launch = launch, install_hint = install_hint)
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index b37c4c0e7be..385300c831e 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -7566,6 +7566,120 @@ def test_connect_hermes_no_launch(fake_studio, tmp_path):
assert not any(c[1].split("?")[0].endswith("/api/inference/status") for c in fake_studio)
+def test_hermes_keeps_the_users_mcp_servers(fake_studio, tmp_path, monkeypatch):
+ yaml = pytest.importorskip("yaml")
+ source_home = tmp_path / "user-hermes"
+ source_home.mkdir()
+ user_config = source_home / "config.yaml"
+ user_config.write_text(
+ "model:\n default: cloud-model\n"
+ "mcp_servers:\n"
+ " github:\n command: npx\n args: [-y, '@modelcontextprotocol/server-github']\n"
+ " docs:\n url: http://127.0.0.1:9000/mcp\n"
+ )
+ monkeypatch.setenv("HERMES_HOME", str(source_home))
+ home = tmp_path / "agents" / "hermes"
+
+ result = CliRunner().invoke(start.start_app, ["hermes", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ config = yaml.safe_load((home / "config.yaml").read_text())
+ assert config["mcp_servers"] == {
+ "github": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]},
+ "docs": {"url": "http://127.0.0.1:9000/mcp"},
+ }
+ assert config["model"]["default"] == MODEL["id"]
+
+ config["mcp_servers"]["local"] = {"command": "local-server"}
+ (home / "config.yaml").write_text(yaml.safe_dump(config))
+ user_config.write_text("mcp_servers:\n docs:\n url: http://127.0.0.1:9000/mcp\n")
+ result = CliRunner().invoke(start.start_app, ["hermes", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ config = yaml.safe_load((home / "config.yaml").read_text())
+ assert config["mcp_servers"] == {
+ "local": {"command": "local-server"},
+ "docs": {"url": "http://127.0.0.1:9000/mcp"},
+ }
+ assert user_config.read_text() == "mcp_servers:\n docs:\n url: http://127.0.0.1:9000/mcp\n"
+
+
+def test_hermes_mcp_servers_follow_the_origin_from_a_recipe_shell(
+ fake_studio, tmp_path, monkeypatch
+):
+ yaml = pytest.importorskip("yaml")
+ source_home = tmp_path / "user-hermes"
+ source_home.mkdir()
+ user_config = source_home / "config.yaml"
+ user_config.write_text("mcp_servers:\n docs:\n command: d\n")
+ monkeypatch.setenv("HERMES_HOME", str(source_home))
+ home = tmp_path / "agents" / "hermes"
+ assert CliRunner().invoke(start.start_app, ["hermes", "--no-launch"]).exit_code == 0
+
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ user_config.write_text("mcp_servers:\n github:\n command: g\n")
+ result = CliRunner().invoke(start.start_app, ["hermes", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ config = yaml.safe_load((home / "config.yaml").read_text())
+ assert config["mcp_servers"] == {"github": {"command": "g"}}
+
+
+def test_hermes_fresh_session_from_a_recipe_shell_keeps_saved_home_servers(
+ fake_studio, tmp_path, monkeypatch
+):
+ yaml = pytest.importorskip("yaml")
+ source_home = tmp_path / "user-hermes"
+ source_home.mkdir()
+ (source_home / "config.yaml").write_text("mcp_servers:\n docs:\n command: d\n")
+ monkeypatch.setenv("HERMES_HOME", str(source_home))
+ home = tmp_path / "agents" / "hermes"
+ assert CliRunner().invoke(start.start_app, ["hermes", "--no-launch"]).exit_code == 0
+ config = yaml.safe_load((home / "config.yaml").read_text())
+ config["mcp_servers"]["local"] = {"command": "l"}
+ (home / "config.yaml").write_text(yaml.safe_dump(config))
+
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ fresh = tmp_path / "session" / "config.yaml"
+ fresh.parent.mkdir()
+ start.write_hermes_config(BASE, MODEL, fresh, keep_mcp_servers = True)
+ assert yaml.safe_load(fresh.read_text())["mcp_servers"] == {
+ "local": {"command": "l"},
+ "docs": {"command": "d"},
+ }
+
+
+def test_hermes_relative_origin_survives_a_directory_change(fake_studio, tmp_path, monkeypatch):
+ yaml = pytest.importorskip("yaml")
+ (tmp_path / "user-hermes").mkdir()
+ (tmp_path / "user-hermes" / "config.yaml").write_text("mcp_servers:\n docs:\n command: d\n")
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setenv("HERMES_HOME", "user-hermes")
+ home = tmp_path / "agents" / "hermes"
+ assert CliRunner().invoke(start.start_app, ["hermes", "--no-launch"]).exit_code == 0
+
+ (tmp_path / "elsewhere").mkdir()
+ monkeypatch.chdir(tmp_path / "elsewhere")
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ result = CliRunner().invoke(start.start_app, ["hermes", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ config = yaml.safe_load((home / "config.yaml").read_text())
+ assert config["mcp_servers"] == {"docs": {"command": "d"}}
+
+
+def test_hermes_mcp_servers_follow_the_active_profile(fake_studio, tmp_path, monkeypatch):
+ yaml = pytest.importorskip("yaml")
+ root = tmp_path / "user-hermes"
+ profile = root / "profiles" / "work"
+ profile.mkdir(parents = True)
+ (root / "config.yaml").write_text("mcp_servers:\n personal:\n command: p\n")
+ (root / "active_profile").write_text("work\n")
+ (profile / "config.yaml").write_text("mcp_servers:\n work:\n command: w\n")
+ monkeypatch.setenv("HERMES_HOME", str(root))
+
+ result = CliRunner().invoke(start.start_app, ["hermes", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ config = yaml.safe_load((tmp_path / "agents" / "hermes" / "config.yaml").read_text())
+ assert config["mcp_servers"] == {"work": {"command": "w"}}
+
+
@pytest.mark.parametrize(("found", "warned"), [("v20.19.5", True), ("v22.19.0", False)])
def test_pi_warns_when_node_is_older_than_it_needs(monkeypatch, capsys, found, warned):
monkeypatch.setattr(start, "_which_with_install_dirs", lambda name: "/usr/bin/node")
@@ -12099,3 +12213,62 @@ def test_model_download_progress_counts_the_remote_base_of_a_local_adapter(monke
assert progress.downloaded_bytes == 2 * GiB
assert server.count("my-lora") == 0
+
+
+def test_hermes_carries_only_referenced_mcp_secrets_into_the_session_env(
+ fake_studio, tmp_path, monkeypatch
+):
+ pytest.importorskip("yaml")
+ source_home = tmp_path / "user-hermes"
+ source_home.mkdir()
+ (source_home / "config.yaml").write_text(
+ "mcp_servers:\n remote:\n url: https://mcp.example/mcp\n"
+ " headers:\n Authorization: Bearer ${MCP_REMOTE_API_KEY}\n"
+ " quoted:\n url: https://q.example/mcp\n headers: {X-Key: '${env:Q_KEY}'}\n"
+ )
+ quoted = 'export Q_KEY="a # b" # rotated'
+ (source_home / ".env").write_text(
+ f"OPENROUTER_API_KEY=not-for-the-session\nMCP_REMOTE_API_KEY=sekret\n{quoted}\n"
+ )
+ monkeypatch.setenv("HERMES_HOME", str(source_home))
+ home = tmp_path / "agents" / "hermes"
+ result = CliRunner().invoke(start.start_app, ["hermes", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ assert "sekret" not in result.output
+ assert (home / ".env").read_text() == f"MCP_REMOTE_API_KEY=sekret\n{quoted}\n"
+ if os.name != "nt":
+ assert (home / ".env").stat().st_mode & 0o777 == 0o600
+
+ # A key added in the saved home stays; a key the user dropped goes.
+ with (home / ".env").open("a") as handle:
+ handle.write("MCP_LOCAL_API_KEY=mine\n")
+ (source_home / ".env").write_text("MCP_REMOTE_API_KEY=rotated\n")
+ assert CliRunner().invoke(start.start_app, ["hermes", "--no-launch"]).exit_code == 0
+ assert (home / ".env").read_text() == "MCP_LOCAL_API_KEY=mine\nMCP_REMOTE_API_KEY=rotated\n"
+
+ # A fresh session from that recipe shell also gets the saved home's own server secrets.
+ config = (home / "config.yaml").read_text() + (
+ " local:\n url: https://l.example/mcp\n"
+ " headers: {Authorization: 'Bearer ${MCP_LOCAL_API_KEY}'}\n"
+ )
+ (home / "config.yaml").write_text(config)
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ fresh = tmp_path / "session"
+ fresh.mkdir()
+ start.write_hermes_config("http://x", MODEL, fresh / "config.yaml", keep_mcp_servers = True)
+ assert (fresh / ".env").read_text() == "MCP_REMOTE_API_KEY=rotated\nMCP_LOCAL_API_KEY=mine\n"
+
+ # A key removed at the origin is not revived from the saved home's copy.
+ (source_home / ".env").write_text("OTHER=1\n")
+ start.write_hermes_config("http://x", MODEL, fresh / "config.yaml", keep_mcp_servers = True)
+ assert (fresh / ".env").read_text() == "MCP_LOCAL_API_KEY=mine\n"
+
+ # A server kept in the saved home still gets a key it shares with a dropped origin server.
+ monkeypatch.setenv("HERMES_HOME", str(source_home))
+ (source_home / ".env").write_text("MCP_REMOTE_API_KEY=shared\n")
+ (source_home / "config.yaml").write_text("mcp_servers: {}\n")
+ (home / "config.yaml").write_text(
+ config.replace("${MCP_LOCAL_API_KEY}", "${MCP_REMOTE_API_KEY}")
+ )
+ assert CliRunner().invoke(start.start_app, ["hermes", "--no-launch"]).exit_code == 0
+ assert "MCP_REMOTE_API_KEY=shared" in (home / ".env").read_text().splitlines()