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.

unsloth start: fix Studio discovery, proxy, Hermes context, Claude hooks and Codex login (#14591)

Michael Hancb2590f395d8
diff --git a/README.md b/README.md
index 8db45e32240..6dd58c91710 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,7 @@ unsloth start claude --model unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL
| Hermes Agent | `unsloth start hermes` |
| Pi | `unsloth start pi` |
| OpenClaw | `unsloth start openclaw` |
+| Mistral Vibe | `unsloth start vibe` |
## 📥 Install
Unsloth can be used in three ways: **[Unsloth Desktop](https://unsloth.ai/download)**, the desktop app; **[Unsloth Studio](https://unsloth.ai/docs/new/studio/)**, the web UI; or **Unsloth Core**, the code based version.
diff --git a/unsloth_cli/__init__.py b/unsloth_cli/__init__.py
index 4236e5d98b7..fe5ac87f5b6 100644
--- a/unsloth_cli/__init__.py
+++ b/unsloth_cli/__init__.py
@@ -242,8 +242,8 @@ if not _windows_studio_mutation_entry:
app.add_typer(
start_app,
name = "start",
- help = "Start a coding agent (Claude, Codex, OpenClaw, OpenCode, Hermes, Pi, dsh, Vibe) "
- "against Unsloth.",
+ help = "Start a coding agent (Claude, Codex, OpenClaw, OpenCode, Hermes, Pi, dsh, Vibe, "
+ "VS Code) against Unsloth.",
)
app.add_typer(
mcp_app, name = "mcp", help = "Connect coding agents to the Unsloth Studio MCP server."
diff --git a/unsloth_cli/_inference.py b/unsloth_cli/_inference.py
index 13065d81bfa..2cc4f427d94 100644
--- a/unsloth_cli/_inference.py
+++ b/unsloth_cli/_inference.py
@@ -4,7 +4,6 @@
"""Model loading and streaming shared by `inference` and `chat`."""
import asyncio
-import itertools
import json
import os
import re
@@ -37,16 +36,12 @@ _MPI_ENV_PAIRS = (
("MV2_COMM_WORLD_RANK", "MV2_COMM_WORLD_SIZE"),
)
-# Built lazily; urllib stays function-local to match this module.
-_no_redirect_opener = None
+_openers: dict = {}
-def urlopen_no_redirect(request, timeout):
- """urlopen that errors on any redirect: following a 3xx would send a bearer
- token (or accept an identity proof) to a base we never vetted, letting a port
- squatter relay a real Unsloth's response."""
- global _no_redirect_opener
- if _no_redirect_opener is None:
+def _opener(follow_redirects: bool, loopback: bool):
+ key = (follow_redirects, loopback)
+ if key not in _openers:
import urllib.error
import urllib.request
@@ -56,8 +51,27 @@ def urlopen_no_redirect(request, timeout):
req.full_url, code, f"refusing redirect to {newurl}", headers, fp
)
- _no_redirect_opener = urllib.request.build_opener(_NoRedirect)
- return _no_redirect_opener.open(request, timeout = timeout)
+ # urllib proxies 127.0.0.1 unless no_proxy lists it, leaking the bearer key to http_proxy.
+ handlers = [urllib.request.ProxyHandler({})] if loopback else []
+ if not follow_redirects:
+ handlers.append(_NoRedirect)
+ _openers[key] = urllib.request.build_opener(*handlers)
+ return _openers[key]
+
+
+def urlopen_no_redirect(request, timeout):
+ """urlopen that errors on any redirect: following a 3xx would send a bearer
+ token (or accept an identity proof) to a base we never vetted, letting a port
+ squatter relay a real Unsloth's response."""
+ return _opener(False, is_loopback_url(request.full_url)).open(request, timeout = timeout)
+
+
+def urlopen_local(request, timeout):
+ """urllib.request.urlopen that never sends a loopback request through a proxy."""
+ if not is_loopback_url(request.full_url):
+ import urllib.request
+ return urllib.request.urlopen(request, timeout = timeout)
+ return _opener(True, True).open(request, timeout = timeout)
# /api/inference/load and /unload pad their body so a proxy cannot time a slow load out,
@@ -784,28 +798,31 @@ def _recorded_studio_bases(tried: list):
yield candidate
-def find_studio_server(timeout: float = 3.0) -> Optional[str]:
+def _answers_as_studio(base: str, timeout: float) -> bool:
import urllib.request
+ request = urllib.request.Request(f"{base}/api/health", headers = {"User-Agent": _USER_AGENT})
+ try:
+ with urlopen_local(request, timeout = timeout) as response:
+ # A live port is not Studio: a stranger answering every path would get our key.
+ body = json.loads(response.read(65536).decode() or "{}")
+ return body.get("service") == _STUDIO_SERVICE_MARKER
+ except Exception:
+ return False
+
+def find_studio_server(timeout: float = 3.0) -> Optional[str]:
base = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")
candidates = _loopback_candidate_bases(base)
- if not os.environ.get("UNSLOTH_STUDIO_URL"):
- candidates = itertools.chain(candidates, _recorded_studio_bases(candidates))
# Try the concrete loopback addresses in order and return the first that answers, so the rest of
# the flow talks to that exact address.
- for candidate in candidates:
- request = urllib.request.Request(
- f"{candidate}/api/health", headers = {"User-Agent": _USER_AGENT}
- )
- try:
- with urllib.request.urlopen(request, timeout = timeout) as response:
- # A live port is not Studio: a stranger answering every path would get our key.
- body = json.loads(response.read(65536).decode() or "{}")
- if body.get("service") == _STUDIO_SERVICE_MARKER:
- return candidate
- except Exception:
- continue
- return None
+ found = next((c for c in candidates if _answers_as_studio(c, timeout)), None)
+ if os.environ.get("UNSLOTH_STUDIO_URL"):
+ return found
+ recorded = list(_recorded_studio_bases(candidates))
+ # Another install may own the default port: prefer the server this install recorded.
+ if found is not None and (not recorded or verify_studio_identity(found, timeout)):
+ return found
+ return next((c for c in recorded if _answers_as_studio(c, timeout)), found)
def is_loopback_url(base: str) -> bool:
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index aec7ab3315e..54b6707bb68 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -43,6 +43,7 @@ from unsloth_cli._inference import (
is_loopback_url,
raise_for_deferred_error,
require_completed_padded_body,
+ urlopen_local,
urlopen_no_redirect,
verify_studio_identity,
)
@@ -58,7 +59,9 @@ _CODEX_ENV_KEY = "UNSLOTH_STUDIO_AUTH_TOKEN"
# Codex treats an SSE stream with no bytes for this long as lost, cancels it and reconnects. Its default is 300000 (5 minutes), measured against the WHOLE quiet period, and llama-server sends nothing at all while it processes the prompt. A local CPU host chews through a prompt at low tens of tokens a second and Codex's own preamble is several thousand tokens before the user has typed anything: 16.1 tok/s measured on a 2-core box means ~460s of silence for a ~7300-token first turn, so the default trips before the first token exists. The reconnect is worse than the wait, because llama-server hands the retry a different parallel slot whose KV cache shares no prefix, so each attempt restarts prompt processing from zero and the five retries can never converge. Observed as a request completing in exactly 300056ms with `Reconnecting... 1/5` and no turn ever finishing. 20 minutes here, sized to be longer than a slow local first turn rather than to any server-side budget: nothing here bounds generation, and a genuinely dead stream is still caught, just later.
_CODEX_STREAM_IDLE_TIMEOUT_MS = 1_200_000
_HERMES_ENV_KEY = "UNSLOTH_API_KEY"
-_HERMES_PROVIDER = "unsloth"
+# Not "unsloth": Hermes strips a `<provider>/` prefix, so unsloth/<repo> stops matching model.default.
+_HERMES_PROVIDER = "unsloth-studio"
+_HERMES_LEGACY_PROVIDER = "unsloth"
# 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 = (
@@ -709,7 +712,12 @@ _DSH_NO_PROFILE_ARGS = frozenset("-V --version plugin".split())
def _dsh_command(args: list[str], patch: Optional[str] = None) -> list[str]:
head = args[0] if args else ""
- if head in _DSH_LAUNCHER_ARGS or head.startswith(("--profile=", "--patch=")):
+ # The web app takes no positionals, so a leading bare word is a profile name (`dsh headless "task"`).
+ if (
+ head in _DSH_LAUNCHER_ARGS
+ or head.startswith(("--profile=", "--patch="))
+ or (head and not head.startswith("-"))
+ ):
command = ["dsh", *args]
else:
command = ["dsh", "web", *args]
@@ -1376,7 +1384,7 @@ def _load_model_with_progress(
def _studio_healthy(base: str, timeout: float = 3.0) -> bool:
request = urllib.request.Request(f"{base}/api/health", headers = {"User-Agent": _USER_AGENT})
try:
- with urllib.request.urlopen(request, timeout = timeout) as response:
+ with urlopen_local(request, timeout = timeout) as response:
return json.loads(response.read(65536).decode() or "{}").get("status") == "healthy"
except Exception:
return False
@@ -1718,10 +1726,15 @@ def _require_studio(
)
# Leave a bare GGUF repo's variant unset: the server's own quant preference already picks the best available (UD-Q4_K_XL for Unsloth uploads, else Q4_K_M) and falls back when that exact quant is missing, which forcing a fixed variant here would break.
return _start_studio_server(expected, model, load, server_options)
- model_hint = "" if model else " Pass --model to have it start one for you, or"
+ if not model:
+ hint = " Pass --model to have it start one for you, or start one with"
+ elif serve and not launch:
+ hint = " --no-launch never starts a server; drop it, or start one with"
+ else:
+ hint = " Start one with"
_fail(
- f"No running Unsloth server found at {expected}.{model_hint} start one with "
- "`unsloth studio`, or point UNSLOTH_STUDIO_URL at a remote server."
+ f"No running Unsloth server found at {expected}.{hint} `unsloth studio`, or point "
+ "UNSLOTH_STUDIO_URL at a remote server."
)
@@ -2481,8 +2494,16 @@ def _resolve_model(
f"Unsloth didn't report '{requested}' as loaded. Double-check the model "
"id, or load it from the model dropdown in the UI."
)
- resident = next((m for m in models if m.get("loaded") is not False), None)
+ loaded = [m for m in models if m.get("loaded") is not False]
+ # A speech or separation model is listed like any resident but carries a task: it cannot chat.
+ resident = next((m for m in loaded if m.get("task") is None), None)
if resident is None:
+ if loaded:
+ _fail(
+ f"Unsloth is serving only {loaded[0].get('id')}, a {loaded[0].get('task')} model "
+ "that cannot serve chat. Load a chat model from the model dropdown in the UI, or "
+ "pass --model <hf-id-or-path> to load one from here."
+ )
if _inference_status(base, key).get("yours") is False:
_fail(_OTHER_ACCOUNT_RESIDENT)
# An empty listing and one holding only unloaded entries are the same situation
@@ -3079,7 +3100,11 @@ def _require_gguf_for_agent(agent: _GgufAgent, base: str, key: str, model_id: st
_DYNAMIC_SECTIONS_FLAG = "--exclude-dynamic-system-prompt-sections"
-def _claude_settings_overlay(model_id: str, local_env: Optional[dict] = None) -> str:
+def _claude_settings_overlay(
+ model_id: str,
+ local_env: Optional[dict] = None,
+ user: Optional[dict] = None,
+) -> str:
# Command-tier pins beat user/project settings, which Claude applies after the process env.
settings_env = {name: "" for name in _CLAUDE_ENV_UNSET}
settings_env.update(local_env or {})
@@ -3091,14 +3116,51 @@ def _claude_settings_overlay(model_id: str, local_env: Optional[dict] = None) ->
)
return json.dumps(
{
- "env": settings_env,
+ **(user or {}),
+ "env": {**(user or {}).get("env", {}), **settings_env},
"availableModels": [model_id],
+ # A user's apiKeyHelper would still run and send its cloud key to Unsloth as x-api-key.
+ "apiKeyHelper": "",
}
)
-def _write_claude_settings(path: Path, model_id: str, local_env: dict) -> Path:
- overlay = _claude_settings_overlay(model_id, local_env)
+def _forwarded_claude_settings(args: list) -> tuple:
+ """(the forwarded --settings merged, args without them), or (None, args) when one is unreadable."""
+ separator = args.index("--") if "--" in args else len(args)
+ merged, remaining, index = {}, [], 0
+ while index < separator:
+ arg = args[index]
+ if arg == "--settings" and index + 1 < separator:
+ value, index = args[index + 1], index + 2
+ elif arg.startswith("--settings="):
+ value, index = arg.split("=", 1)[1], index + 1
+ else:
+ remaining.append(arg)
+ index += 1
+ continue
+ try:
+ text = (
+ value
+ if value.lstrip().startswith("{")
+ else Path(value).expanduser().read_text(encoding = "utf-8")
+ )
+ loaded = json.loads(text)
+ except (OSError, ValueError):
+ return None, args
+ if not isinstance(loaded, dict) or not isinstance(loaded.get("env", {}), dict):
+ return None, args
+ merged = {**merged, **loaded, "env": {**merged.get("env", {}), **loaded.get("env", {})}}
+ return merged, remaining + args[separator:]
+
+
+def _write_claude_settings(
+ path: Path,
+ model_id: str,
+ local_env: dict,
+ user: Optional[dict] = None,
+) -> Path:
+ overlay = _claude_settings_overlay(model_id, local_env, user)
digest = hashlib.sha256(overlay.encode("utf-8")).hexdigest()[:16]
settings = path / f"settings-{digest}.json"
_write_private_text(settings, overlay)
@@ -3566,7 +3628,11 @@ def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:
entries.append(source.name)
except OSError:
if source.is_file():
- shutil.copy2(source, target)
+ # Hard link, not copy: Codex rewrites auth.json in place, and a copy strands a rotated refresh token.
+ try:
+ os.link(source, target)
+ except OSError:
+ shutil.copy2(source, target)
entries.append(source.name)
elif source.is_dir():
if _create_directory_junction(source, target):
@@ -3574,6 +3640,14 @@ def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:
elif source.name in fallback_dirs:
shutil.copytree(source, target)
entries.append(source.name)
+ # Not signed in yet: a dangling link lands the first login in the user's home, not the overlay.
+ auth = source_home / "auth.json"
+ if not os.path.lexists(auth):
+ with contextlib.suppress(OSError):
+ source_home.mkdir(parents = True, exist_ok = True, mode = 0o700)
+ _remove_overlay_entry(overlay / auth.name)
+ (overlay / auth.name).symlink_to(auth)
+ entries.append(auth.name)
_write_private_json(
manifest_path,
@@ -3825,7 +3899,18 @@ sys.exit(0)
_CLAUDE_ROUTE_GATE_MATCHER = "Read|Grep|Glob|Bash|PowerShell|Monitor|NotebookRead|Agent|Task"
-def _claude_hook(gate: Path) -> dict:
+_CLAUDE_HOOK_ARGS_MIN_VERSION = (2, 1, 139)
+
+
+def _claude_hook(gate: Path, exec_form: bool = True) -> dict:
+ if exec_form:
+ # Exec form: without Git Bash, Windows runs shell-form hooks in PowerShell, which cannot parse them.
+ return {
+ "type": "command",
+ "command": sys.executable,
+ "args": ["-c", "import runpy,sys; runpy.run_path(sys.argv[1])", str(gate)],
+ "timeout": 10,
+ }
return {
"type": "command",
# Run through runpy rather than handing the path to the interpreter: a missing gate is then an ordinary traceback (exit 1, fails open) instead of exit 2, which Claude treats as a blocking error and would deny the tool in every mode. The path is base64'd because this string goes through a shell: a temp root holding $(..) or a backtick expands under sh, %VAR% under cmd, and the gate then silently fails open. base64's alphabet has no metacharacter in either.
@@ -3915,11 +4000,16 @@ def write_claude_subagent_plugin(path: Path, server_env: dict) -> Path:
stale.unlink(missing_ok = True)
else:
_write_private_text(gate, _CLAUDE_PLAN_GATE_SCRIPT)
- entries = [{"matcher": _CLAUDE_SUBAGENT_TOOL, "hooks": [_claude_hook(gate)]}]
+ version = _claude_version()
+ exec_form = version is None or version >= _CLAUDE_HOOK_ARGS_MIN_VERSION
+ entries = [{"matcher": _CLAUDE_SUBAGENT_TOOL, "hooks": [_claude_hook(gate, exec_form)]}]
if auto_route:
_write_private_text(route_gate, _CLAUDE_ROUTE_GATE_SCRIPT)
entries.append(
- {"matcher": _CLAUDE_ROUTE_GATE_MATCHER, "hooks": [_claude_hook(route_gate)]}
+ {
+ "matcher": _CLAUDE_ROUTE_GATE_MATCHER,
+ "hooks": [_claude_hook(route_gate, exec_form)],
+ }
)
_write_private_json(plugin / "hooks" / "hooks.json", {"hooks": {"PreToolUse": entries}})
skill = plugin / "skills" / "local-agent" / "SKILL.md"
@@ -4257,6 +4347,40 @@ def _pinned_raw_github_commit(source: str) -> Optional[str]:
return match.group(1).lower() if match else None
+# Pi needs node >=22.19.0; npm only warns, so it installs on Node 20.19 and then dies on load.
+_PI_MIN_NODE = (22, 19, 0)
+
+
+def _node_version() -> Optional[tuple]:
+ """Version of the `node` a launched npm shim resolves (`#!/usr/bin/env node`), or None."""
+ node = _which_with_install_dirs("node")
+ if node is None:
+ return None
+ try:
+ found = subprocess.run(
+ [node, "--version"],
+ capture_output = True,
+ text = True,
+ timeout = 10,
+ env = _probe_env(),
+ ).stdout
+ except (OSError, subprocess.SubprocessError):
+ return None
+ match = re.match(r"\s*v?(\d+)\.(\d+)\.(\d+)", found or "")
+ return tuple(int(part) for part in match.groups()) if match else None
+
+
+def _warn_if_node_older(agent: str, minimum: tuple, legacy_package: str) -> None:
+ found = _node_version()
+ if found is not None and found < minimum:
+ typer.echo(
+ f"Warning: {agent} needs Node.js {'.'.join(map(str, minimum))} or newer, but `node` "
+ f"here is {'.'.join(map(str, found))}. If it fails to start, upgrade Node.js, or "
+ f"install the older line with `npm install -g {legacy_package}`.",
+ err = True,
+ )
+
+
def _npm_executable() -> Optional[str]:
managed_node = _managed_node_tools()
if not (managed_node and managed_node[2]):
@@ -4696,6 +4820,12 @@ def _connect(
model = repo
if not load.gguf_variant:
load = load._replace(gguf_variant = variant)
+ elif load.gguf_variant.lower() != variant.lower():
+ typer.echo(
+ f"Warning: using --gguf-variant {load.gguf_variant} instead of the "
+ f":{variant} in --model.",
+ err = True,
+ )
base, server = _require_studio(
model,
load,
@@ -4703,6 +4833,10 @@ def _connect(
launch = launch,
server_options = server_options,
)
+ # The server resolves relative paths against its own cwd; only a local Studio shares our filesystem.
+ if model and server is None and is_loopback_url(base) and _is_model_path(model):
+ if os.path.exists(os.path.expanduser(model)) and verify_studio_identity(base):
+ model = os.path.abspath(os.path.expanduser(model))
try:
key = _agent_api_key(base, api_key, auto_started = server is not None)
connection = None if server is not None else _connection_entry(base, key, requested)
@@ -5371,6 +5505,12 @@ def _set_hermes_provider(
window = model.get("context_length") or model.get("max_context_length")
if window:
window = int(window)
+ # A --persist home keeps what an earlier run pinned for another window.
+ _subdict(config, "compression").pop("threshold_tokens", None)
+ stale = config.get("auxiliary")
+ stale = stale.get("compression") if isinstance(stale, dict) else None
+ if isinstance(stale, dict) and stale.get("context_length") == _HERMES_MIN_CONTEXT:
+ del stale["context_length"]
# Hermes auto-detects context from GET /v1/models, but OpenAI's schema has no context field, so it can fall back to a 256k default that overflows a small local model. Pin the real window (top-level model.context_length is the highest-priority override) and compact at 90% of it (Hermes defaults to 50%).
if window >= _HERMES_MIN_CONTEXT:
_subdict(config, "model")["context_length"] = window
@@ -5383,10 +5523,17 @@ def _set_hermes_provider(
# Current Hermes refuses a local server below its floor unless ollama_num_ctx claims it; context_length alone no longer passes.
_subdict(config, "model")["ollama_num_ctx"] = _HERMES_MIN_CONTEXT
threshold = round(0.9 * window / _HERMES_MIN_CONTEXT, 4)
- _subdict(config, "compression").update(enabled = True, threshold = threshold)
+ # Hermes raises thresholds under 0.75 below 512K; threshold_tokens is the cap it still honors.
+ _subdict(config, "compression").update(
+ enabled = True, threshold = threshold, threshold_tokens = int(0.9 * window)
+ )
auxiliary = _subdict(_subdict(config, "auxiliary"), "compression")
auxiliary["context_length"] = _HERMES_MIN_CONTEXT
- _subdict(config, "providers")[_HERMES_PROVIDER] = {
+ providers = _subdict(config, "providers")
+ legacy = providers.get(_HERMES_LEGACY_PROVIDER)
+ if isinstance(legacy, dict) and legacy.get("key_env") == _HERMES_ENV_KEY:
+ del providers[_HERMES_LEGACY_PROVIDER]
+ providers[_HERMES_PROVIDER] = {
"base_url": f"{base}/v1",
"api_mode": "openai",
"key_env": _HERMES_ENV_KEY,
@@ -5937,10 +6084,69 @@ def _parse_app_config(path: Path, text: Optional[str]) -> Optional[dict]:
_fail(f"Couldn't parse {path}, so it was left as is. Fix it and re-run.")
+_APP_DELETE = object()
+
+
+def _jsonc_members(clean: str, start: int) -> tuple:
+ """({key: (value_start, value_end)}, closing brace) for the object opening at clean[start]."""
+ decoder, space = json.JSONDecoder(), re.compile(r"\s*")
+ members, index = {}, space.match(clean, start + 1).end()
+ while clean[index] != "}":
+ key, index = decoder.raw_decode(clean, index)
+ value_start = space.match(clean, space.match(clean, index).end() + 1).end()
+ _, value_end = decoder.raw_decode(clean, value_start)
+ members[key] = (value_start, value_end)
+ index = space.match(clean, value_end).end()
+ if clean[index] == ",":
+ index = space.match(clean, index + 1).end()
+ return members, index
+
+
+def _splice_jsonc(text: str, keys: tuple, value) -> str:
+ """Set keys to value in JSONC text, touching only that member so comments elsewhere survive."""
+
+ def blank(match):
+ # Same-length blanking keeps every offset into the original text valid.
+ return match.group(1) or re.sub(r"[^\n]", " ", match.group(0))
+
+ clean = _JSONC_TRAILING_COMMA.sub(blank, _JSONC_COMMENT.sub(blank, text))
+ start, depth = re.compile(r"\s*").match(clean).end(), 0
+ for depth, key in enumerate(keys):
+ members, close = _jsonc_members(clean, start)
+ if key not in members:
+ break
+ value_start, value_end = members[key]
+ if depth == len(keys) - 1 or clean[value_start] != "{":
+ rendered = json.dumps(value, indent = 2, ensure_ascii = False)
+ rendered = rendered.replace("\n", "\n" + " " * (depth + 1))
+ return text[:value_start] + rendered + text[value_end:]
+ start = value_start
+ for key in reversed(keys[depth + 1 :]):
+ value = {key: value}
+ indent = " " * (depth + 1)
+ rendered = json.dumps(value, indent = 2, ensure_ascii = False).replace("\n", "\n" + indent)
+ member = f"{json.dumps(keys[depth])}: {rendered}"
+ last = len(clean[:close].rstrip())
+ if last != start + 1:
+ return text[:last] + f",\n{indent}{member}" + text[last:]
+ if text[last:close].strip():
+ return text[:last] + f"\n{indent}{member}" + text[last:]
+ return text[:last] + f"\n{indent}{member}\n" + " " * depth + text[close:]
+
+
def _set_app_values(text: Optional[str], path: Path, updates: list) -> Optional[str]:
config = _parse_app_config(path, text)
before = json.dumps(config, sort_keys = True)
for keys, value in updates:
+ if value is _APP_DELETE:
+ parent = functools.reduce(
+ lambda node, key: node.get(key) if isinstance(node, dict) else None,
+ keys[:-1],
+ config,
+ )
+ if isinstance(parent, dict):
+ parent.pop(keys[-1], None)
+ continue
parent = config
for depth, key in enumerate(keys[:-1]):
if parent.get(key) is None:
@@ -5954,6 +6160,13 @@ def _set_app_values(text: Optional[str], path: Path, updates: list) -> Optional[
if json.dumps(config, sort_keys = True) == before:
return text
if path.suffix != ".yaml":
+ candidate = text
+ with contextlib.suppress(Exception):
+ if candidate and candidate.strip():
+ for keys, value in updates:
+ candidate = _splice_jsonc(candidate, keys, value)
+ if _load_app_config(path, candidate) == config:
+ return candidate
return json.dumps(config, indent = 2, ensure_ascii = False) + "\n"
import yaml
@@ -6319,7 +6532,8 @@ def _codex_app_session(base: str, explicit_key: Optional[str], entry: dict) -> N
typer.echo(
f"The Codex app is on {entry['id']} from Unsloth at {base} until this command exits "
"(Ctrl+C). If the app was already open, quit and reopen it: it reads the model list "
- "only at startup."
+ "only at startup. If this command is killed instead, the next `unsloth start codex` "
+ "switches the app back."
)
_hold_codex_app(base)
finally:
@@ -6436,7 +6650,25 @@ def _hermes_app_target(request_body: Optional[dict] = None) -> _AppTarget:
# model.context_length only covers the default model, so a picked one reads its window here.
context = max(int(window), _HERMES_MIN_CONTEXT)
provider["models"] = {entry["id"]: {"context_length": context}}
- return [(("providers", _HERMES_PROVIDER), provider)]
+ changes = [(("providers", _HERMES_PROVIDER), provider)]
+ config = _parse_app_config(path, text) or {}
+ providers = config.get("providers")
+ legacy = providers.get(_HERMES_LEGACY_PROVIDER) if isinstance(providers, dict) else None
+ # Only the entry an earlier --app wrote: it points here and carries nothing of the user's.
+ if (
+ isinstance(legacy, dict)
+ and legacy.get("base_url") == provider["base_url"]
+ and set(legacy) <= {"base_url", "api_mode", "api_key", "models", "extra_body"}
+ ):
+ changes.append((("providers", _HERMES_LEGACY_PROVIDER), _APP_DELETE))
+ # A default the user picked in the app still names the old entry; move it along.
+ model = config.get("model")
+ if (
+ isinstance(model, dict)
+ and model.get("provider") == f"custom:{_HERMES_LEGACY_PROVIDER}"
+ ):
+ changes.append((("model", "provider"), f"custom:{_HERMES_PROVIDER}"))
+ return changes
return _AppTarget("hermes", "Hermes app", path, updates)
@@ -6823,13 +7055,15 @@ def claude(
env = _claude_local_env(base, key, entry, server_options.request_body())
# Claude Code auto-compacts against its native context window; the local env above supplies the loaded model's real window and a 90% threshold instead. --yolo (or its aliases) maps to Claude's own --dangerously-skip-permissions. IS_SANDBOX is left unset on purpose: Claude refuses bypass mode as root unless a sandbox is detected, and we do not want to falsely claim one on the user's host. claude keeps its history in ~/.claude/projects, which --settings/env never relocate, so a session already survives exit; resume it with `claude --continue` or `--resume <id>` passed through.
+ # Claude keeps only the last --settings, so a forwarded one is merged into ours instead of dropped.
+ user_settings, args = _forwarded_claude_settings(ctx.args)
with _session_config("claude", launch, persist = persist) as config:
- settings = _write_claude_settings(config, model_id, env)
+ settings = _write_claude_settings(config, model_id, env, user_settings)
command = _claude_local_command(
model_id,
_agent_config_path(settings, ["claude"]),
yolo,
- ctx.args,
+ args,
)
_run(
base,
@@ -7419,6 +7653,8 @@ def pi(
if as_subagent and not _PI_SUBAGENT_EXTENSION.is_file():
_fail(f"Missing Pi subagent extension: {_PI_SUBAGENT_EXTENSION}")
_require_agent_for_launch("pi", install_hint, launch)
+ if launch:
+ _warn_if_node_older("Pi", _PI_MIN_NODE, "@earendil-works/pi-coding-agent@legacy-node20")
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
diff --git a/unsloth_cli/tests/test_claude_plan_gate.py b/unsloth_cli/tests/test_claude_plan_gate.py
index 1340f09c7b5..c63d187576f 100644
--- a/unsloth_cli/tests/test_claude_plan_gate.py
+++ b/unsloth_cli/tests/test_claude_plan_gate.py
@@ -18,6 +18,24 @@ def _plugin(tmp_path):
return start.write_claude_subagent_plugin(tmp_path, {"UNSLOTH_CLAUDE_SUBAGENT_MODEL": "m"})
[email protected](params = ["exec", "shell"])
+def hook_form(request, monkeypatch):
+ # Claude Code before 2.1.139 has no exec form, so it gets the shell string.
+ version = start._CLAUDE_HOOK_ARGS_MIN_VERSION if request.param == "exec" else (2, 1, 100)
+ monkeypatch.setattr(start, "_claude_version", lambda: version)
+ return request.param
+
+
+def _run_hook(hook, payload):
+ if "args" in hook:
+ argv, shell = [hook["command"], *hook["args"]], False
+ else:
+ argv, shell = hook["command"], True
+ return subprocess.run(
+ argv, input = payload, shell = shell, capture_output = True, text = True, timeout = 60
+ )
+
+
def _run_gate(script, payload):
return subprocess.run(
[sys.executable, str(script)],
@@ -28,7 +46,7 @@ def _run_gate(script, payload):
)
-def test_plugin_registers_a_pretooluse_hook_on_the_editing_tool(tmp_path):
+def test_plugin_registers_a_pretooluse_hook_on_the_editing_tool(tmp_path, hook_form):
plugin = _plugin(tmp_path)
hooks = json.loads((plugin / "hooks" / "hooks.json").read_text())["hooks"]["PreToolUse"]
@@ -38,12 +56,16 @@ def test_plugin_registers_a_pretooluse_hook_on_the_editing_tool(tmp_path):
assert start._CLAUDE_SUBAGENT_PLAN_TOOL not in json.dumps(hooks)
[hook] = entry["hooks"]
assert hook["type"] == "command"
- assert sys.executable in hook["command"]
- assert f'"{sys.executable}"' in hook["command"]
- encoded = start._b64_path(plugin / "hooks" / "plan_gate.py")
- assert encoded in hook["command"]
- assert str(plugin / "hooks" / "plan_gate.py") not in hook["command"]
assert 0 < hook["timeout"] <= 30
+ gate = plugin / "hooks" / "plan_gate.py"
+ if hook_form == "exec":
+ assert hook["command"] == sys.executable
+ assert hook["args"][-1] == str(gate)
+ return
+ assert "args" not in hook
+ assert f'"{sys.executable}"' in hook["command"]
+ assert start._b64_path(gate) in hook["command"]
+ assert str(gate) not in hook["command"]
def test_gate_script_is_written_and_compiles(tmp_path):
@@ -109,52 +131,31 @@ def test_wsl_run_clears_a_gate_left_by_an_earlier_windows_run(tmp_path, monkeypa
assert not hooks.exists()
-def test_hook_command_survives_a_missing_gate_and_a_path_with_spaces(tmp_path):
+def test_hook_command_survives_a_missing_gate_and_a_path_with_spaces(tmp_path, hook_form):
# A missing gate must exit 1 (fails open), not 2 (denies the tool in every mode).
plugin = _plugin(tmp_path / "dir with space")
hook = json.loads((plugin / "hooks" / "hooks.json").read_text())
- command = hook["hooks"]["PreToolUse"][0]["hooks"][0]["command"]
+ hook = hook["hooks"]["PreToolUse"][0]["hooks"][0]
- denied = subprocess.run(
- command,
- input = json.dumps({"permission_mode": "plan"}),
- shell = True,
- capture_output = True,
- text = True,
- timeout = 30,
- )
+ denied = _run_hook(hook, json.dumps({"permission_mode": "plan"}))
assert denied.returncode == 0
assert json.loads(denied.stdout)["hookSpecificOutput"]["permissionDecision"] == "deny"
(plugin / "hooks" / "plan_gate.py").unlink()
- gone = subprocess.run(
- command,
- input = json.dumps({"permission_mode": "default"}),
- shell = True,
- capture_output = True,
- text = True,
- timeout = 30,
- )
+ gone = _run_hook(hook, json.dumps({"permission_mode": "default"}))
assert gone.returncode != 2, "exit 2 blocks the tool in every mode"
assert gone.stdout.strip() == ""
@pytest.mark.parametrize("hostile", ["sub$(echo X)", "tick`echo X`", "var$HOME", "pct%TEMP%pct"])
-def test_gate_survives_shell_metacharacters_in_its_path(tmp_path, hostile):
+def test_gate_survives_shell_metacharacters_in_its_path(tmp_path, hostile, hook_form):
# These expand under sh (or cmd, %VAR%) before Python sees the path.
plugin = _plugin(tmp_path / hostile)
- command = json.loads((plugin / "hooks" / "hooks.json").read_text())["hooks"]["PreToolUse"][0][
+ hook = json.loads((plugin / "hooks" / "hooks.json").read_text())["hooks"]["PreToolUse"][0][
"hooks"
- ][0]["command"]
+ ][0]
- denied = subprocess.run(
- command,
- input = json.dumps({"permission_mode": "plan"}),
- shell = True,
- capture_output = True,
- text = True,
- timeout = 60,
- )
+ denied = _run_hook(hook, json.dumps({"permission_mode": "plan"}))
assert denied.returncode == 0, denied.stderr
decision = json.loads(denied.stdout)["hookSpecificOutput"]["permissionDecision"]
diff --git a/unsloth_cli/tests/test_inference_chat.py b/unsloth_cli/tests/test_inference_chat.py
index 2c98d465150..ab8a628136c 100644
--- a/unsloth_cli/tests/test_inference_chat.py
+++ b/unsloth_cli/tests/test_inference_chat.py
@@ -1195,7 +1195,7 @@ def test_find_studio_server_none_when_not_running(monkeypatch):
def refuse(*a, **k):
raise OSError("connection refused")
- monkeypatch.setattr(urllib.request, "urlopen", refuse)
+ monkeypatch.setattr(_inference, "urlopen_local", refuse)
assert _inference.find_studio_server() is None
@@ -1220,7 +1220,7 @@ def test_find_studio_server_falls_back_to_a_recorded_studio_port(monkeypatch, tm
raise OSError("HTTP Error 404: File not found")
return _HealthResponse()
- monkeypatch.setattr(urllib.request, "urlopen", default_port_taken)
+ monkeypatch.setattr(_inference, "urlopen_local", default_port_taken)
assert _inference.find_studio_server() == "http://127.0.0.1:8889"
assert probed == ["http://127.0.0.1:8888/api/health", "http://127.0.0.1:8889/api/health"]
@@ -1254,7 +1254,7 @@ def test_find_studio_server_skips_a_recorded_pid_reused_by_another_process(monke
raise OSError("connection refused")
return _HealthResponse()
- monkeypatch.setattr(urllib.request, "urlopen", urlopen)
+ monkeypatch.setattr(_inference, "urlopen_local", urlopen)
assert _inference.find_studio_server() == "http://127.0.0.1:8889"
assert probed == ["http://127.0.0.1:8888/api/health", "http://127.0.0.1:8889/api/health"]
@@ -1279,7 +1279,7 @@ def test_find_studio_server_probes_a_recorded_port_on_the_family_it_bound(monkey
probed.append(request.full_url)
raise OSError("connection refused")
- monkeypatch.setattr(urllib.request, "urlopen", nothing_answers)
+ monkeypatch.setattr(_inference, "urlopen_local", nothing_answers)
assert _inference.find_studio_server() is None
assert probed == [
"http://127.0.0.1:8888/api/health",
@@ -1309,10 +1309,83 @@ def test_find_studio_server_keeps_looking_past_a_stranger_on_the_default_port(
return _HealthResponse(b'{"status": "healthy", "service": "some-other-app"}')
return _HealthResponse()
- monkeypatch.setattr(urllib.request, "urlopen", stranger_on_8888)
+ monkeypatch.setattr(_inference, "urlopen_local", stranger_on_8888)
assert _inference.find_studio_server() == "http://127.0.0.1:8889"
+def test_loopback_requests_bypass_an_exported_proxy(monkeypatch):
+ import http.server
+ import threading
+ import urllib.request
+
+ from unsloth_cli import _inference
+
+ seen = []
+
+ class Studio(http.server.BaseHTTPRequestHandler):
+ def do_GET(self):
+ seen.append(self.headers.get("Authorization"))
+ body = b'{"status": "healthy", "service": "Unsloth UI Backend"}'
+ self.send_response(200)
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def log_message(self, *a):
+ pass
+
+ server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Studio)
+ threading.Thread(target = server.serve_forever, daemon = True).start()
+ base = f"http://127.0.0.1:{server.server_address[1]}"
+ try:
+ for name in ("http_proxy", "HTTP_PROXY"):
+ monkeypatch.setenv(name, "http://127.0.0.1:9")
+ for name in ("no_proxy", "NO_PROXY"):
+ monkeypatch.delenv(name, raising = False)
+ monkeypatch.setenv("UNSLOTH_STUDIO_URL", base)
+ assert _inference.find_studio_server(timeout = 2) == base
+ request = urllib.request.Request(
+ f"{base}/api/health", headers = {"Authorization": "Bearer sk-unsloth-test"}
+ )
+ with _inference.urlopen_no_redirect(request, timeout = 2) as response:
+ assert response.status == 200
+ assert seen[-1] == "Bearer sk-unsloth-test"
+ finally:
+ server.shutdown()
+ server.server_close()
+
+
+def test_find_studio_server_prefers_its_own_recorded_studio_over_a_foreign_default(
+ monkeypatch, tmp_path
+):
+ import importlib
+ import urllib.request
+
+ from unsloth_cli import _inference
+
+ studio = importlib.import_module("unsloth_cli.commands.studio")
+ monkeypatch.delenv("UNSLOTH_STUDIO_URL", raising = False)
+ monkeypatch.setattr(studio, "STUDIO_HOME", tmp_path)
+ monkeypatch.setattr(studio, "_pid_alive", lambda pid: True)
+ monkeypatch.setattr(_inference, "urlopen_local", lambda *a, **k: _HealthResponse())
+ verified = []
+
+ def identity(base, timeout = 3.0):
+ verified.append(base)
+ return base.endswith(":8889")
+
+ monkeypatch.setattr(_inference, "verify_studio_identity", identity)
+ assert _inference.find_studio_server() == "http://127.0.0.1:8888"
+ assert verified == []
+
+ (tmp_path / "studio-8889-4343.pid").write_text("4343\n\n127.0.0.1", encoding = "utf-8")
+ assert _inference.find_studio_server() == "http://127.0.0.1:8889"
+ assert verified == ["http://127.0.0.1:8888"]
+
+ monkeypatch.setattr(_inference, "verify_studio_identity", lambda base, timeout = 3.0: True)
+ assert _inference.find_studio_server() == "http://127.0.0.1:8888"
+
+
def test_find_studio_server_prefers_ipv4_loopback_for_localhost(monkeypatch):
import socket
import urllib.request
@@ -1334,7 +1407,7 @@ def test_find_studio_server_prefers_ipv4_loopback_for_localhost(monkeypatch):
raise OSError("connection refused")
return _HealthResponse()
- monkeypatch.setattr(urllib.request, "urlopen", only_ipv4)
+ monkeypatch.setattr(_inference, "urlopen_local", only_ipv4)
assert _inference.find_studio_server() == "http://127.0.0.1:8888"
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index e701893625d..56d7b238f30 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -1108,6 +1108,39 @@ def test_write_codex_parent_overlay_refreshes_fallback_copies(tmp_path, monkeypa
assert (overlay / "history.jsonl").read_text() == "session state\n"
+def test_write_codex_parent_overlay_shares_a_token_refresh_without_symlinks(tmp_path, monkeypatch):
+ source = tmp_path / "user-codex"
+ source.mkdir()
+ (source / "auth.json").write_text('{"refresh_token": "rt-1"}')
+ monkeypatch.setenv("CODEX_HOME", str(source))
+
+ def deny_symlink(*args, **kwargs):
+ raise OSError(1314, "A required privilege is not held by the client")
+
+ monkeypatch.setattr(Path, "symlink_to", deny_symlink)
+ overlay = start.write_codex_parent_overlay(tmp_path / "session" / "parent")
+ # Codex rewrites auth.json in place (FileAuthStorage::save) after rotating the refresh token.
+ with open(overlay / "auth.json", "w") as handle:
+ handle.write('{"refresh_token": "rt-2"}')
+ shutil.rmtree(tmp_path / "session")
+ assert (source / "auth.json").read_text() == '{"refresh_token": "rt-2"}'
+
+
[email protected](os.name == "nt", reason = "needs symlink privilege")
[email protected]("home_exists", [False, True])
+def test_write_codex_parent_overlay_keeps_a_first_login(tmp_path, monkeypatch, home_exists):
+ source = tmp_path / "user-codex"
+ if home_exists:
+ source.mkdir()
+ (source / "config.toml").write_text('model = "gpt-5.5"\n')
+ monkeypatch.setenv("CODEX_HOME", str(source))
+ overlay = start.write_codex_parent_overlay(tmp_path / "session" / "parent")
+ with open(overlay / "auth.json", "w") as handle:
+ handle.write('{"tokens": "chatgpt"}')
+ shutil.rmtree(tmp_path / "session")
+ assert (source / "auth.json").read_text() == '{"tokens": "chatgpt"}'
+
+
def test_create_directory_junction_uses_windows_mklink(tmp_path, monkeypatch):
captured = {}
monkeypatch.setattr(start.os, "name", "nt")
@@ -1547,6 +1580,7 @@ def fake_studio(tmp_path, monkeypatch):
monkeypatch.setattr(start, "_key_cache_path", lambda: tmp_path / "agent_api_key.json")
monkeypatch.setattr(start, "_agents_config_root", lambda: tmp_path / "agents")
monkeypatch.setattr(start, "_require_agent_for_launch", lambda *args: None)
+ monkeypatch.setattr(start, "_node_version", lambda: None)
monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode", False))
# No `claude` on PATH, so _claude_flags never probes the real binary.
monkeypatch.setattr(start.shutil, "which", lambda _: None)
@@ -1666,10 +1700,24 @@ def test_connect_claude_session_settings_follow_forwarded_settings(fake_studio):
)
assert result.exit_code == 0, result.output
command = _launch_command(result.output)
- positions = [index for index, arg in enumerate(command) if arg == "--settings"]
- assert len(positions) == 2
- assert command[positions[0] + 1] == forwarded
- assert Path(command[positions[1] + 1]).name.startswith("settings-")
+ [position] = [index for index, arg in enumerate(command) if arg == "--settings"]
+ settings = json.loads(Path(command[position + 1]).read_text())
+ assert settings["env"]["CLAUDE_CODE_USE_FOUNDRY"] == ""
+ assert settings["env"]["ANTHROPIC_BASE_URL"] == BASE
+
+
+def test_connect_claude_merges_a_forwarded_settings_file(fake_studio, tmp_path):
+ user = tmp_path / "mine.json"
+ user.write_text(json.dumps({"statusLine": {"type": "command"}, "env": {"MY_VAR": "1"}}))
+ result = CliRunner().invoke(start.start_app, ["claude", "--no-launch", f"--settings={user}"])
+ assert result.exit_code == 0, result.output
+ command = _launch_command(result.output)
+ assert str(user) not in " ".join(command)
+ settings = json.loads(Path(command[command.index("--settings") + 1]).read_text())
+ assert settings["statusLine"] == {"type": "command"}
+ assert settings["env"]["MY_VAR"] == "1"
+ assert settings["availableModels"] == [MODEL["id"]]
+ assert settings["apiKeyHelper"] == ""
@pytest.mark.parametrize(
@@ -1694,8 +1742,8 @@ def test_connect_claude_session_settings_precede_subcommand(fake_studio, setting
for index, arg in enumerate(command)
if arg == "--settings" or arg.startswith("--settings=")
]
- assert len(settings_positions) == 2
- assert settings_positions[0] < settings_positions[1] < subcommand
+ assert len(settings_positions) == 1
+ assert settings_positions[0] < subcommand
def test_connect_claude_session_settings_precede_forwarded_delimiter(fake_studio):
@@ -1852,7 +1900,7 @@ def test_claude_auto_route_blocks_the_parents_own_file_and_shell_tools(fake_stud
assert route_gate["matcher"] == "Read|Grep|Glob|Bash|PowerShell|Monitor|NotebookRead|Agent|Task"
[hook] = route_gate["hooks"]
assert hook["type"] == "command"
- assert start._b64_path(plugin / "hooks" / "route_gate.py") in hook["command"]
+ assert hook["args"][-1] == str(plugin / "hooks" / "route_gate.py")
assert 0 < hook["timeout"] <= 30
payload = json.dumps({"tool_name": "Read", "tool_input": {"file_path": "about.txt"}})
for run in (
@@ -1864,7 +1912,11 @@ def test_claude_auto_route_blocks_the_parents_own_file_and_shell_tools(fake_stud
timeout = 30,
),
lambda: subprocess.run(
- hook["command"], input = payload, shell = True, capture_output = True, text = True, timeout = 30
+ [hook["command"], *hook["args"]],
+ input = payload,
+ capture_output = True,
+ text = True,
+ timeout = 30,
),
):
denied = run()
@@ -2968,6 +3020,47 @@ def test_resolve_model_without_request_rejects_unloaded_catalog(monkeypatch):
start._resolve_model(BASE, "sk-test", None)
+def test_resolve_model_without_request_skips_a_speech_model(monkeypatch, capsys):
+ speech = {"id": "unsloth/orpheus-3b-0.1-ft-GGUF", "task": "text-to-speech"}
+ listing = {"data": [speech, MODEL]}
+ monkeypatch.setattr(start, "_http_json", lambda *a, **k: listing)
+ assert start._resolve_model(BASE, "sk-test", None) == MODEL
+
+ listing["data"] = [speech]
+ with pytest.raises(typer.Exit):
+ start._resolve_model(BASE, "sk-test", None)
+ assert "cannot serve chat" in capsys.readouterr().err
+
+
+def test_connect_sends_a_running_server_the_users_absolute_path(fake_studio, tmp_path, monkeypatch):
+ (tmp_path / "foo.gguf").write_bytes(b"GGUF")
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setattr(
+ start,
+ "_load_model_with_progress",
+ lambda b, k, r, l, payload: (
+ fake_studio.state.update(models = [{"id": payload["model_path"]}])
+ or {"status": "loaded", "model": payload["model_path"]}
+ ),
+ )
+ _, _, entry = start._connect(None, "./foo.gguf")
+ assert entry["id"] == str(tmp_path / "foo.gguf")
+
+ monkeypatch.setattr(start, "verify_studio_identity", lambda base: False)
+ monkeypatch.setattr(start, "_agent_api_key", lambda *a, **k: "sk-unsloth-saved")
+ _, _, entry = start._connect(None, "./foo.gguf")
+ assert entry["id"] == "./foo.gguf"
+
+
+def test_no_launch_says_why_no_server_was_started(fake_studio, monkeypatch):
+ monkeypatch.setattr(start, "find_studio_server", lambda: None)
+ result = CliRunner().invoke(
+ start.start_app, ["claude", "--no-launch", "--model", "unsloth/Qwen3-8B-GGUF"]
+ )
+ assert result.exit_code == 1
+ assert "--no-launch never starts a server" in result.output
+
+
def test_resolve_model_remote_studio_does_not_casefold_attach(monkeypatch):
# Remotely the existence probe cannot see server paths, so a case variant must not attach.
calls = []
@@ -3722,7 +3815,7 @@ def _session_request_body(agent, root, output):
return config["providers"]["unsloth"]["models"][0].get("samplingParams")
if agent == "hermes":
config = yaml.safe_load((home / "config.yaml").read_text())
- return config["providers"]["unsloth"].get("extra_body")
+ return config["providers"]["unsloth-studio"].get("extra_body")
if agent == "openclaw":
config = json.loads((home / "openclaw.json").read_text())
models = config["agents"]["defaults"].get("models", {})
@@ -4216,6 +4309,7 @@ def test_connect_explicit_gguf_variant_wins_over_suffix(fake_studio):
],
)
assert result.exit_code == 0, result.output
+ assert "using --gguf-variant UD-Q4_K_XL instead of the :Q8_0" in result.output
loads = [c for c in fake_studio if c[1].endswith("/api/inference/load")]
assert loads == [
(
@@ -6767,13 +6861,13 @@ def test_write_hermes_config_fresh(hermes_config):
yaml = pytest.importorskip("yaml")
start.write_hermes_config(BASE, MODEL, hermes_config)
config = yaml.safe_load(hermes_config.read_text())
- assert config["model"]["provider"] == "custom:unsloth"
+ assert config["model"]["provider"] == "custom:unsloth-studio"
assert config["model"]["default"] == MODEL["id"]
assert config["model"]["api_mode"] == "openai"
assert config["model"]["context_length"] == MODEL["context_length"]
assert config["compression"] == {"enabled": True, "threshold": 0.9}
assert "auxiliary" not in config
- provider = config["providers"]["unsloth"]
+ provider = config["providers"]["unsloth-studio"]
assert provider["base_url"] == f"{BASE}/v1"
assert provider["api_mode"] == "openai"
assert provider["key_env"] == "UNSLOTH_API_KEY"
@@ -6787,11 +6881,43 @@ def test_write_hermes_config_small_window_claims_floor(hermes_config):
config = yaml.safe_load(hermes_config.read_text())
# 0.5625 = 0.9 * 40960 / 65536: 90% of the real window.
assert config["model"]["context_length"] == 65536
- assert config["compression"] == {"enabled": True, "threshold": 0.5625}
+ assert config["compression"] == {
+ "enabled": True,
+ "threshold": 0.5625,
+ "threshold_tokens": 36864,
+ }
assert config["auxiliary"]["compression"]["context_length"] == 65536
assert config["model"]["ollama_num_ctx"] == 65536
+def test_write_hermes_config_provider_name_is_not_an_unsloth_model_prefix(hermes_config):
+ yaml = pytest.importorskip("yaml")
+ hermes_config.write_text(
+ yaml.safe_dump(
+ {
+ "providers": {
+ "unsloth": {"base_url": f"{BASE}/v1", "key_env": "UNSLOTH_API_KEY"},
+ "mine": {"base_url": "http://example.test/v1"},
+ }
+ }
+ )
+ )
+ start.write_hermes_config(BASE, MODEL, hermes_config)
+ config = yaml.safe_load(hermes_config.read_text())
+ provider = config["model"]["provider"].removeprefix("custom:")
+ assert not MODEL["id"].startswith(f"{provider}/")
+ assert set(config["providers"]) == {provider, "mine"}
+
+
+def test_write_hermes_config_drops_small_window_pins_for_a_larger_reload(hermes_config):
+ yaml = pytest.importorskip("yaml")
+ start.write_hermes_config(BASE, {"id": "small", "context_length": 32768}, hermes_config)
+ start.write_hermes_config(BASE, MODEL, hermes_config)
+ config = yaml.safe_load(hermes_config.read_text())
+ assert config["compression"] == {"enabled": True, "threshold": 0.9}
+ assert "context_length" not in config["auxiliary"]["compression"]
+
+
def test_write_hermes_config_large_window_drops_claimed_num_ctx(hermes_config):
yaml = pytest.importorskip("yaml")
start.write_hermes_config(BASE, {"id": "small", "context_length": 40960}, hermes_config)
@@ -6821,9 +6947,9 @@ def test_write_hermes_config_preserves_and_idempotent(hermes_config):
config = yaml.safe_load(hermes_config.read_text())
assert config["terminal"] == {"backend": "local"}
assert config["model"]["temperature"] == 0.7
- assert config["model"]["provider"] == "custom:unsloth"
+ assert config["model"]["provider"] == "custom:unsloth-studio"
assert config["providers"]["openrouter"]["base_url"] == "https://openrouter.ai/api/v1"
- assert config["providers"]["unsloth"]["base_url"] == f"{BASE}/v1"
+ assert config["providers"]["unsloth-studio"]["base_url"] == f"{BASE}/v1"
before = hermes_config.read_text()
start.write_hermes_config(BASE, MODEL, hermes_config)
assert hermes_config.read_text() == before
@@ -6847,12 +6973,24 @@ def test_connect_hermes_no_launch(fake_studio, tmp_path):
_assert_env_set(result.output, "HERMES_HOME", str(home))
assert "hermes" in result.output
config = yaml.safe_load((home / "config.yaml").read_text())
- assert config["model"]["provider"] == "custom:unsloth"
- assert config["providers"]["unsloth"]["base_url"] == f"{BASE}/v1"
+ assert config["model"]["provider"] == "custom:unsloth-studio"
+ assert config["providers"]["unsloth-studio"]["base_url"] == f"{BASE}/v1"
assert config["model"]["default"] == MODEL["id"]
assert not any(c[1].split("?")[0].endswith("/api/inference/status") for c in fake_studio)
[email protected](("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")
+ monkeypatch.setattr(
+ start.subprocess, "run", lambda *a, **k: SimpleNamespace(stdout = found + "\n")
+ )
+ start._warn_if_node_older("Pi", start._PI_MIN_NODE, "pkg@legacy")
+ err = capsys.readouterr().err
+ assert ("needs Node.js 22.19.0" in err) is warned
+ assert ("pkg@legacy" in err) is warned
+
+
def test_write_pi_config_fresh(tmp_path):
path = tmp_path / ".pi" / "agent" / "models.json"
start.write_pi_config(BASE, "sk-unsloth-abc", MODEL, path)
@@ -7510,6 +7648,8 @@ def test_dsh_command_selects_web_only_for_app_arguments(args, expected):
),
(["-V"], ["dsh", "-V"]),
(["--version"], ["dsh", "--version"]),
+ (["headless", "fix the bug"], ["dsh", "headless", "--patch", "P", "fix the bug"]),
+ (["acp"], ["dsh", "acp", "--patch", "P"]),
],
)
def test_dsh_command_places_the_patch_where_dsh_parses_it(args, expected):
diff --git a/unsloth_cli/tests/test_start_app.py b/unsloth_cli/tests/test_start_app.py
index ef4f41a7e34..6aecf17da34 100644
--- a/unsloth_cli/tests/test_start_app.py
+++ b/unsloth_cli/tests/test_start_app.py
@@ -412,10 +412,36 @@ def test_opencode_app_reads_a_commented_jsonc(studio, monkeypatch):
result = CliRunner().invoke(start.start_app, ["opencode", "--app"])
assert result.exit_code == 0, result.output
- data = json.loads(config.read_text())
+ text = config.read_text()
+ assert "// mine" in text and "/* x */" in text
+ data = start._load_app_config(config, text)
assert (data["model"], data["theme"]) == ("openai/gpt-5.5", "a//b")
assert "unsloth-studio" in data["provider"]
+ assert CliRunner().invoke(start.start_app, ["opencode", "--app"]).exit_code == 0
+ assert config.read_text() == text
+
+
+ "text",
+ [
+ "{}",
+ "{\n // only a comment\n}\n",
+ '{\n "provider": {\n // keep\n "openai": {"x": 1},\n },\n}\n',
+ '{"provider": {"unsloth-studio": {"old": true}}, /* tail */ "model": "m"}',
+ ],
+)
+def test_set_app_values_keeps_jsonc_comments(tmp_path, text):
+ path = tmp_path / "opencode.jsonc"
+ updates = [(("provider", "unsloth-studio"), {"npm": "x", "models": {"a": {}}})]
+ out = start._set_app_values(text, path, updates)
+ expected = start._load_app_config(path, text)
+ expected.setdefault("provider", {})["unsloth-studio"] = updates[0][1]
+ assert start._load_app_config(path, out) == expected
+ for comment in ("// only a comment", "// keep", "/* tail */"):
+ assert (comment in out) is (comment in text)
+ assert start._set_app_values(out, path, updates) == out
+
def test_opencode_app_reenables_a_disabled_unsloth(studio, monkeypatch):
monkeypatch.delenv("XDG_CONFIG_HOME", raising = False)
@@ -439,7 +465,7 @@ def test_openclaw_app_reads_a_commented_config(studio):
result = CliRunner().invoke(start.start_app, ["openclaw", "--app"])
assert result.exit_code == 0, result.output
- data = json.loads(config.read_text())
+ data = start._load_app_config(config, config.read_text())
assert data["agents"]["defaults"] == {"model": "openai/gpt-5.5"}
assert data["models"]["providers"]["unsloth"]["apiKey"] == APP_KEY
@@ -470,6 +496,35 @@ def test_codex_app_owner_without_psutil(monkeypatch):
assert start._codex_app_owner_alive(owner) is True
+def test_hermes_app_replaces_the_provider_an_earlier_run_named_unsloth(studio):
+ yaml = pytest.importorskip("yaml")
+ config = start._hermes_app_target().path
+ config.parent.mkdir(parents = True, exist_ok = True)
+ legacy = {"base_url": f"{BASE}/v1", "api_mode": "openai", "api_key": "sk-unsloth-old"}
+ mine = {"base_url": "http://elsewhere.test/v1", "api_key": "k"}
+ config.write_text(
+ yaml.safe_dump(
+ {
+ "model": {"provider": "custom:unsloth", "default": "m"},
+ "providers": {"unsloth": legacy, "other": mine},
+ }
+ )
+ )
+
+ result = CliRunner().invoke(start.start_app, ["hermes", "--app"])
+
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(config.read_text())
+ assert set(data["providers"]) == {"unsloth-studio", "other"}
+ assert data["model"] == {"provider": "custom:unsloth-studio", "default": "m"}
+
+ providers = {"unsloth": {**mine, "base_url": f"{BASE}/v1", "headers": {"x": "1"}}}
+ config.write_text(yaml.safe_dump({"providers": providers}))
+ result = CliRunner().invoke(start.start_app, ["hermes", "--app"])
+ assert result.exit_code == 0, result.output
+ assert "unsloth" in yaml.safe_load(config.read_text())["providers"]
+
+
def test_hermes_app_adds_unsloth_to_the_active_profile(studio):
yaml = pytest.importorskip("yaml")
root = start._hermes_app_target().path.parent
@@ -488,7 +543,7 @@ def test_hermes_app_adds_unsloth_to_the_active_profile(studio):
data = yaml.safe_load(config.read_text())
assert data["model"] == {"default": "openrouter/kimi-k3", "provider": "openrouter"}
assert "compression" not in data
- provider = data["providers"]["unsloth"]
+ provider = data["providers"]["unsloth-studio"]
assert provider["api_key"] == APP_KEY
assert provider["base_url"] == f"{BASE}/v1"
assert "key_env" not in provider