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.

Let agent desktop apps use the model Unsloth is serving (#12582)

Nilaydd5131f769ed
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index 9ab5035a6e0..1529dc35e65 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -384,6 +384,27 @@ _AS_SUBAGENT_OPTION = typer.Option(
rich_help_panel = _PANEL_SESSION,
help = "Keep the coding agent's current model and add Unsloth as a local subagent.",
)
+_APP_OPTION = typer.Option(
+ False,
+ "--app",
+ rich_help_panel = _PANEL_SESSION,
+ help = (
+ "Add Unsloth to the agent's desktop app instead of starting the CLI: writes the "
+ "provider and its own API key into your config (backed up first) and leaves your "
+ "default model alone, so you pick Unsloth in the app's model picker. Re-run after "
+ "loading another model."
+ ),
+)
+_CODEX_APP_OPTION = typer.Option(
+ False,
+ "--app",
+ rich_help_panel = _PANEL_SESSION,
+ help = (
+ "Switch the Codex desktop app to Unsloth instead of starting the CLI, open it, and "
+ "switch it back when this command exits or Unsloth stops (the app only offers one "
+ "provider's models at a time)."
+ ),
+)
# Per-agent CLI flag for "run tools without prompting". OpenCode (native --auto is command-scoped, handled below) and OpenClaw (config-only) are absent from this prefix map.
_YOLO_COMMAND_FLAGS = {
@@ -3026,28 +3047,41 @@ def _claude_local_env(
return env
-def _merge_codex_config(existing: str, base: str) -> str:
+def _codex_provider_table(base: str, key: Optional[str] = None) -> str:
+ # The desktop app gets no shell env, so it needs the key itself rather than env_key.
+ auth = (
+ f"experimental_bearer_token = {json.dumps(key)}" if key else f'env_key = "{_CODEX_ENV_KEY}"'
+ )
+ return (
+ f"{_PROVIDER_HEADER}\n"
+ 'name = "Unsloth Studio"\n'
+ f"base_url = {json.dumps(base + '/v1')}\n"
+ f"{auth}\n"
+ 'wire_api = "responses"\n'
+ "requires_openai_auth = false\n"
+ f"stream_idle_timeout_ms = {_CODEX_STREAM_IDLE_TIMEOUT_MS}\n"
+ )
+
+
+_CODEX_PROVIDER_TABLES = (_PROVIDER_HEADER, _PROVIDER_HEADER[:-1] + ".")
+
+
+def _merge_codex_config(
+ existing: str,
+ base: str,
+ key: Optional[str] = None,
+) -> str:
chunks = re.split(r"(?m)^(?=\[)", existing) # preamble, then one chunk per table
- if not re.search(r"(?m)^\s*oss_provider\s*=", chunks[0]):
+ if key is None and not re.search(r"(?m)^\s*oss_provider\s*=", chunks[0]):
if chunks[0] and not chunks[0].endswith("\n"):
chunks[0] += "\n"
chunks[0] += f'oss_provider = "{_CODEX_PROFILE}"\n'
- # Drop the provider table and any stale [model_providers.unsloth_api.*] subtables.
- stale = (_PROVIDER_HEADER, _PROVIDER_HEADER[:-1] + ".")
- text = "".join(c for c in chunks if not c.startswith(stale))
+ text = "".join(c for c in chunks if not c.startswith(_CODEX_PROVIDER_TABLES))
if not text.endswith("\n"):
text += "\n"
if not text.endswith("\n\n"):
text += "\n"
- return text + (
- f"{_PROVIDER_HEADER}\n"
- 'name = "Unsloth Studio"\n'
- f"base_url = {json.dumps(base + '/v1')}\n"
- f'env_key = "{_CODEX_ENV_KEY}"\n'
- 'wire_api = "responses"\n'
- "requires_openai_auth = false\n"
- f"stream_idle_timeout_ms = {_CODEX_STREAM_IDLE_TIMEOUT_MS}\n"
- )
+ return text + _codex_provider_table(base, key)
# Keep custom-model behavior aligned with Codex's own unknown-model fallback. This Apache-2.0 prompt is copied from openai/codex rust-v0.144.0 models-manager/prompt.md.
@@ -3103,7 +3137,7 @@ def _codex_supports_patch_line_endings() -> bool:
return version is not None and version >= _CODEX_PATCH_LINE_ENDINGS_MIN_VERSION
-def _codex_model_catalog(model: dict) -> dict:
+def _codex_model_catalog(model: dict, visibility: str = "none") -> dict:
"""Return conservative metadata for an Unsloth model unknown to Codex's built-in catalog."""
model_id = model["id"]
window = model.get("context_length") or model.get("max_context_length")
@@ -3113,7 +3147,7 @@ def _codex_model_catalog(model: dict) -> dict:
"description": "Model served by Unsloth Studio",
"supported_reasoning_levels": [],
"shell_type": "default",
- "visibility": "none",
+ "visibility": visibility,
"supported_in_api": True,
"priority": 99,
"availability_nux": None,
@@ -4634,6 +4668,30 @@ def _studio_embedding_model(base: str, key: str) -> Optional[str]:
return name.strip()
+def _openclaw_provider(
+ base: str,
+ key: str,
+ model: dict,
+ max_tokens: Optional[int] = None,
+) -> dict:
+ # Unsloth is a generic OpenAI-compatible /v1 endpoint (the vLLM/LM Studio path).
+ provider_model = {"id": model["id"], "name": model["id"]}
+ window = model.get("context_length") or model.get("max_context_length")
+ if window:
+ window = int(window)
+ provider_model["contextWindow"] = window
+ # Unset, OpenClaw caps every reply at 8192 (DEFAULT_MODEL_MAX_TOKENS) whatever the window.
+ provider_model["maxTokens"] = _agent_output_limit(window, max_tokens)
+ elif max_tokens:
+ provider_model["maxTokens"] = max_tokens
+ return {
+ "baseUrl": f"{base}/v1",
+ "apiKey": key,
+ "api": "openai-completions",
+ "models": [provider_model],
+ }
+
+
def write_openclaw_config(
base: str,
key: str,
@@ -4654,24 +4712,9 @@ def write_openclaw_config(
)
return
before = json.dumps(config, sort_keys = True)
- # Unsloth is a generic OpenAI-compatible /v1 endpoint (the vLLM/LM Studio path).
- provider_model = {"id": model["id"], "name": model["id"]}
- window = model.get("context_length") or model.get("max_context_length")
- if window:
- window = int(window)
- provider_model["contextWindow"] = window
- # Unset, OpenClaw caps every reply at 8192 (DEFAULT_MODEL_MAX_TOKENS) whatever the window.
- provider_model["maxTokens"] = _agent_output_limit(window, max_tokens)
- elif max_tokens:
- provider_model["maxTokens"] = max_tokens
models = _subdict(config, "models")
models.setdefault("mode", "merge")
- _subdict(models, "providers")["unsloth"] = {
- "baseUrl": f"{base}/v1",
- "apiKey": key,
- "api": "openai-completions",
- "models": [provider_model],
- }
+ _subdict(models, "providers")["unsloth"] = _openclaw_provider(base, key, model, max_tokens)
# Memory search is on by default and defaults to openai, so a local session reaches OpenAI unless this block is written.
search = _subdict(_subdict(config, "memory"), "search")
if embedding_model:
@@ -4819,34 +4862,18 @@ def _opencode_output_env(model: dict, max_tokens: Optional[int]) -> dict:
return {_OPENCODE_OUTPUT_TOKEN_MAX_ENV: str(max(output, ceiling))}
-def write_opencode_config(
+def _opencode_provider(
base: str,
key: str,
model: dict,
- path: Path,
- yolo: bool = False,
- as_subagent: bool = False,
max_tokens: Optional[int] = None,
request_body: Optional[dict] = None,
) -> dict:
- config = _read_json_object(path)
- if config is None:
- typer.echo(
- f"Warning: couldn't parse {path} — add an '{_OPENCODE_PROVIDER}' provider "
- "there yourself, or move the file aside and re-run.",
- err = True,
- )
- return {}
- before = json.dumps(config, sort_keys = True)
- config.setdefault("$schema", "https://opencode.ai/config.json")
- # Keep the provider definition in this private session file. The launch path adjusts effective provider filters in the higher-priority inline overlay.
model_entry = {"name": model["id"]}
window = model.get("context_length") or model.get("max_context_length")
- reserved = None
if window:
window = int(window)
output = opencode_output_limit(window, max_tokens)
- reserved = opencode_compaction_reserved(window, output)
# Without a limit OpenCode assumes context 0 and never compacts. Without input it compacts at context - output and ignores compaction.reserved.
model_entry["limit"] = {"context": window, "input": window, "output": output}
provider_options = {"baseURL": f"{base}/v1", "apiKey": key}
@@ -4859,12 +4886,43 @@ def write_opencode_config(
if "temperature" in request_body:
model_entry["temperature"] = True
provider_options["body"] = request_body
- _subdict(config, "provider")[_OPENCODE_PROVIDER] = {
+ return {
"npm": "@ai-sdk/openai-compatible",
"name": "Unsloth Studio",
"options": provider_options,
"models": {model["id"]: model_entry},
}
+
+
+def write_opencode_config(
+ base: str,
+ key: str,
+ model: dict,
+ path: Path,
+ yolo: bool = False,
+ as_subagent: bool = False,
+ max_tokens: Optional[int] = None,
+ request_body: Optional[dict] = None,
+) -> dict:
+ config = _read_json_object(path)
+ if config is None:
+ typer.echo(
+ f"Warning: couldn't parse {path} — add an '{_OPENCODE_PROVIDER}' provider "
+ "there yourself, or move the file aside and re-run.",
+ err = True,
+ )
+ return {}
+ before = json.dumps(config, sort_keys = True)
+ config.setdefault("$schema", "https://opencode.ai/config.json")
+ window = model.get("context_length") or model.get("max_context_length")
+ reserved = None
+ if window:
+ window = int(window)
+ reserved = opencode_compaction_reserved(window, opencode_output_limit(window, max_tokens))
+ # Keep the provider definition in this private session file. The launch path adjusts effective provider filters in the higher-priority inline overlay.
+ _subdict(config, "provider")[_OPENCODE_PROVIDER] = _opencode_provider(
+ base, key, model, max_tokens, request_body
+ )
# Normal mode pins this as the session model. Subagent mode leaves the user's main/small models alone and exposes the local model to @unsloth and /models.
opencode_model = f"{_OPENCODE_PROVIDER}/{model['id']}"
if as_subagent:
@@ -4921,35 +4979,12 @@ def write_opencode_config(
return session_permission
-def write_hermes_config(
+def _set_hermes_provider(
+ config: dict,
base: str,
model: dict,
- path: Path,
request_body: Optional[dict] = None,
) -> None:
- import yaml
-
- config: dict = {}
- if path.exists():
- try:
- loaded = yaml.safe_load(path.read_text(encoding = "utf-8"))
- except (yaml.YAMLError, OSError):
- typer.echo(
- f"Warning: couldn't parse {path} — configure the custom endpoint "
- "there yourself, or move the file aside and re-run.",
- err = True,
- )
- return
- if isinstance(loaded, dict):
- config = loaded
- elif loaded is not None:
- # Non-empty, non-mapping YAML is a user-managed file; leave it.
- typer.echo(
- f"Warning: couldn't parse {path} — configure the custom endpoint "
- "there yourself, or move the file aside and re-run.",
- err = True,
- )
- return
# Hermes only reads the key for a NAMED custom provider (a bare `provider: custom` ignores it), so register it under providers.*.
_subdict(config, "model").update(
provider = f"custom:{_HERMES_PROVIDER}",
@@ -4962,10 +4997,14 @@ def write_hermes_config(
# 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
+ if config["model"].get("ollama_num_ctx") == _HERMES_MIN_CONTEXT:
+ del config["model"]["ollama_num_ctx"]
_subdict(config, "compression").update(enabled = True, threshold = 0.9)
else:
# Below Hermes' 64,000-token floor it refuses to initialize, so claim the floor and shrink the threshold so compaction still fires at 90% of the REAL window (the threshold is a fraction of the claimed context_length). The auxiliary override keeps the same floor check from rejecting the compression model mid-session.
_subdict(config, "model")["context_length"] = _HERMES_MIN_CONTEXT
+ # 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)
auxiliary = _subdict(_subdict(config, "auxiliary"), "compression")
@@ -4976,6 +5015,38 @@ def write_hermes_config(
"key_env": _HERMES_ENV_KEY,
**({"extra_body": request_body} if request_body else {}),
}
+
+
+def write_hermes_config(
+ base: str,
+ model: dict,
+ path: Path,
+ request_body: Optional[dict] = None,
+) -> None:
+ import yaml
+
+ config: dict = {}
+ if path.exists():
+ try:
+ loaded = yaml.safe_load(path.read_text(encoding = "utf-8"))
+ except (yaml.YAMLError, OSError):
+ typer.echo(
+ f"Warning: couldn't parse {path} — configure the custom endpoint "
+ "there yourself, or move the file aside and re-run.",
+ err = True,
+ )
+ return
+ if isinstance(loaded, dict):
+ config = loaded
+ elif loaded is not None:
+ # Non-empty, non-mapping YAML is a user-managed file; leave it.
+ typer.echo(
+ f"Warning: couldn't parse {path} — configure the custom endpoint "
+ "there yourself, or move the file aside and re-run.",
+ err = True,
+ )
+ return
+ _set_hermes_provider(config, base, model, request_body)
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)
@@ -5365,6 +5436,592 @@ def write_dsh_patch(
typer.echo(f"Updated {path}")
+class _AppTarget(NamedTuple):
+ agent: str
+ label: str
+ path: Path
+ updates: object = None
+
+
+def _app_state_path(agent: str, path: Optional[Path] = None) -> Path:
+ # One state per settings file, so another profile or config dir keeps its own backup and key.
+ name = (
+ agent if path is None else f"{agent}-{hashlib.sha256(str(path).encode()).hexdigest()[:12]}"
+ )
+ return _agents_config_root() / "app" / f"{name}.json"
+
+
+def _read_app_file(path: Path) -> Optional[str]:
+ if path.is_symlink():
+ _fail(
+ f"{path} is a symlink, so Unsloth won't rewrite it. Replace the link with a "
+ "plain file and re-run, or add the Unsloth provider there yourself."
+ )
+ try:
+ fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+ except FileNotFoundError:
+ return None
+ with open(fd, encoding = "utf-8", newline = "") as handle:
+ return handle.read()
+
+
+def _app_file_mode(path: Path) -> Optional[int]:
+ try:
+ return path.stat().st_mode & 0o777
+ except FileNotFoundError:
+ return None
+
+
+def _write_app_file(path: Path, text: str) -> None:
+ # Never world-readable, even briefly, and the rename replaces a planted symlink instead of following it.
+ path.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
+ fd, temp = tempfile.mkstemp(prefix = f".{path.name}.", dir = path.parent)
+ try:
+ with open(fd, "w", encoding = "utf-8", newline = "") as handle:
+ handle.write(text)
+ handle.flush()
+ os.fsync(handle.fileno())
+ os.replace(temp, path)
+ except BaseException:
+ with contextlib.suppress(OSError):
+ os.unlink(temp)
+ raise
+
+
+_JSONC_COMMENT = re.compile(r'("(?:\\.|[^"\\])*")|//[^\n]*|/\*.*?\*/', re.S)
+_JSONC_TRAILING_COMMA = re.compile(r'("(?:\\.|[^"\\])*")|,(?=\s*[\]}])')
+
+
+def _load_app_config(path: Path, text: Optional[str]) -> Optional[dict]:
+ if text is None or not text.strip():
+ return {}
+ if path.suffix == ".toml":
+ try:
+ import tomllib # novermin
+ except ImportError:
+ try:
+ import tomli as tomllib
+ except ImportError:
+ return None
+ data = tomllib.loads(text)
+ elif path.suffix == ".yaml":
+ import yaml
+ data = yaml.safe_load(text)
+ else:
+ # OpenCode reads JSONC and OpenClaw JSON5, so accept comments and trailing commas in either.
+ text = _JSONC_COMMENT.sub(lambda m: m.group(1) or "", text)
+ data = json.loads(_JSONC_TRAILING_COMMA.sub(lambda m: m.group(1) or "", text))
+ if not isinstance(data, dict):
+ raise ValueError("not a settings object")
+ return data
+
+
+def _parse_app_config(path: Path, text: Optional[str]) -> Optional[dict]:
+ try:
+ return _load_app_config(path, text)
+ except Exception:
+ _fail(f"Couldn't parse {path}, so it was left as is. Fix it and re-run.")
+
+
+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:
+ parent = config
+ for depth, key in enumerate(keys[:-1]):
+ if parent.get(key) is None:
+ parent[key] = {}
+ elif not isinstance(parent[key], dict):
+ _fail(
+ f"{'.'.join(keys[: depth + 1])} in {path} isn't a table, so it was left as is."
+ )
+ parent = parent[key]
+ parent[keys[-1]] = value
+ if json.dumps(config, sort_keys = True) == before:
+ return text
+ if path.suffix != ".yaml":
+ return json.dumps(config, indent = 2, ensure_ascii = False) + "\n"
+ import yaml
+
+ # Rewrite only the touched top-level blocks so the rest of the file keeps its comments.
+ candidate = text or ""
+ for top in dict.fromkeys(keys[0] for keys, _ in updates):
+ block = yaml.safe_dump({top: config[top]}, sort_keys = False, allow_unicode = True)
+ match = re.search(rf"(?m)^{re.escape(top)}:[^\n]*\n(?:[ \t]+[^\n]*\n)*", candidate)
+ if match:
+ candidate = candidate[: match.start()] + block + candidate[match.end() :]
+ else:
+ candidate += ("\n" if candidate and not candidate.endswith("\n") else "") + block
+ with contextlib.suppress(Exception):
+ if _load_app_config(path, candidate) == config:
+ return candidate
+ return yaml.safe_dump(config, sort_keys = False, allow_unicode = True)
+
+
+def _set_toml_key(text: str, name: str, line: str) -> tuple:
+ chunks = re.split(r"(?m)^(?=\[)", text)
+ match = re.search(rf"(?m)^[ \t]*{name}[ \t]*=[^\r\n]*", chunks[0])
+ if match is None:
+ return f"{line}\n{text}", None
+ chunks[0] = chunks[0][: match.start()] + line + chunks[0][match.end() :]
+ return "".join(chunks), match.group(0)
+
+
+def _unset_toml_key(text: str, name: str, line: str, previous: Optional[str]) -> Optional[str]:
+ chunks = re.split(r"(?m)^(?=\[)", text)
+ match = re.search(rf"(?m)^[ \t]*{name}[ \t]*=([^\r\n]*)(\r?\n)?", chunks[0])
+ if match is None or match.group(0).strip() != line:
+ return None
+ restored = "" if previous is None else previous + (match.group(2) or "")
+ chunks[0] = chunks[0][: match.start()] + restored + chunks[0][match.end() :]
+ return "".join(chunks)
+
+
+def _same_app_config(path: Path, text: str, other: str) -> bool:
+ if text.strip() == other.strip():
+ return True
+ try:
+ parsed = _load_app_config(path, text)
+ return parsed is not None and parsed == _load_app_config(path, other)
+ except Exception:
+ return False
+
+
+def _revoke_app_key(base: str, key_id: object) -> bool:
+ if not is_loopback_url(base) or not verify_studio_identity(base):
+ return False
+ token = _studio_token()
+ if token is None:
+ return False
+ try:
+ _http_json("DELETE", f"{base}/api/auth/api-keys/{int(key_id)}", token)
+ except urllib.error.HTTPError as exc:
+ return exc.code == 404
+ except (urllib.error.URLError, TimeoutError, ValueError):
+ return False
+ return True
+
+
+def _app_api_key(target: _AppTarget, base: str, explicit: Optional[str], state: dict) -> tuple:
+ if explicit:
+ return explicit, None
+ previous = state.get("key")
+ if (
+ previous
+ and state.get("key_id") is not None
+ and state.get("base") == base
+ and _key_accepted(base, previous)
+ ):
+ return previous, state["key_id"]
+ token = _studio_token() if verify_studio_identity(base) else None
+ if token is None:
+ _fail(
+ f"Couldn't create an API key for the {target.label} automatically. Create one "
+ "in Unsloth → Settings → API and pass it with --api-key."
+ )
+ answer = _http_json(
+ "POST",
+ f"{base}/api/auth/api-keys",
+ token,
+ {"name": target.label},
+ error = "Couldn't create an API key",
+ )
+ return answer["key"], answer["api_key"]["id"]
+
+
+def _open_app_config(target: _AppTarget, base: str, explicit_key: Optional[str]) -> tuple:
+ if not is_loopback_url(base) and not explicit_key:
+ _fail(
+ f"{base} isn't on this machine. --app saves the key in your {target.label} "
+ "config, so pass the key for that server with --api-key."
+ )
+ state_path = _app_state_path(target.agent, None if target.agent == "codex" else target.path)
+ state = _read_json_object(state_path) or {}
+ if state.get("path") != str(target.path):
+ state = {}
+ text = _read_app_file(target.path)
+ _parse_app_config(target.path, text)
+ key, key_id = _app_api_key(target, base, explicit_key, state)
+ return state_path, state, text, key, key_id
+
+
+def _save_app_config(
+ target: _AppTarget,
+ state_path: Path,
+ state: dict,
+ new_state: dict,
+ text: Optional[str],
+ new_text: str,
+) -> None:
+ new_state["backup"] = state.get("backup")
+ if text is not None and not state:
+ backup = target.path.with_name(target.path.name + ".unsloth-backup")
+ _write_app_file(backup, text)
+ new_state["backup"] = str(backup)
+ typer.echo(f"Backed up {target.path} to {backup}")
+ _write_private_json(state_path, new_state)
+ if new_text != text:
+ _write_app_file(target.path, new_text)
+ typer.echo(f"Updated {target.path}")
+ if state.get("key_id") is not None and state.get("key") != new_state["key"]:
+ _revoke_app_key(state["base"], state["key_id"])
+
+
+def _app_server_notice(base: str) -> None:
+ if _keep_auto_served():
+ typer.echo(f"Unsloth Studio is still running at {base}; the app needs it running.")
+ typer.echo("Stop it with: unsloth studio stop")
+
+
+def _revoke_new_app_key(base: str, key_id: object, state: dict) -> None:
+ # A key minted for a setup that then failed would otherwise stay live and unreachable.
+ if key_id is not None and key_id != state.get("key_id"):
+ _revoke_app_key(base, key_id)
+
+
+def _add_app_provider(
+ target: _AppTarget, base: str, explicit_key: Optional[str], entry: dict
+) -> None:
+ state, key_id = {}, None
+ try:
+ state_path, state, text, key, key_id = _open_app_config(target, base, explicit_key)
+ new_text = _set_app_values(
+ text, target.path, target.updates(text, target.path, base, key, entry)
+ )
+ new_state = {"path": str(target.path), "base": base, "key": key, "key_id": key_id}
+ _save_app_config(target, state_path, state, new_state, text, new_text)
+ except BaseException:
+ _revoke_new_app_key(base, key_id, state)
+ _shutdown_auto_served()
+ raise
+ typer.echo(
+ f"Added {entry['id']} from Unsloth at {base} to the {target.label}. Your default "
+ "model is unchanged: pick Unsloth in the app's model picker (restart the app if it "
+ "is open)."
+ )
+ if key_id is not None:
+ typer.echo(
+ f"It uses its own API key, '{target.label}', which you can revoke in "
+ "Unsloth → Settings → API."
+ )
+ typer.echo(f"After loading another model, re-run: unsloth start {target.agent} --app")
+ _app_server_notice(base)
+
+
+_CODEX_APP_CATALOG = "unsloth-model-catalog.json"
+
+
+def _codex_app_lines(model_id: str) -> dict:
+ return {
+ "model_provider": f'model_provider = "{_CODEX_PROFILE}"',
+ "model": f"model = {json.dumps(model_id)}",
+ "model_catalog_json": f"model_catalog_json = {json.dumps(_CODEX_APP_CATALOG)}",
+ }
+
+
+def _codex_app_build(text: Optional[str], base: str, key: str, entry: dict, previous) -> tuple:
+ previous = dict(previous or {})
+ tables = [
+ c for c in re.split(r"(?m)^(?=\[)", text or "") if c.startswith(_CODEX_PROVIDER_TABLES)
+ ]
+ previous.setdefault("table", "".join(tables) or None)
+ merged = _merge_codex_config(text or "", base, key)
+ for name, line in _codex_app_lines(entry["id"]).items():
+ merged, old = _set_toml_key(merged, name, line)
+ previous.setdefault(name, old)
+ return merged, previous
+
+
+def _codex_app_restore(text: str, state: dict) -> tuple:
+ skipped = []
+ chunks = re.split(r"(?m)^(?=\[)", text)
+ ours = _codex_provider_table(state["base"], state["key"]).strip()
+
+ def is_ours(chunk: str) -> bool:
+ # An editor on Windows may have rewritten the file with CRLF line endings.
+ return chunk.replace("\r\n", "\n").strip() == ours
+
+ if any(is_ours(chunk) for chunk in chunks):
+ table = state["previous"].get("table") or ""
+ text = "".join(table if is_ours(chunk) else chunk for chunk in chunks)
+ else:
+ skipped.append(_PROVIDER_HEADER)
+ for name, line in _codex_app_lines(state["model"]).items():
+ restored = _unset_toml_key(text, name, line, state["previous"].get(name))
+ if restored is None:
+ skipped.append(name)
+ else:
+ text = restored
+ return text, skipped
+
+
+def _codex_app_target() -> _AppTarget:
+ # The desktop app is opened from the Dock or Start menu, so it never sees CODEX_HOME.
+ path = _codex_source_home(ignore_configured = True) / "config.toml"
+ return _AppTarget("codex", "Codex app", path)
+
+
+_CODEX_APP_HEALTH_INTERVAL_S = 5.0
+_CODEX_APP_HEALTH_MISSES = 3
+
+
+def _codex_app_owner() -> dict:
+ try:
+ import psutil
+ except ImportError:
+ return {"pid": os.getpid(), "started": None}
+ return {"pid": os.getpid(), "started": psutil.Process().create_time()}
+
+
+def _codex_app_owner_alive(owner: object) -> bool:
+ try:
+ pid = int(owner["pid"])
+ if owner["started"] is None:
+ # psutil is optional, so fall back to the PID alone.
+ from unsloth_cli.commands.studio import _pid_alive
+ return _pid_alive(pid)
+ import psutil
+
+ return abs(psutil.Process(pid).create_time() - float(owner["started"])) < 1.0
+ except Exception:
+ return False
+
+
+def _switch_codex_app_back(state_path: Path, state: dict) -> list:
+ path = Path(state["path"])
+ text = _read_app_file(path)
+ skipped = []
+ if text is not None:
+ new_text, skipped = _codex_app_restore(text, state)
+ backup = Path(state["backup"]) if state.get("backup") else None
+ original = _read_app_file(backup) if backup else None
+ if original is not None and _same_app_config(path, new_text, original):
+ new_text = original
+ if state.get("created") and _same_app_config(path, new_text, ""):
+ path.unlink()
+ elif new_text != text:
+ _write_app_file(path, new_text)
+ if original is not None and new_text == original:
+ if state.get("mode") is not None:
+ os.chmod(path, state["mode"])
+ backup.unlink(missing_ok = True)
+ if "model_catalog_json" not in skipped:
+ path.with_name(_CODEX_APP_CATALOG).unlink(missing_ok = True)
+ revoked = state.get("key_id") is None or _revoke_app_key(state.get("base", ""), state["key_id"])
+ state_path.unlink(missing_ok = True)
+ notes = [
+ f"Left {name} in {path} as is: it changed while Codex was on Unsloth." for name in skipped
+ ]
+ if not revoked:
+ notes.append(
+ "Couldn't reach Unsloth to revoke the app's key; delete 'Codex app' in "
+ "Unsloth → Settings → API."
+ )
+ return notes
+
+
+def _recover_codex_app() -> Optional[dict]:
+ state_path = _app_state_path("codex")
+ state = _read_json_object(state_path) or {}
+ if not state.get("path"):
+ return None
+ if _codex_app_owner_alive(state.get("owner")):
+ return state
+ notes = _switch_codex_app_back(state_path, state)
+ typer.echo(
+ "Switched the Codex app back from an earlier `unsloth start codex --app` that did not "
+ "exit cleanly."
+ )
+ for note in notes:
+ typer.echo(note)
+ return None
+
+
+def _open_codex_app() -> None:
+ if sys.platform == "darwin":
+ with contextlib.suppress(OSError):
+ if (
+ subprocess.run(["open", "-b", "com.openai.codex"], capture_output = True).returncode
+ == 0
+ ):
+ return
+ typer.echo("Open the Codex app now.")
+
+
+def _hold_codex_app(base: str) -> None:
+ def stop(signum, frame):
+ raise KeyboardInterrupt
+
+ previous = {}
+ for name in ("SIGTERM", "SIGHUP"):
+ if hasattr(signal, name):
+ previous[getattr(signal, name)] = signal.signal(getattr(signal, name), stop)
+ try:
+ misses = 0
+ while misses < _CODEX_APP_HEALTH_MISSES:
+ time.sleep(_CODEX_APP_HEALTH_INTERVAL_S)
+ misses = 0 if _studio_healthy(base) else misses + 1
+ typer.echo(f"Unsloth at {base} stopped answering.")
+ except KeyboardInterrupt:
+ pass
+ finally:
+ for number, handler in previous.items():
+ signal.signal(number, handler)
+
+
+def _codex_app_session(base: str, explicit_key: Optional[str], entry: dict) -> None:
+ target = _codex_app_target()
+ catalog = target.path.with_name(_CODEX_APP_CATALOG)
+ state, key_id = {}, None
+ try:
+ state_path, state, text, key, key_id = _open_app_config(target, base, explicit_key)
+ new_text, previous = _codex_app_build(text, base, key, entry, None)
+ _parse_app_config(target.path, new_text)
+ # The Codex app lists only the active provider's catalog, so this is what makes the model pickable.
+ _write_app_file(catalog, json.dumps(_codex_model_catalog(entry, "list"), indent = 2) + "\n")
+ new_state = {
+ "path": str(target.path),
+ "base": base,
+ "model": entry["id"],
+ "key": key,
+ "key_id": key_id,
+ "owner": _codex_app_owner(),
+ "created": text is None,
+ "mode": _app_file_mode(target.path),
+ "previous": previous,
+ }
+ _save_app_config(target, state_path, {}, new_state, text, new_text)
+ except BaseException:
+ _revoke_new_app_key(base, key_id, state)
+ _shutdown_auto_served()
+ raise
+ try:
+ _open_codex_app()
+ 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."
+ )
+ _hold_codex_app(base)
+ finally:
+ # A second Ctrl+C must not cut the switch back short.
+ previous_sigint = signal.signal(signal.SIGINT, signal.SIG_IGN)
+ try:
+ notes = _switch_codex_app_back(state_path, new_state)
+ _shutdown_auto_served()
+ # After SIGHUP the terminal may be gone; the switch back has already happened.
+ with contextlib.suppress(OSError):
+ typer.echo("Switched the Codex app back; restart it if a window is still open.")
+ for note in notes:
+ typer.echo(note)
+ finally:
+ signal.signal(signal.SIGINT, previous_sigint)
+
+
+def _check_app_flags(
+ requested: bool,
+ args: list,
+ as_subagent: bool = False,
+) -> None:
+ if requested and (args or as_subagent):
+ _fail("--app sets up the desktop app, so it takes no agent arguments or --as-subagent.")
+
+
+def _opencode_app_target(
+ max_tokens: Optional[int] = None, request_body: Optional[dict] = None
+) -> _AppTarget:
+ # OpenCode Desktop imports the login shell env; it merges config.json, opencode.json, opencode.jsonc, last wins.
+ root = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "opencode"
+ names = ("opencode.jsonc", "opencode.json", "config.json")
+ path = next((root / n for n in names if os.path.lexists(root / n)), root / "opencode.json")
+
+ def updates(text, path, base, key, entry):
+ provider = _opencode_provider(base, key, entry, max_tokens, request_body)
+ changes = [(("provider", _OPENCODE_PROVIDER), provider)]
+ config = _parse_app_config(path, text) or {}
+ enabled = config.get("enabled_providers")
+ if isinstance(enabled, list) and _OPENCODE_PROVIDER not in enabled:
+ changes.append((("enabled_providers",), [*enabled, _OPENCODE_PROVIDER]))
+ # disabled_providers wins over enabled_providers.
+ disabled = config.get("disabled_providers")
+ if isinstance(disabled, list) and _OPENCODE_PROVIDER in disabled:
+ changes.append(
+ (("disabled_providers",), [p for p in disabled if p != _OPENCODE_PROVIDER])
+ )
+ return changes
+
+ return _AppTarget("opencode", "OpenCode app", path, updates)
+
+
+def _openclaw_app_updates(
+ text,
+ path,
+ base,
+ key,
+ entry,
+ max_tokens = None,
+) -> list:
+ config = _parse_app_config(path, text) or {}
+ agents = config.get("agents")
+ defaults = agents.get("defaults") if isinstance(agents, dict) else None
+ defaults = defaults if isinstance(defaults, dict) else {}
+ ref = f"unsloth/{entry['id']}"
+ changes = [
+ (("models", "providers", "unsloth"), _openclaw_provider(base, key, entry, max_tokens))
+ ]
+ # The picker only offers allowlisted models once an allowlist exists; never create one.
+ policy = defaults.get("modelPolicy")
+ allowed = policy.get("allow") if isinstance(policy, dict) else None
+ meta = config.get("meta")
+ migrations = meta.get("migrations") if isinstance(meta, dict) else None
+ migrated = isinstance(migrations, dict) and migrations.get("modelPolicyAllowlist")
+ # An empty allow list or models map allows every model, so adding the ref would restrict it.
+ if isinstance(allowed, list):
+ if allowed and ref not in allowed:
+ changes.append((("agents", "defaults", "modelPolicy", "allow"), [*allowed, ref]))
+ elif policy is None and not migrated and isinstance(defaults.get("models"), dict):
+ if defaults["models"] and ref not in defaults["models"]:
+ changes.append((("agents", "defaults", "models", ref), {}))
+ return changes
+
+
+def _openclaw_app_target(max_tokens: Optional[int] = None) -> _AppTarget:
+ path = Path.home() / ".openclaw" / "openclaw.json"
+ updates = functools.partial(_openclaw_app_updates, max_tokens = max_tokens)
+ 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":
+ # 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"
+ 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"
+
+ def updates(text, path, base, key, entry):
+ settings: dict = {}
+ _set_hermes_provider(settings, base, entry, request_body)
+ provider = settings["providers"][_HERMES_PROVIDER]
+ del provider["key_env"]
+ provider["api_key"] = key
+ window = entry.get("context_length") or entry.get("max_context_length")
+ if window:
+ # 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)]
+
+ return _AppTarget("hermes", "Hermes app", path, updates)
+
+
@start_app.command("claude", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def claude(
ctx: typer.Context,
@@ -5521,14 +6178,22 @@ def codex(
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
as_subagent: bool = _AS_SUBAGENT_OPTION,
+ app: bool = _CODEX_APP_OPTION,
):
"""Point OpenAI Codex at the running Unsloth server and start it."""
# Route a leading `org/name` positional to --model; forward the rest to the agent.
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
+ _check_app_flags(app, ctx.args, as_subagent)
+ running = _recover_codex_app()
+ if app and running is not None:
+ _fail(
+ "The Codex app is already on Unsloth for another `unsloth start codex --app` "
+ f"(PID {running['owner']['pid']}). Stop that one first."
+ )
install_hint = _npm_install_hint("@openai/codex")
# Before the install prompt: _install_agent runs a remote installer, and this can refuse outright, so asking first fetches a tool the run cannot use.
_preflight_agent_gguf(_CODEX_GGUF_AGENT, model, serve = serve, launch = launch)
- _require_agent_for_launch("codex", install_hint, launch)
+ _require_agent_for_launch("codex", install_hint, launch and not app)
codex_effort = _codex_reasoning_effort(reasoning, reasoning_effort)
if codex_effort and not _agent_version_at_least("codex", _CODEX_REASONING_REQUEST_MIN_VERSION):
codex_effort = None
@@ -5544,7 +6209,8 @@ def codex(
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
- carried = _REASONING_FIELDS if codex_effort else frozenset(),
+ # The app reads no per-launch flags, so the server applies them.
+ carried = _REASONING_FIELDS if codex_effort and not app else frozenset(),
)
base, key, entry = _connect(
api_key,
@@ -5563,6 +6229,8 @@ def codex(
except BaseException:
_shutdown_auto_served()
raise
+ if app:
+ return _codex_app_session(base, api_key, entry)
if as_subagent:
subagent_id = _subagent_model_id(base, key, entry, model, gguf_variant)
subagent_model = {**entry, "id": subagent_id}
@@ -5643,17 +6311,19 @@ def openclaw(
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
+ app: bool = _APP_OPTION,
):
"""Point OpenClaw at the running Unsloth server and start it."""
# Route a leading `org/name` positional to --model; forward the rest to the agent.
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
_reject_as_subagent("openclaw", ctx.args)
+ _check_app_flags(app, ctx.args)
install_hint = (
"iwr -useb https://openclaw.ai/install.ps1 | iex"
if os.name == "nt"
else "curl -fsSL https://openclaw.ai/install.sh | bash"
)
- _require_agent_for_launch("openclaw", install_hint, launch)
+ _require_agent_for_launch("openclaw", install_hint, launch and not app)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
@@ -5666,7 +6336,7 @@ def openclaw(
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
- carried = _ALL_REQUEST_FIELDS,
+ carried = frozenset() if app else _ALL_REQUEST_FIELDS,
)
base, key, entry = _connect(
api_key,
@@ -5678,6 +6348,8 @@ def openclaw(
launch = launch,
server_options = server_options,
)
+ if app:
+ return _add_app_provider(_openclaw_app_target(max_tokens), base, api_key, entry)
openclaw_args = list(ctx.args)
# Default a bare `unsloth start openclaw` to the local TUI. Anything the caller passes through is forwarded verbatim so OpenClaw parses it under its own grammar (openclaw [global-flags] <command> [options]): an explicit subcommand, a global flag that must precede the command such as --profile/--dev, or a tui option. We cannot reinterpret those safely because a leading "--flag value" is ambiguous between a global (`--profile test`) and a tui option (`--message hi`), and prepending `tui --local` would break the global form, so only the empty case is defaulted.
if not openclaw_args:
@@ -5743,13 +6415,15 @@ def opencode(
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
as_subagent: bool = _AS_SUBAGENT_OPTION,
+ app: bool = _APP_OPTION,
):
"""Point OpenCode at the running Unsloth server and start it."""
# Route a leading `org/name` positional to --model; forward the rest to the agent.
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
+ _check_app_flags(app, ctx.args, as_subagent)
command_name, opencode_v2 = _opencode_command()
install_hint = _npm_install_hint("@opencode-ai/cli@beta" if opencode_v2 else "opencode-ai")
- _require_agent_for_launch(command_name, install_hint, launch)
+ _require_agent_for_launch(command_name, install_hint, launch and not app)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
@@ -5774,6 +6448,9 @@ def opencode(
launch = launch,
server_options = server_options,
)
+ if app:
+ target = _opencode_app_target(max_tokens, server_options.request_body())
+ return _add_app_provider(target, base, api_key, entry)
if opencode_v2:
typer.echo(
f"OpenCode V2 provider policies must allow '{_OPENCODE_PROVIDER}'.",
@@ -5915,15 +6592,17 @@ def hermes(
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
+ app: bool = _APP_OPTION,
):
"""Point Hermes (Nous Research) at the running Unsloth server and start it."""
# Route a leading `org/name` positional to --model; forward the rest to the agent.
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
_reject_as_subagent("hermes", ctx.args)
+ _check_app_flags(app, ctx.args)
native_args = [*_yolo_command_flags("hermes", yolo), *ctx.args]
command = ["hermes", *_hermes_resume_oneshot_args(native_args)]
install_hint = _hermes_install_hint()
- _require_agent_for_launch("hermes", install_hint, launch)
+ _require_agent_for_launch("hermes", install_hint, launch and not app)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
@@ -5948,6 +6627,19 @@ def hermes(
launch = launch,
server_options = server_options,
)
+ if app:
+ target = _hermes_app_target(server_options.request_body())
+ _add_app_provider(target, base, api_key, entry)
+ window = entry.get("context_length") or entry.get("max_context_length")
+ if window and int(window) < _HERMES_MIN_CONTEXT:
+ # The app's compaction settings are global, so they can't be scaled to this model.
+ typer.echo(
+ f"Warning: {entry['id']} serves {int(window):,} tokens, below Hermes' "
+ f"{_HERMES_MIN_CONTEXT:,} floor, so long chats in the app can overflow before "
+ f"Hermes compacts. Load it with --max-seq-length {_HERMES_MIN_CONTEXT} to avoid this.",
+ err = True,
+ )
+ 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())
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index 4b7d114e9b1..51eefeae964 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -6169,6 +6169,22 @@ def test_write_hermes_config_small_window_claims_floor(hermes_config):
assert config["compression"] == {"enabled": True, "threshold": 0.5625}
# The same floor check runs against the compression model mid-session.
assert config["auxiliary"]["compression"]["context_length"] == 65536
+ # Newer Hermes checks a local server's floor against ollama_num_ctx, not context_length.
+ assert config["model"]["ollama_num_ctx"] == 65536
+
+
+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)
+ start.write_hermes_config(BASE, MODEL, hermes_config)
+ assert "ollama_num_ctx" not in yaml.safe_load(hermes_config.read_text())["model"]
+
+
+def test_write_hermes_config_keeps_user_num_ctx(hermes_config):
+ yaml = pytest.importorskip("yaml")
+ hermes_config.write_text(yaml.safe_dump({"model": {"ollama_num_ctx": 100000}}))
+ start.write_hermes_config(BASE, MODEL, hermes_config)
+ assert yaml.safe_load(hermes_config.read_text())["model"]["ollama_num_ctx"] == 100000
def test_write_hermes_config_preserves_and_idempotent(hermes_config):
diff --git a/unsloth_cli/tests/test_start_app.py b/unsloth_cli/tests/test_start_app.py
new file mode 100644
index 00000000000..783d5105dde
--- /dev/null
+++ b/unsloth_cli/tests/test_start_app.py
@@ -0,0 +1,586 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(_REPO_ROOT))
+
+import pytest
+from typer.testing import CliRunner
+
+import unsloth_cli.commands.start as start
+
+BASE = "http://127.0.0.1:8888"
+MODEL = {"id": "unsloth/gemma-4-E2B-it-GGUF", "context_length": 32768}
+CLI_KEY = "sk-unsloth-c11c11c11c11"
+APP_KEY = "sk-unsloth-a99a99a99a99"
+
+
+def _parse_toml(text: str) -> dict:
+ tomllib = pytest.importorskip("tomllib")
+ return tomllib.loads(text)
+
+
+def _private(path: Path) -> bool:
+ return os.name == "nt" or stat.S_IMODE(path.stat().st_mode) == 0o600
+
+
+def studio(tmp_path, monkeypatch):
+ home = tmp_path / "home"
+ home.mkdir()
+ monkeypatch.setenv("HOME", str(home))
+ monkeypatch.setenv("USERPROFILE", str(home))
+ monkeypatch.setenv("LOCALAPPDATA", str(home / "AppData" / "Local"))
+ monkeypatch.delenv("CODEX_HOME", raising = False)
+ monkeypatch.delenv("UNSLOTH_API_KEY", raising = False)
+ server = {"calls": [], "keys": {CLI_KEY, APP_KEY}, "minted": 0}
+
+ def http_json(
+ method,
+ url,
+ token,
+ payload = None,
+ timeout = 30,
+ error = None,
+ ):
+ server["calls"].append((method, url, payload))
+ if url.endswith("/api/inference/loaded-models"):
+ if token not in server["keys"] and token != "jwt":
+ raise start.urllib.error.HTTPError(url, 401, "Unauthorized", {}, None)
+ return {"object": "list", "data": [MODEL]}
+ if url.endswith("/api/inference/status"):
+ return {"is_gguf": True, "model_identifier": MODEL["id"]}
+ if url.endswith("/api/auth/api-keys") and method == "GET":
+ return {"api_keys": [{"key_prefix": CLI_KEY[11:19]}]}
+ if url.endswith("/api/auth/api-keys") and method == "POST":
+ if payload["name"].startswith("Coding agents"):
+ return {"key": CLI_KEY, "api_key": {"id": 1}}
+ server["minted"] += 1
+ return {"key": APP_KEY, "api_key": {"id": 7}}
+ if "/api/auth/api-keys/" in url and method == "DELETE":
+ server["keys"].discard(APP_KEY)
+ return {"detail": "API key revoked"}
+ raise AssertionError(f"unexpected request: {method} {url}")
+
+ monkeypatch.setattr(start, "find_studio_server", lambda: BASE)
+ monkeypatch.setattr(start, "verify_studio_identity", lambda base: True)
+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)
+ monkeypatch.setattr(start, "_studio_token", lambda: "jwt")
+ monkeypatch.setattr(start, "_http_json", http_json)
+ 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, "_launch", lambda *args, **kwargs: pytest.fail("--app launched the CLI")
+ )
+ monkeypatch.setattr(start.shutil, "which", lambda _: None)
+ server["opened"] = 0
+ monkeypatch.setattr(
+ start, "_open_codex_app", lambda: server.__setitem__("opened", 1), raising = False
+ )
+ monkeypatch.setattr(start, "_studio_healthy", lambda base, timeout = 3.0: True)
+ server["while_running"] = lambda: None
+
+ def ctrl_c(_seconds):
+ server["while_running"]()
+ raise KeyboardInterrupt
+
+ monkeypatch.setattr(start.time, "sleep", ctrl_c)
+ server["home"] = home
+ return server
+
+
+USER_CODEX = (
+ "# my settings\n"
+ 'model = "gpt-5.5"\n'
+ 'approval_policy = "on-request"\n'
+ "\n"
+ '[projects."/work/repo"]\n'
+ 'trust_level = "trusted"\n'
+)
+
+
+def _codex_config(studio) -> Path:
+ config = studio["home"] / ".codex" / "config.toml"
+ config.parent.mkdir(exist_ok = True)
+ config.write_text(USER_CODEX)
+ return config
+
+
+def test_codex_app_switches_the_app_while_running_and_back_on_exit(studio):
+ config = _codex_config(studio)
+ catalog = config.with_name("unsloth-model-catalog.json")
+ backup = config.with_name("config.toml.unsloth-backup")
+ seen = {}
+
+ def while_running():
+ seen["config"] = _parse_toml(config.read_text())
+ seen["catalog"] = json.loads(catalog.read_text())["models"]
+ seen["private"] = all(_private(p) for p in (config, catalog, backup))
+ seen["backup"] = backup.read_text()
+
+ studio["while_running"] = while_running
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app"])
+
+ assert result.exit_code == 0, result.output
+ assert seen["config"]["model_provider"] == "unsloth_api"
+ assert seen["config"]["model"] == MODEL["id"]
+ assert seen["config"]["model_catalog_json"] == "unsloth-model-catalog.json"
+ assert seen["config"]["approval_policy"] == "on-request"
+ provider = seen["config"]["model_providers"]["unsloth_api"]
+ assert provider["base_url"] == f"{BASE}/v1"
+ assert provider["experimental_bearer_token"] == APP_KEY
+ [listed] = seen["catalog"]
+ assert (listed["slug"], listed["visibility"]) == (MODEL["id"], "list")
+ assert seen["private"]
+ assert seen["backup"] == USER_CODEX
+ assert studio["opened"] == 1
+ assert config.read_text() == USER_CODEX
+ assert not catalog.exists()
+ assert not backup.exists()
+ assert ("POST", f"{BASE}/api/auth/api-keys", {"name": "Codex app"}) in studio["calls"]
+ assert ("DELETE", f"{BASE}/api/auth/api-keys/7", None) in studio["calls"]
+ assert APP_KEY not in result.output
+ assert "Switched the Codex app back" in result.output
+
+
+def test_codex_app_switches_back_when_unsloth_stops_answering(studio, monkeypatch):
+ config = _codex_config(studio)
+ monkeypatch.setattr(start.time, "sleep", lambda _seconds: None)
+ monkeypatch.setattr(start, "_studio_healthy", lambda base, timeout = 3.0: False)
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app"])
+
+ assert result.exit_code == 0, result.output
+ assert "stopped answering" in result.output
+ assert config.read_text() == USER_CODEX
+ assert not config.with_name("unsloth-model-catalog.json").exists()
+
+
+def test_codex_recovers_a_switch_left_by_a_dead_session(studio, monkeypatch, tmp_path):
+ config = _codex_config(studio)
+ with monkeypatch.context() as crash:
+ crash.setattr(start, "_switch_codex_app_back", lambda *args: [], raising = False)
+ assert CliRunner().invoke(start.start_app, ["codex", "--app"]).exit_code == 0
+ state_path = tmp_path / "agents" / "app" / "codex.json"
+ state = json.loads(state_path.read_text())
+ state["owner"] = {"pid": 2**22 + 4321, "started": 1.0}
+ state_path.write_text(json.dumps(state))
+ assert _parse_toml(config.read_text())["model"] == MODEL["id"]
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--no-launch"])
+
+ assert result.exit_code == 0, result.output
+ assert "did not exit cleanly" in result.output
+ assert config.read_text() == USER_CODEX
+ assert not state_path.exists()
+
+
+def test_a_second_codex_app_session_does_not_switch_twice(studio):
+ config = _codex_config(studio)
+ seen = {}
+
+ def while_running():
+ before = config.read_text()
+ seen["second"] = CliRunner().invoke(start.start_app, ["codex", "--app"])
+ seen["unchanged"] = config.read_text() == before
+
+ studio["while_running"] = while_running
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app"])
+
+ assert result.exit_code == 0, result.output
+ assert seen["second"].exit_code == 1
+ assert "already on Unsloth" in seen["second"].output
+ assert seen["unchanged"]
+ assert studio["minted"] == 1
+ assert config.read_text() == USER_CODEX
+
+
+def test_codex_app_leaves_a_model_the_user_picked_while_running(studio):
+ config = _codex_config(studio)
+ studio["while_running"] = lambda: config.write_text(
+ config.read_text().replace(f'model = "{MODEL["id"]}"', 'model = "o3"')
+ )
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app"])
+
+ assert result.exit_code == 0, result.output
+ parsed = _parse_toml(config.read_text())
+ assert parsed["model"] == "o3"
+ assert parsed["approval_policy"] == "on-request"
+ assert "model_provider" not in parsed
+ assert "model_catalog_json" not in parsed
+ assert "unsloth_api" not in parsed.get("model_providers", {})
+ assert "Left model" in result.output
+
+
+def test_codex_app_creates_and_removes_a_missing_config(studio):
+ config = studio["home"] / ".codex" / "config.toml"
+ seen = {}
+ studio["while_running"] = lambda: seen.update(model = _parse_toml(config.read_text())["model"])
+
+ assert CliRunner().invoke(start.start_app, ["codex", "--app"]).exit_code == 0
+
+ assert seen["model"] == MODEL["id"]
+ assert not config.exists()
+ assert not config.with_name("unsloth-model-catalog.json").exists()
+
+
+def test_codex_app_keeps_a_created_config_the_app_wrote_to_without_a_toml_parser(
+ studio, monkeypatch
+):
+ config = studio["home"] / ".codex" / "config.toml"
+ monkeypatch.setitem(sys.modules, "tomllib", None)
+ monkeypatch.setitem(sys.modules, "tomli", None)
+ studio["while_running"] = lambda: config.write_text(
+ config.read_text() + '\n[projects."/work/repo"]\ntrust_level = "trusted"\n'
+ )
+
+ assert CliRunner().invoke(start.start_app, ["codex", "--app"]).exit_code == 0
+
+ assert config.read_text().strip() == '[projects."/work/repo"]\ntrust_level = "trusted"'
+
+
[email protected](os.name == "nt", reason = "creating a symlink needs admin rights on Windows")
+def test_codex_app_refuses_a_symlinked_config(studio, tmp_path):
+ target = tmp_path / "dotfiles" / "codex.toml"
+ target.parent.mkdir()
+ target.write_text(USER_CODEX)
+ config = studio["home"] / ".codex" / "config.toml"
+ config.parent.mkdir()
+ config.symlink_to(target)
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app"])
+
+ assert result.exit_code == 1
+ assert "symlink" in result.output
+ assert target.read_text() == USER_CODEX
+ assert studio["minted"] == 0
+
+
+def test_app_refuses_a_remote_server_without_an_explicit_key(studio, monkeypatch, tmp_path):
+ remote = "http://10.0.0.5:8888"
+ monkeypatch.setattr(start, "find_studio_server", lambda: remote)
+ cache = tmp_path / "agent_api_key.json"
+ cache.write_text(json.dumps({"servers": {remote: {"saved": [CLI_KEY], "minted": []}}}))
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app"])
+
+ assert result.exit_code == 1
+ assert "--api-key" in result.output
+ assert not (studio["home"] / ".codex").exists()
+
+
+def test_codex_app_never_revokes_an_explicit_key(studio, monkeypatch):
+ monkeypatch.setattr(start, "find_studio_server", lambda: "http://10.0.0.5:8888")
+ config = studio["home"] / ".codex" / "config.toml"
+ seen = {}
+ studio["while_running"] = lambda: seen.update(config = _parse_toml(config.read_text()))
+
+ result = CliRunner().invoke(start.start_app, ["codex", "--app", "--api-key", CLI_KEY])
+
+ assert result.exit_code == 0, result.output
+ assert seen["config"]["model_providers"]["unsloth_api"]["experimental_bearer_token"] == CLI_KEY
+ assert studio["minted"] == 0
+ assert not any(m == "DELETE" for m, _, _ in studio["calls"])
+
+
+def test_codex_app_has_no_off_switch():
+ result = CliRunner().invoke(start.start_app, ["codex", "--help"])
+ assert "--app " in result.output
+ assert "--app-off" not in result.output
+
+
+def test_undo_is_not_an_app_option(studio):
+ result = CliRunner().invoke(start.start_app, ["opencode", "--app", "--undo"])
+ assert result.exit_code == 1
+ assert "takes no agent arguments" in result.output
+
+
+def test_opencode_app_adds_unsloth_without_changing_the_default_model(studio, monkeypatch):
+ monkeypatch.delenv("XDG_CONFIG_HOME", raising = False)
+ monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode", False))
+ config = studio["home"] / ".config" / "opencode" / "opencode.json"
+ config.parent.mkdir(parents = True)
+ user = {
+ "$schema": "https://opencode.ai/config.json",
+ "model": "openai/gpt-5.5",
+ "enabled_providers": ["anthropic"],
+ "permission": {"bash": "allow"},
+ }
+ original = json.dumps(user, indent = 4) + "\n"
+ config.write_text(original)
+
+ result = CliRunner().invoke(start.start_app, ["opencode", "--app"])
+
+ assert result.exit_code == 0, result.output
+ data = json.loads(config.read_text())
+ assert data["model"] == "openai/gpt-5.5"
+ assert data["enabled_providers"] == ["anthropic", "unsloth-studio"]
+ provider = data["provider"]["unsloth-studio"]
+ assert provider["options"] == {"baseURL": f"{BASE}/v1", "apiKey": APP_KEY}
+ assert provider["models"][MODEL["id"]]["limit"]["output"] > 0
+ assert data["permission"] == {"bash": "allow"}
+ assert "compaction" not in data
+ assert _private(config)
+ assert config.with_name("opencode.json.unsloth-backup").read_text() == original
+ assert ("POST", f"{BASE}/api/auth/api-keys", {"name": "OpenCode app"}) in studio["calls"]
+ assert APP_KEY not in result.output
+
+ first = config.read_text()
+ again = CliRunner().invoke(start.start_app, ["opencode", "--app"])
+ assert again.exit_code == 0, again.output
+ assert config.read_text() == first
+ assert studio["minted"] == 1
+
+
+def test_openclaw_app_adds_unsloth_and_joins_an_existing_allowlist(studio):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ user = {
+ "agents": {
+ "defaults": {
+ "model": {"primary": "openai/gpt-5.5", "fallbacks": ["openai/o3"]},
+ "modelPolicy": {"allow": ["openai/*"]},
+ "workspace": "/work",
+ }
+ },
+ "gateway": {"mode": "local", "auth": {"mode": "token"}},
+ }
+ config.write_text(json.dumps(user, indent = 2) + "\n")
+
+ result = CliRunner().invoke(start.start_app, ["openclaw", "--app"])
+
+ assert result.exit_code == 0, result.output
+ data = json.loads(config.read_text())
+ ref = f"unsloth/{MODEL['id']}"
+ defaults = data["agents"]["defaults"]
+ assert defaults["model"] == user["agents"]["defaults"]["model"]
+ assert defaults["modelPolicy"] == {"allow": ["openai/*", ref]}
+ assert "models" not in defaults
+ assert defaults["workspace"] == "/work"
+ assert data["gateway"] == user["gateway"]
+ assert data["models"]["providers"]["unsloth"]["apiKey"] == APP_KEY
+ assert data["models"]["providers"]["unsloth"]["baseUrl"] == f"{BASE}/v1"
+
+
+def test_openclaw_app_creates_no_allowlist(studio):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ config.write_text('{"agents": {"defaults": {"model": "openai/gpt-5.5"}}}\n')
+
+ assert CliRunner().invoke(start.start_app, ["openclaw", "--app"]).exit_code == 0
+
+ defaults = json.loads(config.read_text())["agents"]["defaults"]
+ assert defaults == {"model": "openai/gpt-5.5"}
+
+
+ "defaults",
+ [{"modelPolicy": {"allow": []}}, {"models": {}}],
+ ids = ["empty-allow", "empty-legacy-map"],
+)
+def test_openclaw_app_keeps_an_empty_allowlist_open(studio, defaults):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ config.write_text(json.dumps({"agents": {"defaults": defaults}}) + "\n")
+
+ assert CliRunner().invoke(start.start_app, ["openclaw", "--app"]).exit_code == 0
+
+ assert json.loads(config.read_text())["agents"]["defaults"] == defaults
+
+
+def test_opencode_app_reads_a_commented_jsonc(studio, monkeypatch):
+ monkeypatch.delenv("XDG_CONFIG_HOME", raising = False)
+ monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode", False))
+ config = studio["home"] / ".config" / "opencode" / "opencode.jsonc"
+ config.parent.mkdir(parents = True)
+ config.write_text('{\n // mine\n "model": "openai/gpt-5.5", /* x */\n "theme": "a//b",\n}\n')
+
+ result = CliRunner().invoke(start.start_app, ["opencode", "--app"])
+
+ assert result.exit_code == 0, result.output
+ data = json.loads(config.read_text())
+ assert (data["model"], data["theme"]) == ("openai/gpt-5.5", "a//b")
+ assert "unsloth-studio" in data["provider"]
+
+
+def test_opencode_app_reenables_a_disabled_unsloth(studio, monkeypatch):
+ monkeypatch.delenv("XDG_CONFIG_HOME", raising = False)
+ monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode", False))
+ config = studio["home"] / ".config" / "opencode" / "opencode.json"
+ config.parent.mkdir(parents = True)
+ config.write_text(json.dumps({"disabled_providers": ["openai", "unsloth-studio"]}) + "\n")
+
+ assert CliRunner().invoke(start.start_app, ["opencode", "--app"]).exit_code == 0
+
+ data = json.loads(config.read_text())
+ assert data["disabled_providers"] == ["openai"]
+ assert "unsloth-studio" in data["provider"]
+
+
+def test_openclaw_app_reads_a_commented_config(studio):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ config.write_text('{\n // mine\n "agents": {"defaults": {"model": "openai/gpt-5.5",}},\n}\n')
+
+ result = CliRunner().invoke(start.start_app, ["openclaw", "--app"])
+
+ assert result.exit_code == 0, result.output
+ data = json.loads(config.read_text())
+ assert data["agents"]["defaults"] == {"model": "openai/gpt-5.5"}
+ assert data["models"]["providers"]["unsloth"]["apiKey"] == APP_KEY
+
+
+def test_opencode_app_keeps_each_config_dirs_backup_and_key(studio, monkeypatch, tmp_path):
+ monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode", False))
+ originals = {}
+ for name in ("a", "b"):
+ config = tmp_path / name / "opencode" / "opencode.json"
+ config.parent.mkdir(parents = True)
+ originals[name] = json.dumps({"model": f"openai/{name}"}) + "\n"
+ config.write_text(originals[name])
+
+ for name in ("a", "b", "a"):
+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / name))
+ assert CliRunner().invoke(start.start_app, ["opencode", "--app"]).exit_code == 0
+
+ for name in ("a", "b"):
+ backup = tmp_path / name / "opencode" / "opencode.json.unsloth-backup"
+ assert backup.read_text() == originals[name]
+ assert studio["minted"] == 2
+
+
+def test_codex_app_owner_without_psutil(monkeypatch):
+ monkeypatch.setitem(sys.modules, "psutil", None)
+ owner = start._codex_app_owner()
+ assert owner == {"pid": os.getpid(), "started": None}
+ assert start._codex_app_owner_alive(owner) is True
+
+
+def test_hermes_app_adds_unsloth_to_the_active_profile(studio):
+ yaml = pytest.importorskip("yaml")
+ root = start._hermes_app_target().path.parent
+ (root / "profiles" / "work").mkdir(parents = True)
+ (root / "active_profile").write_text("work\n")
+ config = root / "profiles" / "work" / "config.yaml"
+ original = (
+ "# my hermes\nmodel:\n default: openrouter/kimi-k3 # mine\n provider: openrouter\n"
+ "toolsets:\n- web\n"
+ )
+ config.write_text(original)
+
+ result = CliRunner().invoke(start.start_app, ["hermes", "--app"])
+
+ assert result.exit_code == 0, result.output
+ 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"]
+ assert provider["api_key"] == APP_KEY
+ assert provider["base_url"] == f"{BASE}/v1"
+ assert "key_env" not in provider
+ assert provider["models"] == {MODEL["id"]: {"context_length": start._HERMES_MIN_CONTEXT}}
+ assert data["toolsets"] == ["web"]
+ assert config.read_text().startswith(original)
+ assert not (root / "config.yaml").exists()
+ assert ("POST", f"{BASE}/api/auth/api-keys", {"name": "Hermes app"}) in studio["calls"]
+ assert "--max-seq-length 65536" in result.output
+
+
+def test_app_refuses_a_config_it_cannot_parse(studio):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ config.write_text("{ // json5 comment\n agents: {} }\n")
+
+ result = CliRunner().invoke(start.start_app, ["openclaw", "--app"])
+
+ assert result.exit_code == 1
+ assert "Couldn't parse" in result.output
+ assert config.read_text() == "{ // json5 comment\n agents: {} }\n"
+ assert studio["minted"] == 0
+
+
+def test_app_revokes_the_key_it_minted_when_setup_fails(studio):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ config.write_text('{"models": []}\n')
+
+ result = CliRunner().invoke(start.start_app, ["openclaw", "--app"])
+
+ assert result.exit_code == 1
+ assert "isn't a table" in result.output
+ assert config.read_text() == '{"models": []}\n'
+ assert studio["minted"] == 1
+ assert ("DELETE", f"{BASE}/api/auth/api-keys/7", None) in studio["calls"]
+
+
+def test_app_revokes_the_key_it_minted_when_saving_fails(studio, monkeypatch):
+ config = studio["home"] / ".openclaw" / "openclaw.json"
+ config.parent.mkdir()
+ config.write_text("{}\n")
+
+ def read_only(path, text):
+ raise PermissionError(path)
+
+ monkeypatch.setattr(start, "_write_app_file", read_only)
+
+ result = CliRunner().invoke(start.start_app, ["openclaw", "--app"])
+
+ assert result.exit_code == 1
+ assert ("DELETE", f"{BASE}/api/auth/api-keys/7", None) in studio["calls"]
+
+
+def test_codex_app_switches_back_a_config_rewritten_with_crlf(studio):
+ config = _codex_config(studio)
+ studio["while_running"] = lambda: config.write_bytes(
+ config.read_bytes().replace(b"\r\n", b"\n").replace(b"\n", b"\r\n")
+ )
+
+ assert CliRunner().invoke(start.start_app, ["codex", "--app"]).exit_code == 0
+
+ parsed = _parse_toml(config.read_text())
+ assert "model_providers" not in parsed
+ assert parsed["model"] == "gpt-5.5"
+
+
+ "agent, flags",
+ [("openclaw", ["--temperature", "0.3"]), ("codex", ["--reasoning-effort", "high"])],
+)
+def test_app_leaves_request_flags_to_the_server(studio, monkeypatch, agent, flags):
+ seen = {}
+ real_connect = start._connect
+
+ def connect(*args, **kwargs):
+ seen["options"] = kwargs["server_options"]
+ return real_connect(*args, **kwargs)
+
+ monkeypatch.setattr(start, "_connect", connect)
+ monkeypatch.setattr(start, "_agent_version_at_least", lambda *args: True)
+
+ result = CliRunner().invoke(start.start_app, [agent, "--app", *flags])
+
+ assert result.exit_code == 0, result.output
+ assert seen["options"].sent_by_agent() == frozenset()
+
+
+def test_hermes_app_uses_the_windows_hermes_home(studio, monkeypatch, tmp_path):
+ local = tmp_path / "LocalAppData"
+ monkeypatch.setattr(start.sys, "platform", "win32")
+ monkeypatch.setenv("LOCALAPPDATA", str(local))
+
+ target = start._hermes_app_target()
+
+ assert target.path == local / "hermes" / "config.yaml"