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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: keep Hermes MCP servers in unsloth start hermes (#16949)
Nilay4030f3fc66f8
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.pyindex 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(returnwith _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.pyindex 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(monkeassert progress.downloaded_bytes == 2 * GiBassert 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()