Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""`unsloth start` — launch a coding agent against a running Unsloth server."""
import atexit
import base64
import contextlib
import errno
import functools
import hashlib
import http.client
import json
import math
import os
import re
import shlex
import shutil
import signal
import subprocess
import sys
import tempfile
import threading
import time
import urllib.error
import urllib.request
from pathlib import Path
from typing import Literal, NamedTuple, NoReturn, Optional
from urllib.parse import quote, urlencode, urlparse
import click
import typer
from typer.core import TyperCommand
from studio.backend.utils.coding_agents import (
deepseek_harness_executables_on_path,
is_deepseek_harness_executable,
)
from unsloth_cli._inference import (
_USER_AGENT,
_studio_token,
ensure_studio_backend_path,
find_studio_server,
is_loopback_url,
raise_for_deferred_error,
require_completed_padded_body,
urlopen_local,
urlopen_no_redirect,
verify_studio_identity,
)
start_app = typer.Typer(
help = "Start a coding agent against a running Unsloth server.",
no_args_is_help = True,
context_settings = {"help_option_names": ["-h", "--help"]},
)
_CODEX_PROFILE = "unsloth_api"
_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"
# Not "unsloth": Hermes strips a `<provider>/` prefix, so unsloth/<repo> stops matching model.default.
_HERMES_PROVIDER = "unsloth-studio"
_HERMES_LEGACY_PROVIDER = "unsloth"
_HERMES_MCP_MANIFEST = "unsloth_mcp_servers.json"
# Skip the installer's interactive setup wizard: `unsloth start hermes` runs this hint unattended and then writes its own session-scoped Hermes config, so the wizard's global API-key/model prompts would block the launch and point the user at a different provider than the one Unsloth just configured. Both installers expose a skip flag: `-SkipSetup` (PowerShell) and `--skip-setup` (POSIX, passed to the piped script via `bash -s --`). Pin both the fetched script and the repository checkout it performs to the same full commit so a later change to either upstream branch cannot silently replace code that Unsloth executes with the user's privileges.
_HERMES_INSTALL_COMMIT = "f1af945f6c576eccb126fa955edc9be258b33020"
_HERMES_INSTALL_BASE = (
"https://raw.githubusercontent.com/NousResearch/hermes-agent/"
f"{_HERMES_INSTALL_COMMIT}/scripts"
)
_HERMES_WINDOWS_INSTALL_HINT = (
f"& ([scriptblock]::Create((irm {_HERMES_INSTALL_BASE}/install.ps1)))"
f" -SkipSetup -Commit {_HERMES_INSTALL_COMMIT}"
)
_HERMES_POSIX_INSTALL_HINT = (
f"curl -fsSL {_HERMES_INSTALL_BASE}/install.sh | bash -s --"
f" --skip-setup --commit {_HERMES_INSTALL_COMMIT}"
)
# Hermes refuses to initialize when the model window is under 64,000 tokens; its error message points at the model.context_length / auxiliary.compression overrides in config.yaml. write_hermes_config claims this value for smaller windows and scales the compaction threshold back down to the real window.
_HERMES_MIN_CONTEXT = 65536
_DSH_PROVIDER = "unsloth"
_DSH_ENV_KEY = "UNSLOTH_API_KEY"
_DSH_PATCH_FILE = "unsloth.patch.yml"
_DSH_PACKAGE = "@deepseek-ai/dsh@latest"
# dsh picks its sandbox+approval preset from DSH_PERMISSION_MODE via ??, so omitting it would inherit a danger-full-access exported in the parent shell, and "" is not unset to ??. Pin the mode in both directions instead of only setting it for --yolo.
_DSH_SAFE_PERMISSION_MODE = "workspace-write"
_DSH_YOLO_PERMISSION_MODE = "danger-full-access"
# dsh's pi-ai provider sends max_tokens = contextWindow - its prompt estimate - 4,096 (pi-ai CONTEXT_SAFETY_TOKENS), floored at 1, and dsh's own instructions and tools are about 6,500 tokens: at 8,192 every reply is cut after one token (#14315).
_DSH_MIN_CONTEXT = 16384
# First request of a stock install (system prompt + tool schemas) before any user text, measured on Claude Code 2.1 and OpenCode 1.19 / 2.1. MCP servers and project instructions add to it.
_CLAUDE_PROMPT_TOKENS = 16_000
_OPENCODE_PROMPT_TOKENS = 7_500
_OPENCODE_V2_PROMPT_TOKENS = 5_500
_PI_PROVIDER = "unsloth"
_SUBAGENT_NAME = "unsloth"
_SUBAGENT_DESCRIPTION = (
"Local coding subagent powered by Unsloth for debugging, implementation, and codebase "
"research. Use when the user asks to spawn an Unsloth or local agent."
)
_AUTO_ROUTE_DESCRIPTION = (
"Local coding subagent powered by Unsloth. In this session it is the only way to reach "
"files and the shell: {blocked}. "
"Give it the complete task in one message (codebase search, reading or summarizing files, "
"running tests or commands, mechanical edits with a clear spec) and review its result "
"before answering. Keep talking with the user and planning and design decisions to "
"yourself."
)
_SUBAGENT_AUTO_ROUTE_DESCRIPTION = _AUTO_ROUTE_DESCRIPTION.format(
blocked = (
"your own Read, Grep, Glob, Bash, PowerShell, Monitor, NotebookRead and Agent calls "
"are blocked"
)
)
# Without tools of its own the parent cannot check a small model's answer except by asking for the evidence.
_AUTO_ROUTE_VERIFY = (
" It is a small local model and can be wrong: ask it for the raw command output behind an "
"answer you rely on, such as a search that found nothing or an edit, and say so if you "
"cannot confirm it."
)
_AUTO_ROUTE_CHECK = (
_AUTO_ROUTE_VERIFY + " If it fails, tell the user plainly; you cannot do the step yourself."
)
_OPENCODE_AUTO_ROUTE_DESCRIPTION = (
_AUTO_ROUTE_DESCRIPTION.format(
blocked = "your own read, grep, glob, list, lsp, bash and edit tools are blocked"
)
+ _AUTO_ROUTE_VERIFY
+ " If it fails, do that step with your own read and bash if they work, or else tell the "
"user plainly that it was not done."
)
_OPENCODE_PLAN_SUBAGENT_NAME = "unsloth-plan"
_OPENCODE_AUTO_ROUTE_PLAN_DESCRIPTION = (
"Read-only local coding subagent powered by Unsloth for planning and codebase research. "
"In plan mode it is the only way to read files: your own read, grep, glob, list, lsp and "
"bash tools are blocked. Give it the complete question in one message."
)
_OPENCODE_HIDDEN_TOOLS = ("grep", "glob", "list", "lsp")
# OpenCode's free tier refuses a request without read or bash, so on V1 the route plugin blocks their calls instead of a permission rule removing them.
_OPENCODE_ROUTED_TOOLS = ("read", "bash")
_OPENCODE_ROUTE_PLUGIN = "unsloth-auto-route.js"
_SUBAGENT_AUTO_ROUTE_INSTRUCTIONS = (
"Files and the shell in this session are reachable only through the unsloth_agent tool; "
"your own Read, Grep, Glob, Bash, PowerShell, Monitor, NotebookRead and Agent calls are "
"blocked by a hook. Give the "
"tool the complete task in one message, with the paths and commands it needs, and review "
"its result before answering. Keep talking with the user and planning and design "
"decisions to yourself. In plan mode call unsloth_plan_agent instead."
)
_SUBAGENT_INSTRUCTIONS = (
"You are a local coding subagent powered by Unsloth. Complete the assigned task directly, "
"use the available tools when useful, verify your work, and return a concise result to the "
"parent agent."
)
_SUBAGENT_PLAN_DESCRIPTION = (
"Read-only local coding subagent powered by Unsloth for planning and codebase research. "
"Use this local agent when Claude is in plan mode."
)
_SUBAGENT_PLAN_INSTRUCTIONS = (
"You are a read-only local coding subagent powered by Unsloth. Investigate the assigned "
"task with read-only tools, produce a concrete plan or answer, and return a concise result "
"to the parent agent. Do not modify files."
)
_CLAUDE_SUBAGENT_MCP_MODULE = "unsloth_cli.claude_subagent_mcp"
_CLAUDE_SUBAGENT_SETTINGS_ENV = "UNSLOTH_CLAUDE_SUBAGENT_SETTINGS"
_CLAUDE_SUBAGENT_AUTO_ROUTE_ENV = "UNSLOTH_CLAUDE_SUBAGENT_AUTO_ROUTE"
_CLAUDE_SUBAGENT_FALLBACK_ENV = "UNSLOTH_CLAUDE_SUBAGENT_FALLBACK"
_CLAUDE_ROUTE_FALLBACK_FILE = "local-agent-failed"
_CLAUDE_SUBAGENT_TOOL = "mcp__plugin_unsloth-local-agent_unsloth__unsloth_agent"
_CLAUDE_SUBAGENT_PLAN_TOOL = "mcp__plugin_unsloth-local-agent_unsloth__unsloth_plan_agent"
_CODEX_SUBAGENT_MCP_MODULE = "unsloth_cli.codex_subagent_mcp"
_CODEX_SUBAGENT_MCP_SERVER = "unsloth_local_agent"
_CODEX_SUBAGENT_MCP_TOOL = "spawn_local_agent"
_CODEX_SUBAGENT_CONFIG_ENV = "UNSLOTH_CODEX_SUBAGENT_CONFIG"
_CODEX_PARENT_OVERLAY_MANIFEST = ".unsloth-parent-overlay.json"
_CODEX_USER_FILES = ("AGENTS.md", "AGENTS.override.md", "skills", "rules", "prompts")
_CODEX_USER_FILES_MANIFEST = "unsloth_user_files.json"
_CODEX_COPIED_DIRS = {"agents", "skills", "rules", "prompts", "plugins", "marketplaces", "sessions"}
_CODEX_EPHEMERAL_STALE_SECONDS = 24 * 60 * 60
_CODEX_EPHEMERAL_HEARTBEAT_SECONDS = 60
_CODEX_SUBAGENT_TOOL_DESCRIPTION = (
f"{_SUBAGENT_DESCRIPTION} Use this tool instead of the built-in spawn_agent tool for those "
"requests. Other subagent requests may use the built-in tools normally."
)
_CODEX_SUBAGENT_ROUTING_INSTRUCTIONS = (
"When the user asks to spawn an Unsloth agent or local agent, you must call the "
"spawn_local_agent MCP tool once with the complete task. Do not answer, simulate the "
"result, call wait, or use a built-in subagent before calling the tool. Use built-in "
"subagents for other delegation requests."
)
_CODEX_AUTO_ROUTE_TOOL_DESCRIPTION = (
_AUTO_ROUTE_DESCRIPTION.format(blocked = "your own shell is disabled") + _AUTO_ROUTE_CHECK
)
_CODEX_AUTO_ROUTE_INSTRUCTIONS = (
"Your own shell is disabled in this session, so files and commands are reachable only "
"through the spawn_local_agent MCP tool. Call it without being asked for codebase search, "
"reading or summarizing files, running tests or commands, and mechanical edits, with the "
"complete task in one message, and review its result before answering. Keep talking with "
"the user and planning and design decisions to yourself." + _AUTO_ROUTE_CHECK
)
_CODEX_AUTO_ROUTE_FLAGS = [
arg
for feature in ("shell_tool", "multi_agent", "view_image")
for arg in ("-c", f"features.{feature}=false")
]
_PI_SUBAGENT_EXTENSION = Path(__file__).parent.parent / "pi_subagent.ts"
_PI_USER_RESOURCE_DIRS = ("extensions", "skills", "prompts", "themes", "npm", "git")
_PI_USER_RESOURCE_SETTINGS = ("packages", "extensions", "skills", "prompts", "themes")
_PI_USER_VERBATIM_SETTINGS = ("npmCommand",)
_PI_USER_RESOURCES_MANIFEST = ".unsloth-user-resources.json"
# OpenCode selects a model by "<providerID>/<modelID>". Use a dedicated id to avoid colliding with a user's providers; provider filters are set in the launch-time overlay.
_OPENCODE_PROVIDER = "unsloth-studio"
# OpenCode sends min(limit.output, this) as max_tokens unless the env var below raises it.
_OPENCODE_OUTPUT_TOKEN_MAX = 32_000
_CLAUDE_COMPACT_OUTPUT_RESERVE = 20_000
# Claude Code 2.1.307-2.1.309 compact one token past window - min(max output, 20k) - 3k, in the TUI and -p alike.
_CLAUDE_COMPACT_BUFFER = 3_000
# claude 2.1 ignores a smaller CLAUDE_CODE_AUTO_COMPACT_WINDOW and warns about it on every launch.
_CLAUDE_MIN_AUTO_COMPACT_WINDOW = 100_000
_OPENCODE_OUTPUT_TOKEN_MAX_ENV = "OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX"
_VIBE_PROVIDER = "unsloth-studio"
_VIBE_MODEL_ALIAS = "unsloth"
_VIBE_ENV_KEY = "UNSLOTH_API_KEY"
# Both installers put binaries in ~/.local/bin; Vibe's exits 1 and uv's leaves the shell PATH stale when it is missing.
_VIBE_POSIX_INSTALL_HINT = (
'curl -LsSf https://mistral.ai/vibe/install.sh | PATH="$HOME/.local/bin:$PATH" bash'
)
_VIBE_WINDOWS_INSTALL_HINT = (
"irm https://astral.sh/uv/install.ps1 | iex; "
'$env:Path = "$HOME\\.local\\bin;$env:Path"; uv tool install mistral-vibe'
)
_PROVIDER_HEADER = f"[model_providers.{_CODEX_PROFILE}]"
_PASSTHROUGH = {"allow_extra_args": True, "ignore_unknown_options": True}
class _PassthroughCommand(TyperCommand):
"""Preserve the option separator when forwarding arguments to an agent."""
def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
raw_args = list(args)
try:
separator = raw_args.index("--")
except ValueError:
return super().parse_args(ctx, args)
trailing_count = len(raw_args) - separator - 1
remaining = super().parse_args(ctx, args)
insert_at = max(0, len(remaining) - trailing_count)
if insert_at >= len(remaining) or remaining[insert_at] != "--":
remaining.insert(insert_at, "--")
ctx.args = remaining
return remaining
# provider routing overrides ANTHROPIC_BASE_URL and would bypass the local server (#9864).
_CLAUDE_ENV_UNSET = (
"ANTHROPIC_API_KEY",
"CLAUDE_CODE_OAUTH_TOKEN",
"ANTHROPIC_UNIX_SOCKET",
"CLAUDE_CODE_USE_FOUNDRY",
"ANTHROPIC_FOUNDRY_BASE_URL",
"ANTHROPIC_FOUNDRY_RESOURCE",
"CLAUDE_CODE_USE_BEDROCK",
"CLAUDE_CODE_USE_VERTEX",
"CLAUDE_CODE_USE_ANTHROPIC_AWS",
"CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD",
"CLAUDE_CODE_USE_MANTLE",
)
_CODEX_ENV_UNSET = ("OPENAI_API_KEY", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN")
# Unset all three: OpenClaw tries CODEX_API_KEY before OPENAI_API_KEY, and CODEX_ACCESS_TOKEN reaches its exec tool and the codex CLI.
_OPENCLAW_ENV_UNSET = ("OPENAI_API_KEY", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN")
_OPENCLAW_PROFILE_RE = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}", re.IGNORECASE)
# Shared by every agent command; only the config/env/command differ. Help is grouped into rich panels so `--help` reads as Model / Server / Session instead of one long unaligned list.
_PANEL_MODEL = "Model"
_PANEL_SERVER = "Server"
_PANEL_SAMPLING = "Sampling"
_PANEL_SESSION = "Agent session"
_MODEL_OPTION = typer.Option(
None,
"--model",
"-m",
rich_help_panel = _PANEL_MODEL,
help = "Model for the agent, or a bare `org/name(:variant)` positional. "
"Defaults to the one loaded in Unsloth.",
)
_GGUF_VARIANT_OPTION = typer.Option(
None,
"--gguf-variant",
rich_help_panel = _PANEL_MODEL,
help = "GGUF quant variant to load (e.g. UD-Q4_K_XL). Defaults to UD-Q4_K_XL for "
"unsloth/* GGUF repos, else Q4_K_M.",
)
_CONTEXT_OPTION = typer.Option(
0,
"--max-seq-length",
"--context-length",
rich_help_panel = _PANEL_MODEL,
help = "Context length in tokens for the load (0 = model default).",
)
_LOAD_4BIT_OPTION = typer.Option(
True,
"--load-in-4bit/--no-load-in-4bit",
rich_help_panel = _PANEL_MODEL,
help = "Load hub models in 4-bit (ignored for GGUF).",
)
_TENSOR_PARALLEL_OPTION = typer.Option(
False,
"--tensor-parallel/--no-tensor-parallel",
rich_help_panel = _PANEL_MODEL,
help = "Split a GGUF across GPUs by tensor instead of by layer (multi-GPU only).",
)
_GPU_MEMORY_MODE_OPTION = typer.Option(
None,
"--gpu-memory-mode",
rich_help_panel = _PANEL_MODEL,
help = (
"GPU memory strategy for GGUF models loaded by this command. Auto lets "
"Unsloth manage placement. Manual with default layers and context delegates "
"placement and sizing to llama.cpp --fit. Omit when attaching to preserve "
"the running model's mode."
),
)
# Server knobs. Tool flags only configure a server `unsloth start` auto-starts (--serve); reasoning rides in the agent's own config where it can.
_SERVE_OPTION = typer.Option(
True,
"--serve/--no-serve",
rich_help_panel = _PANEL_SERVER,
help = "If no Unsloth server is running, auto-start one for --model and keep it "
"available after the agent exits. --no-serve errors out instead.",
)
_ENABLE_TOOLS_OPTION = typer.Option(
None,
"--enable-tools/--disable-tools",
rich_help_panel = _PANEL_SERVER,
help = "Server-side tools (web search, code execution) for the auto-started server. "
"Default off so the agent's own tools are relayed unchanged.",
)
_TOOL_CALL_HEALING_OPTION = typer.Option(
None,
"--enable-tool-call-healing/--disable-tool-call-healing",
rich_help_panel = _PANEL_SERVER,
help = "Promote text-form tool calls from small GGUFs back into structured calls. On by "
"default; when the flag is omitted an inherited UNSLOTH_DISABLE_TOOL_CALL_HEALING is kept.",
)
_TOOL_CALL_NUDGING_OPTION = typer.Option(
None,
"--enable-tool-call-nudging/--disable-tool-call-nudging",
rich_help_panel = _PANEL_SERVER,
help = "Retry once with a nudge when a non-streaming passthrough tool call can't be healed. "
"On by default; when the flag is omitted an inherited UNSLOTH_TOOL_CALL_NUDGE is kept.",
)
_REASONING_OPTION = typer.Option(
None,
"--reasoning",
rich_help_panel = _PANEL_SERVER,
help = (
"Reasoning mode for this agent session. Defaults to auto so the model's chat "
"template decides; use 'on' or 'off' to override it."
),
)
_REASONING_EFFORT_OPTION = typer.Option(
None,
"--reasoning-effort",
rich_help_panel = _PANEL_SERVER,
help = (
"Reasoning effort for this agent session, e.g. 'medium'. The "
"levels are the model's own, so pass one its chat template accepts. Default: "
"unset, which keeps the template's level."
),
)
# Sampling overrides ride in the agent's own config, so only this session uses them; one the agent cannot send pins the auto-started server instead. Default unset means the model's recommended sampling is used.
_TEMPERATURE_OPTION = typer.Option(
None,
"--temperature",
min = 0.0,
max = 2.0,
rich_help_panel = _PANEL_SAMPLING,
help = "Pin the sampling temperature. Default: unset (per-model recommendation).",
)
_TOP_P_OPTION = typer.Option(
None,
"--top-p",
min = 0.0,
max = 1.0,
rich_help_panel = _PANEL_SAMPLING,
help = "Pin top-p (nucleus) sampling. Default: unset (per-model recommendation).",
)
_TOP_K_OPTION = typer.Option(
None,
"--top-k",
min = -1,
max = 100,
rich_help_panel = _PANEL_SAMPLING,
help = "Pin top-k sampling. Default: unset (per-model recommendation).",
)
_MIN_P_OPTION = typer.Option(
None,
"--min-p",
min = 0.0,
max = 1.0,
rich_help_panel = _PANEL_SAMPLING,
help = "Pin min-p sampling threshold. Default: unset (per-model recommendation).",
)
_REPETITION_PENALTY_OPTION = typer.Option(
None,
"--repetition-penalty",
min = 1.0,
max = 2.0,
rich_help_panel = _PANEL_SAMPLING,
help = "Pin the repetition penalty. Default: unset (per-model recommendation).",
)
_PRESENCE_PENALTY_OPTION = typer.Option(
None,
"--presence-penalty",
min = 0.0,
max = 2.0,
rich_help_panel = _PANEL_SAMPLING,
help = "Pin the presence penalty. Default: unset (per-model recommendation).",
)
_MAX_TOKENS_OPTION = typer.Option(
None,
"--max-tokens",
min = 1,
rich_help_panel = _PANEL_SAMPLING,
help = (
"Most tokens the agent may generate in one response. Default: a quarter of the "
"context window, up to 32,000. Capped at half the window so the conversation "
"keeps room."
),
)
# Agent-session knobs.
_KEY_OPTION = typer.Option(
None,
"--api-key",
envvar = "UNSLOTH_API_KEY",
rich_help_panel = _PANEL_SESSION,
help = "Unsloth API key. For a local Unsloth it is minted automatically and "
"remembered per server. For a remote server, pass one with --api-key "
"(or UNSLOTH_API_KEY); it is remembered for next time.",
)
_LAUNCH_OPTION = typer.Option(
True,
"--launch/--no-launch",
rich_help_panel = _PANEL_SESSION,
help = "--no-launch prints the env and command instead (remote shells, WSL).",
)
# One normalized "run tools without prompting" switch. Each agent spells this differently and it is easy to forget which is which, so accept every spelling and route to the agent's own mechanism in _yolo_command_flags / the config writers.
_YOLO_OPTION = typer.Option(
False,
"--yolo",
"--dangerously-skip-permissions",
"--dangerously-bypass-approvals-and-sandbox",
rich_help_panel = _PANEL_SESSION,
help = "Auto-approve all tool actions for this session; routed to the agent's own "
"flag/config. Any of the three spellings works for any agent.",
)
_PERSIST_OPTION = typer.Option(
False,
"--persist/--no-persist",
rich_help_panel = _PANEL_SESSION,
help = (
"Keep this agent's Unsloth-managed session dir so you can resume it later. "
"codex/openclaw/hermes/pi/dsh have their whole home relocated into an Unsloth dir "
"that is a throwaway temp dir (wiped on exit) by default; with --persist it "
"lives under the Unsloth agents dir and survives, so their own resume can reopen "
"it. claude and opencode keep sessions in your own stores (~/.claude, "
"~/.local/share/opencode), so they already resume regardless. To reopen a "
"session, pass the agent's own resume command through, e.g. "
"`unsloth start codex --persist resume` or `claude --resume <id>`; those flow to "
"the agent unchanged."
),
)
_AS_SUBAGENT_OPTION = typer.Option(
False,
"--as-subagent",
rich_help_panel = _PANEL_SESSION,
help = "Keep the coding agent's current model and add Unsloth as a local subagent.",
)
_AUTO_ROUTE_OPTION = typer.Option(
False,
"--auto-route",
rich_help_panel = _PANEL_SESSION,
help = "Keep the agent's current model and let it hand routine, self-contained work to a "
"local Unsloth subagent without being asked.",
)
_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 = {
"claude": ["--dangerously-skip-permissions"],
"codex": ["--dangerously-bypass-approvals-and-sandbox"],
"hermes": ["--yolo"],
# Pi never prompts per tool call; its only approval gate is project trust, so -a (trust project resources) is the closest "do not ask me" equivalent.
"pi": ["--approve"],
"vibe": ["--auto-approve"],
}
def _yolo_command_flags(agent: str, yolo: bool) -> list:
# .get so a config-based agent (or a typo) yields no flag instead of a KeyError.
return _YOLO_COMMAND_FLAGS.get(agent, []) if yolo else []
# Subcommands that reject --auto (OpenCode exposes it only on the default TUI and `run`), so `opencode serve --auto` is never emitted. Includes console/generate, hidden from `opencode --help` but still registered. Unknown first positionals are TUI paths and get --auto.
_OPENCODE_NON_AUTO_SUBCOMMANDS = frozenset(
"completion acp mcp attach debug providers auth agent upgrade uninstall serve web "
"models stats export import github pr session plugin plug db console generate".split()
)
_OPENCODE_V2_SUBCOMMANDS = frozenset(
"acp api debug console auth mcp plugin models export import mini run service pair serve".split()
)
_OPENCODE_V2_STANDALONE_SUBCOMMANDS = frozenset("api models export import mini run".split())
_OPENCODE_GLOBAL_BOOLEAN_OPTIONS = frozenset(
"-h --help -v --version --print-logs --pure --mdns --standalone --wizard".split()
)
_OPENCODE_GLOBAL_VALUE_OPTIONS = frozenset(
"--log-level --port --hostname --mdns-domain --cors --server --completions --cpu-profile".split()
)
_OPENCODE_NATIVE_AUTO_MIN_VERSION = (1, 17, 12)
def _opencode_version(executable: str) -> Optional[tuple[int, int, int]]:
try:
output = subprocess.check_output(
[executable, "--version"],
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 10,
stderr = subprocess.DEVNULL,
env = _probe_env(),
)
except Exception:
return None
match = re.search(r"(\d+)\.(\d+)\.(\d+)", output)
return tuple(int(part) for part in match.groups()) if match else None
def _opencode_command() -> tuple[str, bool]:
resolved_v2 = _which_with_install_dirs("opencode2")
if resolved_v2:
return resolved_v2, True
# Distro packages (Arch extra, opencode-beta) ship V2 as plain `opencode`, which rejects V1's --model flag.
resolved = _which_with_install_dirs("opencode")
version = _opencode_version(resolved) if resolved else None
return "opencode", bool(version) and version[0] >= 2
def _opencode_supports_native_auto(command: str = "opencode") -> bool:
if Path(command).stem.lower() == "opencode2":
return True
executable = _which_with_install_dirs(command)
if executable is None:
# No local binary: a --no-launch recipe may run elsewhere, and _run installs the current release on launch, so either way assume native --auto is available.
return True
version = _opencode_version(executable)
return bool(version) and version >= _OPENCODE_NATIVE_AUTO_MIN_VERSION
def _opencode_subcommand(args: list[str]) -> tuple[Optional[str], Optional[int]]:
"""Return an explicit OpenCode subcommand and its index after global options."""
index = 0
while index < len(args):
arg = args[index]
if arg == "--":
return None, None
if arg in _OPENCODE_GLOBAL_BOOLEAN_OPTIONS:
index += 1
continue
if arg in _OPENCODE_GLOBAL_VALUE_OPTIONS:
index += 2
continue
if any(arg.startswith(f"{option}=") for option in _OPENCODE_GLOBAL_VALUE_OPTIONS):
index += 1
continue
# A non-global option (--session) is a TUI flag; stop before its value is mistaken for a subcommand.
if arg.startswith("-"):
return None, None
return arg, index
return None, None
def _opencode_native_auto_args(
args: list[str],
yolo: bool,
*,
v2: bool = False,
) -> tuple[list[str], bool]:
"""Add OpenCode's native --auto when the selected command supports it."""
routed = list(args)
if not yolo:
return routed, False
subcommand, _ = _opencode_subcommand(routed)
if v2 and subcommand in _OPENCODE_V2_SUBCOMMANDS and subcommand != "run":
return routed, False
if not v2 and subcommand in _OPENCODE_NON_AUTO_SUBCOMMANDS:
return routed, False
separator = routed.index("--") if "--" in routed else len(routed)
# --mini's runMini TUI forces auto=false and never forwards --auto, so appending it is useless; fall back to the config permission block so --yolo still auto-approves.
if any(arg == "--mini" or arg.startswith("--mini=") for arg in routed[:separator]):
return routed, False
if "--auto" not in routed[:separator]:
routed.insert(separator, "--auto")
return routed, True
def _opencode_v2_standalone_args(args: list[str]) -> list[str]:
"""Keep session-only config on the V2 server that consumes it."""
routed = list(args)
separator = routed.index("--") if "--" in routed else len(routed)
head = routed[:separator]
if (
"--standalone" in head
or "--server" in head
or any(arg.startswith("--server=") for arg in head)
):
return routed
subcommand, subcommand_index = _opencode_subcommand(routed)
if (
subcommand in _OPENCODE_V2_SUBCOMMANDS
and subcommand not in _OPENCODE_V2_STANDALONE_SUBCOMMANDS
):
return routed
insert_at = (
subcommand_index + 1 if subcommand in _OPENCODE_V2_STANDALONE_SUBCOMMANDS else separator
)
routed.insert(insert_at, "--standalone")
return routed
def _hermes_install_hint() -> str:
return _HERMES_WINDOWS_INSTALL_HINT if os.name == "nt" else _HERMES_POSIX_INSTALL_HINT
def _vibe_install_hint() -> str:
return _VIBE_WINDOWS_INSTALL_HINT if os.name == "nt" else _VIBE_POSIX_INSTALL_HINT
def _npm_install_hint(
package: str,
*,
ignore_scripts: bool = False,
prefix: Optional[Path] = None,
) -> str:
parts = ["npm", "install", "-g"]
if prefix is not None:
parts.extend(("--prefix", str(prefix)))
elif os.name != "nt":
# No home (bare container UID): fall back to npm's own prefix instead of failing.
try:
parts.extend(("--prefix", str(Path.home() / ".local")))
except (RuntimeError, OSError):
pass
if ignore_scripts:
parts.append("--ignore-scripts")
parts.append(package)
if os.name == "nt":
return " ".join(_powershell_quote(part) for part in parts)
return shlex.join(parts)
def _hermes_resume_oneshot_args(args: list[str]) -> list[str]:
"""Route resumed one-shot prompts through Hermes' session-aware chat command."""
has_resume = any(
arg in ("--resume", "-r", "--continue", "-c")
or arg.startswith(("--resume=", "--continue="))
or (len(arg) > 2 and arg.startswith(("-r", "-c")))
for arg in args
)
if not has_resume:
return args
rewritten = list(args)
for index, arg in enumerate(rewritten):
if arg in ("-z", "--oneshot"):
rewritten[index] = "-q"
elif len(arg) > 2 and arg.startswith("-z"):
# argparse accepts attached short-option values (`-zPROMPT` and `-z=PROMPT`); preserve the value byte-for-byte when switching to -q.
rewritten[index] = f"-q{arg[2:]}"
elif arg.startswith("--oneshot="):
rewritten[index] = f"--query={arg.partition('=')[2]}"
else:
continue
if any(item == "--usage-file" or item.startswith("--usage-file=") for item in args):
raise typer.BadParameter(
"Hermes cannot resume a one-shot session with --usage-file; remove that option."
)
# `chat -Q -q` is the only mode that can resume a session, but it does not inherit hermes' one-shot approval semantics: `-z` itself sets HERMES_YOLO_MODE=1 and HERMES_ACCEPT_HOOKS=1 for the call, because a one-shot has no user at the terminal to answer a prompt. Re-add the equivalent flags so a resumed `-z` keeps behaving like a plain `-z` instead of stalling on an approval nobody can answer. This is parity with the flag the user already typed, not the --yolo option: a resumed INTERACTIVE session still prompts as usual.
prefix = ["chat", "-Q"]
if "--yolo" not in rewritten:
prefix.append("--yolo")
if "--accept-hooks" not in rewritten:
prefix.append("--accept-hooks")
rewritten = prefix + rewritten
return rewritten
return args
_DSH_LAUNCHER_ARGS = frozenset(
"--profile --patch --dump-config --dump-default-config -V --version plugin web".split()
)
# Launcher invocations that boot no profile, so they take no --patch overlay.
_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 ""
# 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]
if patch is not None and command[1] not in _DSH_NO_PROFILE_ARGS:
# dsh name expands to --profile name only when the name comes first, so put the overlay after a bare name and before any leading option.
at = 1 if command[1].startswith("-") else 2
command[at:at] = ["--patch", patch]
return command
class LoadOptions(NamedTuple):
"""Model-load knobs forwarded to /api/inference/load when --model triggers a load."""
gguf_variant: Optional[str] = None
max_seq_length: int = 0
load_in_4bit: bool = True
tensor_parallel: bool = False
gpu_memory_mode: Optional[Literal["auto", "manual"]] = None
# Names the user actually typed: --context-length 0 equals the declared default yet is a reset the server must hear. Appended last to keep positional callers working.
supplied: frozenset = frozenset()
def overrides(self) -> frozenset:
"""Fields that must reach the load: typed explicitly, or differing from default."""
differing = {
name
for name, default in (
("gguf_variant", None),
("max_seq_length", 0),
("load_in_4bit", True),
("tensor_parallel", False),
("gpu_memory_mode", None),
)
if getattr(self, name) != default
}
# Internal callers never populate `supplied`, so a non-default value counts too.
return frozenset(differing) | frozenset(self.supplied)
_LOAD_OPTION_PARAMS = (
"gguf_variant",
"max_seq_length",
"load_in_4bit",
"tensor_parallel",
"gpu_memory_mode",
)
def _supplied_load_params(ctx) -> frozenset:
"""Which load knobs Click saw on the command line. The context must be PASSED IN: Typer invokes callbacks with no active click context, so click.get_current_context() is None. Unaskable gives an empty set, and `overrides()` falls back to comparing values."""
getter = getattr(ctx, "get_parameter_source", None)
if getter is None:
return frozenset()
supplied = set()
for name in _LOAD_OPTION_PARAMS:
try:
source = getter(name)
except Exception:
continue
# By member NAME, not identity or ordering: Typer vendors its own click, so this is typer._click's ParameterSource, and click 8.3 reordered the IntEnum.
if getattr(source, "name", None) == "COMMANDLINE":
supplied.add(name)
return frozenset(supplied)
def _load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
) -> LoadOptions:
"""Build LoadOptions for an agent command, recording what was typed."""
return LoadOptions(
gguf_variant,
max_seq_length,
load_in_4bit,
tensor_parallel,
gpu_memory_mode,
_supplied_load_params(ctx),
)
class ServerOptions(NamedTuple):
"""Start flags: carried fields ride in the agent's requests; the rest configure an auto-started server."""
enable_tools: Optional[bool] = None
tool_call_healing: Optional[bool] = None
tool_call_nudging: Optional[bool] = None
reasoning: Optional[Literal["on", "off", "auto"]] = None
reasoning_effort: Optional[str] = None
temperature: Optional[float] = None
top_p: Optional[float] = None
top_k: Optional[int] = None
min_p: Optional[float] = None
repetition_penalty: Optional[float] = None
presence_penalty: Optional[float] = None
# Fields the agent's own config sends with each request, kept off the server.
carried: frozenset = frozenset()
# Carried fields with a value: an inherited UNSLOTH_SAMPLING_* pin would override them.
unpinned: frozenset = frozenset()
def sent_by_agent(self) -> frozenset:
# A request cannot ask for the template default back, so auto stays a server setting.
unsent = {"reasoning"} if self.reasoning == "auto" else set()
if self.reasoning_effort not in _STUDIO_REASONING_EFFORTS:
unsent.add("reasoning_effort")
return self.carried - unsent
def request_body(self) -> dict:
sent = self.sent_by_agent()
body = {
name: getattr(self, name)
for name in _SAMPLING_FIELDS
if name in sent and getattr(self, name) is not None
}
if "reasoning" in sent and self.reasoning in ("on", "off"):
body["enable_thinking"] = self.reasoning == "on"
if "reasoning_effort" in sent:
body["reasoning_effort"] = self.reasoning_effort
return body
_SAMPLING_FIELDS = (
"temperature",
"top_p",
"top_k",
"min_p",
"repetition_penalty",
"presence_penalty",
)
_REASONING_FIELDS = frozenset({"reasoning", "reasoning_effort"})
_ALL_REQUEST_FIELDS = frozenset(_SAMPLING_FIELDS) | _REASONING_FIELDS
_REQUEST_BODY_KEYS = (*_SAMPLING_FIELDS, "enable_thinking", "reasoning_effort")
_STUDIO_REASONING_EFFORTS = ("none", "minimal", "low", "medium", "high", "max", "xhigh")
_CODEX_REASONING_EFFORTS = ("none", "minimal", "low", "medium", "high", "xhigh")
def _codex_reasoning_effort(
reasoning: Optional[str], reasoning_effort: Optional[str]
) -> Optional[str]:
if reasoning == "off":
return "none"
if reasoning_effort in _CODEX_REASONING_EFFORTS:
return reasoning_effort
return None
def _merge_request_body(container: dict, key: str, body: dict) -> None:
current = container.get(key)
current = (
{k: v for k, v in current.items() if k not in _REQUEST_BODY_KEYS}
if isinstance(current, dict)
else {}
)
current.update(body)
if current:
container[key] = current
else:
container.pop(key, None)
def _split_repo_variant(model: str) -> tuple:
"""Split ``org/name:QUANT`` into ``("org/name", "QUANT")``. ``unsloth run`` and llama.cpp accept ``--model org/name:QUANT`` as shorthand for ``--model org/name --gguf-variant QUANT``, so mirror that here and a ``:variant`` suffix resolves against the already-loaded ``org/name`` (which the loaded listing shows without the suffix) instead of trying to load a repo id containing ``:``, which Hugging Face rejects and which would evict a model another session is using. Local paths, Windows drive letters and ids without a ``:`` pass through unchanged."""
s = (model or "").strip()
if not s or s.startswith(("/", "./", "../", "~")) or s == ".":
return s, None
if len(s) >= 2 and s[1] == ":" and s[0].isalpha(): # Windows drive, e.g. C:\models\x
return s, None
if ":" not in s:
return s, None
repo, _, variant = s.rpartition(":")
if not repo or not variant or "/" in variant:
return s, None
return repo, variant
def _looks_like_model(token: str) -> bool:
"""True for a bare `org/name(:variant)` hub id that is not a flag or a local path. Reuses `_is_hub_model_id`, so a relative dir like `owner/repo` that actually exists is left for the agent instead of being taken as a model; a non-existent `org/name` is treated as a hub id."""
if not token or token.startswith("-") or " " in token:
return False
repo, _ = _split_repo_variant(token)
return _is_hub_model_id(repo)
def _consume_positional_model(model: Optional[str], args: list) -> tuple:
"""Route a leading `org/name` positional to --model when --model was not given. Only the FIRST token is considered so an option value like `--profile owner/repo` is never stolen, and only when --model is absent so an explicit --model always wins. Returns (model, remaining_args) with the consumed token removed from the passthrough."""
args = list(args)
if model or not args or not _looks_like_model(args[0]):
return model, args
return args[0], args[1:]
def _display_model_spec(model: str, variant: Optional[str]) -> str:
"""Return a user-facing model name that includes the selected GGUF variant."""
repo, inline_variant = _split_repo_variant(model)
selected_variant = variant or inline_variant
return f"{repo}:{selected_variant}" if selected_variant else model
def _model_status(
base: str,
key: str,
model_id: Optional[str] = None,
) -> dict:
# Studio serving several models answers for the one serving model_id; an older one ignores it.
query = f"?{urlencode({'model': model_id})}" if model_id else ""
return _http_json("GET", f"{base}/api/inference/status{query}", key)
def _subagent_model_id(
base: str,
key: str,
entry: dict,
requested_model: Optional[str],
requested_variant: Optional[str],
) -> str:
"""Return an API model id that preserves the selected GGUF variant. Coding-agent model definitions outlive the initial load, so if Unsloth later unloads the model a bare repository id may resolve to a different cached quant; include the explicit or currently loaded variant so an automatic reload selects the same weights."""
model_id = str(entry["id"])
_, inline_variant = _split_repo_variant(requested_model or "")
variant = requested_variant or inline_variant
if not variant:
try:
status = _model_status(base, key, model_id)
except Exception:
status = {}
typer.echo(
"Warning: could not verify the loaded GGUF variant; a later reload "
"may pick a different cached quant. Pass :variant to pin it.",
err = True,
)
if status.get("is_gguf"):
variant = status.get("gguf_variant")
elif _MLX_PRECISION_FOLDER_RE.fullmatch(str(variant).strip()):
# The API resolves no :folder suffix for an MLX resident (bf16 reads as a GGUF quant), so pin nothing.
try:
if _model_status(base, key, model_id).get("is_mlx"):
variant = None
except Exception:
pass
if variant and _is_hub_model_id(model_id):
return _display_model_spec(model_id, str(variant))
if variant:
# A path load is advertised as a bare basename with no ":variant" channel, so the quant cannot be recorded and a later reload picks for itself.
typer.echo(
f"Warning: {model_id} loaded from a path, so the subagent config cannot "
f"pin the {variant} quant; a reload may choose a different one. Load the "
"model by repository id to pin it.",
err = True,
)
return model_id
def _fail(message: str) -> NoReturn:
typer.echo(message, err = True)
raise typer.Exit(code = 1)
def _reject_as_subagent(agent: str, args: list) -> None:
# Reject early, or the flag reaches the agent binary after Unsloth loaded the model.
if any(arg == "--as-subagent" or arg.startswith("--as-subagent=") for arg in args):
_fail(f"--as-subagent is not supported for {agent}.")
_reject_auto_route(agent, args)
def _reject_auto_route(agent: str, args: list) -> None:
if any(arg == "--auto-route" or arg.startswith("--auto-route=") for arg in args):
_fail(f"--auto-route is not supported for {agent}.")
def _http_error_detail(exc: urllib.error.HTTPError) -> str:
try:
body = json.loads(exc.read().decode())
return body.get("detail") or body["error"]["message"]
except Exception:
return str(exc)
def _fail_request(exc: Exception, error: str) -> NoReturn:
"""Fail with `error` plus whatever the server or the transport gave as a reason."""
if isinstance(exc, urllib.error.HTTPError):
_fail(f"{error}: {_http_error_detail(exc)}")
_fail(f"{error}: {getattr(exc, 'reason', None) or exc}")
def _http_json(
method: str,
url: str,
token: str,
payload = None,
timeout = 30,
error = None,
):
"""On a failed request: raise if `error` is None, else fail with `error` plus the reason."""
request = urllib.request.Request(
url,
data = None if payload is None else json.dumps(payload).encode(),
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"User-Agent": _USER_AGENT,
},
method = method,
)
try:
# No redirects: a 3xx would leak this bearer token to an unvetted base.
with urlopen_no_redirect(request, timeout = timeout) as response:
body = json.loads(response.read().decode() or "{}")
# A padded /load or /unload commits its 200 early, so a late failure arrives in-band; raise it as the HTTPError handled below.
return raise_for_deferred_error(url, body)
except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
if error is None:
raise
_fail_request(exc, error)
# A server that WE auto-started (never one we merely found). Kept at module scope so failure paths and the atexit backstop can tear it down without threading a handle through all six agent commands. Only one agent runs per process, so one slot is enough.
_auto_served_server: Optional[subprocess.Popen] = None
# Caps time since the download last advanced, not total elapsed.
_SERVER_START_TIMEOUT_S = 900
_DOWNLOAD_POLL_INTERVAL_S = 1.0
# Ceiling on the doubling back-off the progress reader uses after a polling error.
_DOWNLOAD_POLL_MAX_BACKOFF_S = 60.0
# How often the progress reader re-lists the repos a load announced; each listed repo costs a cache scan per poll.
_LOAD_DOWNLOAD_LIST_INTERVAL_S = 5.0
_START_API_KEY_PREFIX = "UNSLOTH_START_API_KEY: "
_START_PORT_PREFIX = "UNSLOTH_START_PORT: "
_START_API_KEY_MARKER_ENV = "_UNSLOTH_START_API_KEY_MARKER"
def _format_download_bytes(value: int) -> str:
value = max(0, int(value))
for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
if value < 1024 or unit == "TiB":
precision = 0 if unit in ("B", "KiB") else 1
return f"{value:.{precision}f} {unit}"
value /= 1024
return "0 B"
def _format_download_eta(seconds: float) -> str:
seconds = max(0, int(seconds))
if seconds < 60:
return f"{seconds}s"
minutes, seconds = divmod(seconds, 60)
if minutes < 60:
return f"{minutes}m {seconds:02d}s"
hours, minutes = divmod(minutes, 60)
return f"{hours}h {minutes:02d}m"
class _DownloadProgressDisplay:
"""Render download progress without making redirected output noisy."""
def __init__(self) -> None:
self._samples: list[tuple[float, int]] = []
self._shown = False
self._last_bucket = -1
self._last_line_length = 0
self._last_expected = 0
self._source: Optional[str] = None
self._interactive = bool(getattr(sys.stdout, "isatty", lambda: False)())
def update(
self,
progress: dict,
source: Optional[str] = None,
) -> None:
if source != self._source:
# A new repo is a new transfer; else redirected output (prints only on a rising bucket) stays silent for a base that starts after the adapter finished.
self._source = source
self._samples.clear()
self._last_expected = 0
# Keep `_shown`: `complete()` and `close()` gate on it.
self._last_bucket = -1
downloaded = max(0, int(progress.get("downloaded_bytes") or 0))
completed = max(0, int(progress.get("completed_bytes") or 0))
expected = max(0, int(progress.get("expected_bytes") or 0))
self._last_expected = max(self._last_expected, expected)
fraction = float(progress.get("progress") or 0)
if downloaded <= 0:
return
# A fully cached snapshot can report 99% with no incomplete bytes; that is not a transfer, so do not show it as a download.
if completed >= downloaded > 0:
return
now = time.monotonic()
if self._samples and downloaded < self._samples[-1][1]:
self._samples.clear()
self._samples.append((now, downloaded))
cutoff = now - 15.0
while len(self._samples) > 2 and self._samples[0][0] < cutoff:
self._samples.pop(0)
rate = 0.0
if len(self._samples) >= 2:
elapsed = self._samples[-1][0] - self._samples[0][0]
delta = self._samples[-1][1] - self._samples[0][1]
if elapsed >= 1.0 and delta > 0:
rate = delta / elapsed
if expected > 0:
# The endpoint caps at 99% while bytes remain in an incomplete file; trust it.
fraction = min(1.0, max(0.0, fraction))
percent = min(100, max(0, int(fraction * 100)))
filled = min(24, int(fraction * 24))
bar = "=" * filled + ">" + "." * max(0, 23 - filled) if filled < 24 else "=" * 24
line = (
f"Downloading model [{bar}] {percent:3d}% "
f"{_format_download_bytes(downloaded)} / {_format_download_bytes(expected)}"
)
bucket = percent // 10
if rate > 0:
line += f" | {_format_download_bytes(rate)}/s"
if downloaded < expected:
line += f" | ETA {_format_download_eta((expected - downloaded) / rate)}"
else:
line = f"Downloading model: {_format_download_bytes(downloaded)}"
bucket = downloaded // (1024**3)
if rate > 0:
line += f" | {_format_download_bytes(rate)}/s"
if self._interactive:
padding = " " * max(0, self._last_line_length - len(line))
typer.echo(f"\r{line}{padding}", nl = False)
sys.stdout.flush()
self._last_line_length = len(line)
elif not self._shown or bucket > self._last_bucket:
typer.echo(line)
self._last_bucket = bucket
self._shown = True
def close(self) -> None:
if self._interactive and self._shown:
typer.echo()
self._last_line_length = 0
def complete(self) -> None:
"""Finish a displayed transfer after the model load confirms success."""
if not self._shown:
return
downloaded = self._samples[-1][1] if self._samples else 0
expected = max(downloaded, getattr(self, "_last_expected", 0))
self.update(
{
"downloaded_bytes": expected,
"expected_bytes": expected,
"progress": 1.0,
}
)
def _normalized_variant(value: object) -> str:
return re.sub(r"[^a-z0-9]", "", str(value or "").lower())
class _ModelDownloadProgress:
"""Best-effort polling of the model download endpoints."""
def __init__(self, base: str, key: str, model: str, variant: Optional[str]) -> None:
self._base = base
self._key = key
self._model = model
self._variant = variant or ""
self._expected_bytes = 0
self._downloaded_bytes = 0
self._failures = 0
self._retry_at = 0.0
self._display = _DownloadProgressDisplay()
self._configured = False
# A local model has no Hub reading of its own, but a remote base it names is still listed.
self._disabled = not _is_hub_model_id(model)
self._progress_prefix = "/api/hub"
# Repos the load announced (its base, the base the loader substitutes): bytes summed for liveness.
self._repo_bytes: dict[str, int] = {}
self._companions: list[str] = []
self._finished: dict[
str, dict
] = {} # Complete companions: final reading kept, never re-read.
self._listed_at: Optional[float] = None
self._active_repo = model
def _is_gguf(self) -> bool:
return bool(self._variant) or "gguf" in self._model.lower()
def _configure(self) -> None:
self._configured = True
if self._disabled:
return
# GGUF repos need the selected quant's size; the repo endpoint totals every quant. Resolve the variant first, otherwise show bytes only.
if self._is_gguf():
try:
params = urlencode({"repo_id": self._model})
try:
info = _http_json(
"GET",
f"{self._base}/api/hub/gguf-variants?{params}",
self._key,
timeout = 10,
)
except urllib.error.HTTPError as exc:
if exc.code != 404:
raise
self._progress_prefix = "/api/models"
info = _http_json(
"GET",
f"{self._base}/api/models/gguf-variants?{params}",
self._key,
timeout = 10,
)
self._variant = self._variant or str(info.get("default_variant") or "")
wanted = _normalized_variant(self._variant)
for item in info.get("variants") or []:
quant = _normalized_variant(item.get("quant"))
filename = _normalized_variant(item.get("filename"))
if wanted and (wanted == quant or wanted in filename):
self._expected_bytes = int(
item.get("download_size_bytes") or item.get("size_bytes") or 0
)
break
except Exception:
# Older servers lack this endpoint; byte progress is still useful.
pass
def _companion_repos(self) -> list[str]:
now = time.monotonic()
if self._listed_at is not None and now - self._listed_at < _LOAD_DOWNLOAD_LIST_INTERVAL_S:
return self._companions
self._listed_at = now
try:
url = f"{self._base}{self._progress_prefix}/active-downloads"
listing = _http_json("GET", url, self._key, timeout = 10)
except urllib.error.HTTPError as exc:
if exc.code == 404:
self._listed_at = float("inf") # Older server: no load-owned jobs to find.
return self._companions
except Exception:
return self._companions
for item in listing.get("downloads") or []:
repo = str(item.get("repo_id") or "")
if not (item.get("owner") == "load" or item.get("load_attached")):
continue
if repo and repo.lower() != self._model.lower() and repo not in self._companions:
self._companions.append(repo)
return self._companions
def _read(
self,
repo: str,
gguf: bool = False,
) -> dict:
if gguf:
params = urlencode(
{"repo_id": repo, "variant": self._variant, "expected_bytes": self._expected_bytes}
)
url = f"{self._base}{self._progress_prefix}/gguf-download-progress?{params}"
else:
params = urlencode({"repo_id": repo})
url = f"{self._base}{self._progress_prefix}/download-progress?{params}"
return _http_json("GET", url, self._key, timeout = 10)
def poll(self) -> None:
if not self._configured:
self._configure()
if time.monotonic() < self._retry_at:
return
try:
readings = {}
try:
if not self._disabled:
readings[self._model] = self._read(self._model, gguf = self._is_gguf())
except urllib.error.HTTPError as exc:
if exc.code != 404 or self._progress_prefix == "/api/models":
raise
self._progress_prefix = "/api/models"
self.poll()
return
for repo in self._companion_repos():
if repo in self._finished:
readings[repo] = self._finished[repo]
continue
try:
readings[repo] = item = self._read(repo)
except Exception:
continue
if (
0
< int(item.get("expected_bytes") or 0)
<= int(item.get("completed_bytes") or 0)
):
self._finished[repo] = item
# The line follows whichever repo grew most; a repo first seen already large (a cached base) has not grown.
growth = 0
for repo, item in readings.items():
current = max(0, int(item.get("downloaded_bytes") or 0))
if current - self._repo_bytes.get(repo, current) > growth:
growth, self._active_repo = current - self._repo_bytes[repo], repo
# Only ever rises, so a dip and recovery never counts as fresh growth.
self._repo_bytes[repo] = max(self._repo_bytes.get(repo, 0), current)
self._downloaded_bytes = max(self._downloaded_bytes, sum(self._repo_bytes.values()))
self._failures = 0
self._retry_at = 0.0
active = self._active_repo if self._active_repo in readings else self._model
if active in readings:
self._display.update(readings[active], active)
except Exception:
# downloaded_bytes drives _start_studio_server liveness: back off on failure but never stop probing, or the download it protects dies.
self._failures += 1
self._retry_at = time.monotonic() + min(
2.0**self._failures, _DOWNLOAD_POLL_MAX_BACKOFF_S
)
@property
def downloaded_bytes(self) -> int:
return self._downloaded_bytes
def close(self) -> None:
self._display.close()
def complete(self) -> None:
self._display.complete()
def _load_model_with_progress(
base: str, key: str, model: str, load: LoadOptions, payload: dict
) -> dict:
"""Run the blocking load request while polling its download progress."""
load_url = f"{base}/api/inference/load"
result: list[tuple[bool, object]] = []
done = threading.Event()
def _load() -> None:
try:
value = _http_json(
"POST",
load_url,
key,
payload,
timeout = 3600,
error = "Model load failed",
)
result.append((True, value))
except BaseException as exc:
result.append((False, exc))
finally:
done.set()
threading.Thread(target = _load, name = "unsloth-model-load", daemon = True).start()
progress = _ModelDownloadProgress(base, key, model, load.gguf_variant)
loading_announced = False
try:
while not done.wait(_DOWNLOAD_POLL_INTERVAL_S):
if not loading_announced:
typer.echo(f"Loading model: {_display_model_spec(model, load.gguf_variant)}")
loading_announced = True
progress.poll()
ok, value = result[0]
if not ok:
assert isinstance(value, BaseException)
# A pad-only or half-written body fails `_http_json`'s json.loads: report the padded 200 that never completed, not a JSON error from the API.
if isinstance(value, ValueError):
require_completed_padded_body(load_url, None)
raise value
progress.complete()
# `_http_json` decodes a blank body as `{}`, which would look like a completed load.
return require_completed_padded_body(load_url, value)
finally:
progress.close()
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 urlopen_local(request, timeout = timeout) as response:
return json.loads(response.read(65536).decode() or "{}").get("status") == "healthy"
except Exception:
return False
def _read_log(path: Path) -> str:
try:
return path.read_text(encoding = "utf-8", errors = "replace")
except OSError:
return "(no server log)"
def _log_tail(path: Path, lines: int = 20) -> str:
return "\n".join(_read_log(path).splitlines()[-lines:])
def _redacted_log_tail(path: Path, lines: int = 20) -> str:
"""Tail with minted keys removed; only for tails shown on the terminal."""
return re.sub(r"sk-unsloth-\S+", "sk-unsloth-[redacted]", _log_tail(path, lines))
def _shutdown_server(server: Optional[subprocess.Popen]) -> None:
# Idempotent teardown of a server WE started, plus its own children (llama-server, cloudflared). A no-op once the process is already gone.
if server is None or server.poll() is not None:
return
if os.name == "nt":
# terminate()/kill() reach only the parent `unsloth run`; taskkill /T walks the whole tree so the llama-server child does not keep the port and GPU.
try:
subprocess.run(
["taskkill", "/PID", str(server.pid), "/T", "/F"],
capture_output = True,
timeout = 15,
check = False,
)
server.wait(timeout = 5)
except Exception:
with contextlib.suppress(Exception):
server.kill()
return
try:
os.killpg(os.getpgid(server.pid), signal.SIGTERM)
except OSError:
server.terminate()
try:
server.wait(timeout = 15)
except Exception:
try:
os.killpg(os.getpgid(server.pid), signal.SIGKILL)
except OSError:
server.kill()
def _shutdown_auto_served() -> None:
global _auto_served_server
server, _auto_served_server = _auto_served_server, None
if server is not None and server.poll() is None:
typer.echo("Stopping the auto-started Unsloth server…")
_shutdown_server(server)
def _keep_auto_served() -> bool:
"""Release ownership so a successfully started server survives this CLI."""
global _auto_served_server
server, _auto_served_server = _auto_served_server, None
atexit.unregister(_shutdown_auto_served)
return server is not None and server.poll() is None
def _start_studio_server(
base: str,
model: str,
load: LoadOptions,
server: ServerOptions = ServerOptions(),
) -> tuple:
"""Spawn `unsloth run` for `model`, wait until it is fully ready, and return (base, server)."""
global _auto_served_server
# This interpreter, not the `unsloth` on PATH: that can be missing, another install, or on Windows the denied unsloth.exe (#8490).
# Local import: unsloth_cli.commands.studio imports at package init after this module, so a top-level import would be circular.
from unsloth_cli.commands.studio import _managed_cli_argv
launch_head = _managed_cli_argv(Path(sys.executable))
parsed = urlparse(base)
# Tools default off means passthrough mode (relay the agent's own tools); --no-cloudflare means loopback only, no tunnel. Mirrors .github/scripts/serve-unsloth-run.sh. Healing/nudging travel via the child env below (version-agnostic) rather than new run flags that an older re-exec'd run could mistake for llama-server args.
command = [
*launch_head,
"run",
"-H",
parsed.hostname or "127.0.0.1",
"-p",
str(parsed.port or 8888),
"--enable-tools" if server.enable_tools else "--disable-tools",
"--no-cloudflare",
"--model",
model,
]
if load.gguf_variant:
command += ["--gguf-variant", load.gguf_variant]
if load.max_seq_length:
command += ["--context-length", str(load.max_seq_length)]
if not load.load_in_4bit:
command += ["--no-load-in-4bit"]
if load.tensor_parallel:
command += ["--tensor-parallel"]
if load.gpu_memory_mode is not None:
command += ["--gpu-memory-mode", load.gpu_memory_mode]
log_path = Path(tempfile.gettempdir()) / f"unsloth-start-server-{os.getpid()}.log"
typer.echo("Starting Unsloth server")
typer.echo(f"Model: {_display_model_spec(model, load.gguf_variant)}")
typer.echo(f"Server log: {log_path}")
# 0600: the `unsloth run` banner in this log carries the minted sk-unsloth- key, and the tempdir is world-traversable. Unlink first so a stale looser-mode file (pid reuse) cannot survive with its old permissions.
log_path.unlink(missing_ok = True)
log = os.fdopen(os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "wb")
# Own session/process group so a mid-session Ctrl+C (cancel a turn) does not reach the server. It survives a successful agent session; torn down on startup/launch failure.
child_env = os.environ.copy()
# Current llama-server versions read this documented env equivalent of --reasoning. Older managed versions ignore an unknown env variable instead of failing startup on an unknown passthrough CLI flag. An omitted start option follows the model template.
child_env["LLAMA_ARG_REASONING"] = server.reasoning or "auto"
# Always written, like the line above: an inherited value would otherwise pin a level the omitted flag promises to leave alone. 'default' is llama.cpp's own sentinel for "keep the chat template's level".
child_env["LLAMA_ARG_REASONING_EFFORT"] = server.reasoning_effort or "default"
# Pass the marker via env so an older launcher ignores it instead of treating an unknown CLI flag as a llama-server arg; new launchers preserve it across re-exec.
child_env[_START_API_KEY_MARKER_ENV] = "1"
# Convey healing/nudging through the env; `unsloth run` reads these when its own flags are omitted, so this works even if run re-execs into an older Unsloth venv. Only write when the operator set the flag explicitly; otherwise keep whatever they already exported (child_env is a copy of os.environ), falling back to the start defaults (healing on, nudging on) when nothing was inherited.
if server.tool_call_healing is not None:
child_env["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] = "0" if server.tool_call_healing else "1"
elif "UNSLOTH_DISABLE_TOOL_CALL_HEALING" not in child_env:
child_env["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] = "0"
if server.tool_call_nudging is not None:
child_env["UNSLOTH_TOOL_CALL_NUDGE"] = "1" if server.tool_call_nudging else "0"
elif "UNSLOTH_TOOL_CALL_NUDGE" not in child_env:
child_env["UNSLOTH_TOOL_CALL_NUDGE"] = "1"
# Forward any sampling pin via the env; `unsloth run` reads UNSLOTH_SAMPLING_* and the backend resolver applies it as a hard override. Only set fields the operator specified.
for _sampling_name in _SAMPLING_FIELDS:
_sampling_env = f"UNSLOTH_SAMPLING_{_sampling_name.upper()}"
_sampling_value = getattr(server, _sampling_name)
if _sampling_value is not None:
child_env[_sampling_env] = str(_sampling_value)
elif _sampling_name in server.unpinned:
child_env.pop(_sampling_env, None)
kwargs: dict = {
"stdout": log,
"stderr": subprocess.STDOUT,
"stdin": subprocess.DEVNULL,
"env": child_env,
}
if os.name == "nt":
kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
else:
kwargs["start_new_session"] = True
try:
server = subprocess.Popen(command, **kwargs)
finally:
log.close() # Popen dup'd the fd; drop the parent's copy
_auto_served_server = server
atexit.register(_shutdown_auto_served)
deadline = time.monotonic() + _SERVER_START_TIMEOUT_S
progress: Optional[_ModelDownloadProgress] = None
downloaded_bytes = 0
early_key_seen = False
port_followed = False
try:
while time.monotonic() < deadline:
if server.poll() is not None:
# The early key marker lands here before load finishes; redact it.
tail = _redacted_log_tail(log_path)
_shutdown_auto_served()
_fail(f"The Unsloth server stopped before it was ready. Last log lines:\n{tail}")
tail = _log_tail(log_path, lines = 400)
# `unsloth run` falls forward off a taken port; it prints the port once, so read the whole log.
if not port_followed:
bound_port = re.search(
rf"^{re.escape(_START_PORT_PREFIX)}(\d+)$",
_read_log(log_path),
flags = re.MULTILINE,
)
if bound_port:
port_followed = True
base = _effective_base(base, int(bound_port.group(1)))
if progress is None:
marker = re.search(
rf"^{re.escape(_START_API_KEY_PREFIX)}(sk-unsloth-[^\s]+)$",
tail,
flags = re.MULTILINE,
)
if marker:
early_key_seen = True
progress = _ModelDownloadProgress(
base,
marker.group(1),
model,
load.gguf_variant,
)
if progress is not None:
progress.poll()
# The cap measures time since bytes last arrived; log growth does not count (health polls and
# heartbeats keep it growing while nothing loads).
bytes_now = progress.downloaded_bytes if progress is not None else 0
if bytes_now > downloaded_bytes:
deadline = time.monotonic() + _SERVER_START_TIMEOUT_S
downloaded_bytes = bytes_now
# New children emit an early key marker, so wait for the Model loaded banner; older ones print the key only after load.
ready_signal = "Model loaded:" in tail if early_key_seen else "sk-unsloth-" in tail
if _studio_healthy(base) and ready_signal:
if progress is not None:
progress.complete()
progress.close()
progress = None
return base, server
time.sleep(2.0)
finally:
if progress is not None:
progress.close()
_shutdown_auto_served()
_fail(
"The Unsloth server didn't become ready and made no progress for "
f"{_SERVER_START_TIMEOUT_S}s. See {log_path}."
)
def _effective_base(base: str, port: Optional[int] = None) -> str:
# `unsloth run` binds to `parsed.port or 8888` and serves at the root, so normalize UNSLOTH_STUDIO_URL to plain scheme://host:port. A portless http://127.0.0.1 would otherwise launch on 8888 but poll port 80, and a path like /studio would poll /studio/api/health (404), either way hitting the startup timeout. IPv6 literals stay bracketed.
parsed = urlparse(base)
host = parsed.hostname or "127.0.0.1"
if ":" in host: # bare IPv6 literal (urlparse strips the brackets)
host = f"[{host}]"
return f"{parsed.scheme or 'http'}://{host}:{port or parsed.port or 8888}"
def _require_studio(
model: Optional[str] = None,
load: Optional[LoadOptions] = None,
*,
serve: bool = False,
launch: bool = True,
server_options: ServerOptions = ServerOptions(),
) -> tuple:
"""Return (base, server). server is a Popen only when WE auto-started it."""
sent = server_options.sent_by_agent()
server_options = server_options._replace(
unpinned = frozenset(name for name in sent if getattr(server_options, name) is not None),
**dict.fromkeys(sent),
)
# What the agent cannot send itself only reaches the env of a server WE launch, which then applies it to every client.
_pinned = [
"--" + _name.replace("_", "-")
for _name in _SAMPLING_FIELDS
if getattr(server_options, _name) is not None
]
_reasoning_pins = [
f"{_flag} {_value}"
for _flag, _value in (
("--reasoning", server_options.reasoning),
("--reasoning-effort", server_options.reasoning_effort),
)
if _value is not None
]
base = find_studio_server()
if base is not None:
if _pinned:
typer.echo(
f"Warning: an Unsloth server is already running at {base}, and this agent "
f"cannot send {', '.join(_pinned)} itself; they apply only when this command "
"starts the server, so the running server keeps its current sampling. Stop it "
"with `unsloth studio stop` and re-run to apply them.",
err = True,
)
if _reasoning_pins:
typer.echo(
f"Warning: an Unsloth server is already running at {base}, and this agent "
f"cannot send {', '.join(_reasoning_pins)} itself; it takes effect only when "
"this command starts the server, so the running server keeps its current "
"reasoning mode. Stop it with `unsloth studio stop` and re-run to apply the "
"override.",
err = True,
)
_tool_flags = [
_on if _value else _off
for _value, _on, _off in (
(server_options.enable_tools, "--enable-tools", "--disable-tools"),
(
server_options.tool_call_healing,
"--enable-tool-call-healing",
"--disable-tool-call-healing",
),
(
server_options.tool_call_nudging,
"--enable-tool-call-nudging",
"--disable-tool-call-nudging",
),
)
if _value is not None
]
if _tool_flags:
typer.echo(
f"Warning: an Unsloth server is already running at {base}; "
f"{', '.join(_tool_flags)} takes effect only when this command starts the "
"server, so the running server keeps its current tool settings. Stop it with "
"`unsloth studio stop` and re-run to apply it.",
err = True,
)
return base, None
expected = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")
# Auto-start a local server only for an interactive launch with a model to serve, and only for a plain-HTTP loopback target: never stand in for an explicit remote UNSLOTH_STUDIO_URL, and never for an https:// one, since `unsloth run` serves plain HTTP and the health poll against https would spin until the startup timeout.
if (
serve
and launch
and model
and is_loopback_url(expected)
and urlparse(expected).scheme == "http"
):
# Normalize to the port unsloth run actually binds, so the health poll and the returned base hit the same server we launch, not a portless :80.
expected = _effective_base(expected)
load = load or LoadOptions()
_server_wide = _pinned + [pin for pin in _reasoning_pins if pin != "--reasoning auto"]
if _server_wide:
typer.echo(
f"Warning: this agent cannot send {', '.join(_server_wide)} itself, so the "
"server this command starts applies them to every client until it stops.",
err = True,
)
_dropped = [
f"UNSLOTH_SAMPLING_{_name.upper()}"
for _name in _SAMPLING_FIELDS
if _name in server_options.unpinned
and os.environ.get(f"UNSLOTH_SAMPLING_{_name.upper()}")
]
if _dropped:
typer.echo(
f"Warning: this agent's flags replace the inherited {', '.join(_dropped)}, so "
"the server this command starts drops those pins for every client.",
err = True,
)
# 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)
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}.{hint} `unsloth studio`, or point "
"UNSLOTH_STUDIO_URL at a remote server."
)
def _studio_auth_root() -> Path:
from unsloth_cli.commands.studio import STUDIO_HOME
return STUDIO_HOME / "auth"
def _key_cache_path() -> Path:
return _studio_auth_root() / "agent_api_key.json"
def _read_cache(cache: Path) -> dict:
try:
data = json.loads(cache.read_text(encoding = "utf-8"))
except Exception:
return {}
return data if isinstance(data, dict) else {}
def _server_buckets(servers: dict, base: str) -> dict:
# Normalise a server's entry to {"saved": [...], "minted": [...]}, tolerating a corrupt or legacy value (a bare string or list is treated as minted, behind the handshake).
entry = servers.get(base) if isinstance(servers, dict) else None
if isinstance(entry, list):
return {"saved": [], "minted": [k for k in entry if isinstance(k, str)]}
if not isinstance(entry, dict):
return {"saved": [], "minted": []}
def _strs(name: str) -> list:
value = entry.get(name)
return [k for k in value if isinstance(k, str)] if isinstance(value, list) else []
return {"saved": _strs("saved"), "minted": _strs("minted")}
def _cached_keys(cache: Path, base: str, source: str) -> list:
# Keys are scoped per server. `source` splits user-supplied --api-key keys ("saved", trusted for that base) from auto-minted ones ("minted", replayed only after the identity check). Legacy unscoped caches are ignored.
return _server_buckets(_read_cache(cache).get("servers", {}), base)[source]
def _write_private_json(path: Path, data: dict) -> None:
# O_CREAT with 0o600 so a file holding an API key is never world-readable, even briefly (existing files keep whatever perms the user set).
path.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w") as handle:
handle.write(json.dumps(data, indent = 2) + "\n")
def _write_private_text(path: Path, text: str) -> None:
path.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w", encoding = "utf-8") as handle:
handle.write(text)
def _read_json_object(path: Path) -> Optional[dict]:
# {} when missing, None when it cannot be parsed as an object, so the caller leaves a user-managed file untouched rather than clobbering it.
if not path.exists():
return {}
try:
data = json.loads(path.read_text(encoding = "utf-8"))
except (ValueError, OSError):
return None
return data if isinstance(data, dict) else None
def _subdict(parent: dict, key: str) -> dict:
child = parent.get(key)
if not isinstance(child, dict):
child = parent[key] = {}
return child
def _remember_key(cache: Path, base: str, key: str, source: str) -> None:
data = _read_cache(cache)
servers = data.get("servers")
if not isinstance(servers, dict):
servers = data["servers"] = {}
buckets = _server_buckets(servers, base)
other = "minted" if source == "saved" else "saved"
buckets[source] = ([key] + [k for k in buckets[source] if k != key])[:8]
buckets[other] = [k for k in buckets[other] if k != key] # a key has one provenance
new_entry = {"saved": buckets["saved"], "minted": buckets["minted"]}
if servers.get(base) == new_entry:
return
servers[base] = new_entry
# Collapse legacy unscoped fields.
data.pop("keys", None)
data.pop("key", None)
try:
_write_private_json(cache, data)
except OSError:
pass # worst case the next launch mints another key
def _loaded_models_response(
base: str,
key: str,
timeout = 30,
) -> dict:
"""Raw listing of resident models, enough for startup and key checks; unlike /v1/models it skips
disk and media discovery, which can outlast the deadline on a slow scan folder."""
try:
answer = _http_json("GET", f"{base}/api/inference/loaded-models", key, timeout = timeout)
if isinstance(answer.get("data"), list):
return answer
# Older Studio returns 200 with error JSON for unknown /api paths; no data list means no route, not an empty one that hides a loaded model.
except urllib.error.HTTPError as exc:
if exc.code != 404:
raise
# Fall back, but never on an auth or server error; older Studios still answer /v1/models.
return _http_json("GET", f"{base}/v1/models", key, timeout = timeout)
def _key_accepted(base: str, key: str) -> bool:
# Only a genuine auth rejection (401/403) means "this key is bad, skip it and try the next cached key or mint a fresh one". A 5xx or a network blip is a server-side outage, not a bad key: fail with a clean message instead of silently discarding a working key and minting extras against a struggling server.
try:
_loaded_models_response(base, key)
return True
except urllib.error.HTTPError as exc:
if exc.code in (401, 403):
return False
_fail(
f"Unsloth server error while checking an API key ({exc.code}). "
"The server may be starting up or unhealthy; try again shortly."
)
except (urllib.error.URLError, TimeoutError) as exc:
_fail(
"Couldn't reach the Unsloth server while checking an API key: "
f"{getattr(exc, 'reason', None) or exc}"
)
def _agent_api_key(
base: str,
explicit: Optional[str],
*,
auto_started: bool = False,
minted_only: bool = False,
) -> str:
cache = _key_cache_path()
if explicit:
if not auto_started or _key_accepted(base, explicit):
_remember_key(cache, base, explicit, "saved")
return explicit
# The server was auto-started for this run, so an exported UNSLOTH_API_KEY meant for some other server must not fail the launch: the loopback mint path below is guaranteed to work. An explicit key the fresh server accepts is still honored above.
# Replay a key the user saved for THIS EXACT server first (scoped per base, so it only goes back there, including a remote or SSH-tunnelled Unsloth whose secret the local handshake cannot match). Skip ones the server rejects.
for key in [] if minted_only else _cached_keys(cache, base, "saved"):
if _key_accepted(base, key):
_remember_key(cache, base, key, "saved")
return key
# Beyond here we auto-mint or replay an auto-minted key. find_studio_server() trusts a base after only a health check, so both are limited to a loopback server we can cryptographically confirm is ours.
if not is_loopback_url(base):
_fail(
f"No saved API key for {base} and automatic minting only runs against "
"a local Unsloth. Create an API key in Unsloth → Settings → API and "
"pass it with --api-key (it is remembered per server), or set "
"UNSLOTH_API_KEY."
)
if not verify_studio_identity(base):
_fail(
f"Couldn't verify that {base} is your Unsloth (it may be running as a "
"different OS user, or another process took the port). Create an API "
"key in Unsloth → Settings → API and pass it with --api-key, or set "
"UNSLOTH_API_KEY."
)
# Identity verified: replay a previously auto-minted key, else mint a new one.
token = _studio_token()
if token is None:
_fail(
"Couldn't authenticate with the Unsloth server automatically. Create "
"an API key in Unsloth → Settings → API and pass it with --api-key, "
"or set UNSLOTH_API_KEY."
)
# Older releases could mint for a managed account, which cannot see the owner's model.
listed = _http_json(
"GET", f"{base}/api/auth/api-keys", token, error = "Couldn't list API keys"
).get("api_keys", [])
# A server reporting purposes only lets stamped keys reach saved Connections: re-mint unstamped ones.
stamped = any("purpose" in entry for entry in listed)
owned = {
entry.get("key_prefix")
for entry in listed
if not stamped or entry.get("purpose") == "unsloth_start"
}
for key in _cached_keys(cache, base, "minted"):
if key[len("sk-unsloth-") :][:8] in owned and _key_accepted(base, key):
_remember_key(cache, base, key, "minted")
return key
key = _http_json(
"POST",
f"{base}/api/auth/api-keys",
token,
{"name": "Coding agents (unsloth start)"},
error = "Couldn't create an API key",
)["key"]
_remember_key(cache, base, key, "minted")
return key
def _loaded_models(base: str, key: str) -> list:
try:
return _loaded_models_response(base, key).get("data", [])
except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
_fail_request(exc, "Couldn't list models")
def _model_loaded_state(base: str, key: str, model_id: object) -> Optional[bool]:
"""Return whether the model is loaded, or None if the listing is unavailable."""
try:
models = _loaded_models_response(base, key, timeout = 5).get("data", [])
except Exception:
return None
return any(m.get("id") == model_id and m.get("loaded") is not False for m in models)
def _model_still_loaded(base: str, key: str, model_id: object) -> bool:
return _model_loaded_state(base, key, model_id) is True
_HF_REPO_ID_SEGMENT_RE = re.compile(r"^[A-Za-z0-9._-]+$")
def _is_hub_model_id(value: object) -> bool:
if not isinstance(value, str):
return False
text = value.strip()
if "\\" in text:
return False
if text.startswith(("/", "./", "../", "~")):
return False
if len(text) >= 2 and text[1] == ":" and text[0].isalpha():
return False
# A hub id is exactly "namespace/name" over a restricted charset. Anything with extra path segments (a server-side relative path such as models/Llama/Foo.gguf on a remote Unsloth) is not a hub id and must not be casefold-matched against a differently cased path on a case-sensitive filesystem. This is host independent, unlike the existence probe below which cannot see a path that only exists on the server.
parts = text.split("/")
if len(parts) != 2:
return False
if any(part in ("", ".", "..") or not _HF_REPO_ID_SEGMENT_RE.match(part) for part in parts):
return False
try:
if Path(os.path.expanduser(text)).exists():
return False
except OSError:
return False
return True
def _is_model_path(value: str) -> bool:
"""Mirrors core.inference.model_ids._looks_like_path: a repo id is exactly ``org/model``, and anything else with a separator, drive, prefix or .gguf is a path. Deliberately not named _looks_like_path: that name is taken further down by the WSLENV classifier, which only matches absolute paths and would shadow this one."""
if value.lower().endswith(".gguf"):
return True
if value.startswith(("/", "\\", "./", "../", ".\\", "..\\", "~")):
return True
if len(value) >= 2 and value[1] == ":":
return True
return value.count("/") >= 2 or "\\" in value
def _public_model_id(value: Optional[str]) -> Optional[str]:
"""The id Unsloth advertises for a model loaded by path. The loaded listing never echoes a host path: it reports the file or directory name with any .gguf suffix stripped (core.inference.model_ids.public_model_id), so a path we asked to load has to be matched by that name too."""
if not value or not _is_model_path(value):
return None
name = os.path.basename(value.replace("\\", "/").rstrip("/"))
if name.lower().endswith(".gguf"):
name = name[: -len(".gguf")]
return name or None
def _public_model_ids(value: Optional[str]) -> set:
"""Return a path's basename ID and HF cache repo ID for old and current servers."""
ids = {_public_model_id(value)} - {None}
if ids:
parts = value.replace("\\", "/").split("/")
for index, part in enumerate(parts):
if part.startswith("models--") and parts[index + 1 : index + 2] == ["snapshots"]:
ids.add(part[len("models--") :].replace("--", "/"))
break
return ids
def _model_id_matches(
actual: object,
requested: object,
*,
allow_casefold: bool = True,
) -> bool:
if actual == requested:
return True
# Case-insensitive matching is only safe when the local existence probe in _is_hub_model_id is authoritative, i.e. against a loopback Unsloth on this host. Against a remote Unsloth a two-segment string is indistinguishable from a server-side relative path (Models/Foo vs models/foo), so casefolding it could attach to the wrong model on a case-sensitive server; defer to an exact match there and let the load endpoint resolve the requested path.
if not allow_casefold:
return False
if not (_is_hub_model_id(actual) and _is_hub_model_id(requested)):
return False
return str(actual).casefold() == str(requested).casefold()
def _inference_status(
base: str,
key: str,
model_id: Optional[str] = None,
) -> dict:
"""Runtime state of the resident model. {} means "cannot prove anything" (older server), never "nothing is set"."""
try:
return _model_status(base, key, model_id)
except Exception:
return {}
_OTHER_ACCOUNT_RESIDENT = (
"The model loaded in Unsloth belongs to another account, so this API key cannot use it. "
"Pass --model <hf-id-or-path> to load one: the same model and quant shares it, anything "
"else unloads it for every session using it."
)
def _resident_load_target(models: list, status: dict, allow_casefold: bool):
"""(identifier to post, id it is advertised as) for the running model. The loaded listing shows only the sanitized basename while _same_loaded_identifier compares resident paths exactly, so the load must carry the identifier status reports."""
if status.get("is_diffusion"):
# An image runtime answers with an active_model like any other, but it cannot serve chat: targeting it would tear down the diffusion server and then point the agent at a model that can never answer it.
_fail(
"Unsloth is serving an image model, which cannot serve chat, so there are no "
"settings to apply. Re-run with --model naming the chat model to load."
)
active_id = status.get("active_model")
entry = None
if active_id:
entry = next(
(
m
for m in models
if _model_id_matches(m.get("id"), active_id, allow_casefold = allow_casefold)
and m.get("loaded") is not False
),
None,
)
if entry is None and not status:
# Only when there is no status at all (older server). A status that ANSWERED with active_model null is stating there is no chat resident. Listing ORDER is not evidence either: a loaded speech sidecar is listed like any other resident model, so the first entry can be one. Answer only when the catalog is unambiguous.
loaded = [m for m in models if m.get("loaded") is not False]
if len(loaded) == 1:
entry = loaded[0]
elif loaded:
_fail(
"This Unsloth cannot say which model is serving chat, and more than one is "
"loaded. Re-run with --model naming the one these settings are for."
)
public_id = active_id or (entry or {}).get("id")
if not public_id:
if status.get("yours") is False:
_fail(_OTHER_ACCOUNT_RESIDENT)
if status:
# Status answered and named no chat model. Returning empty here would drop the knobs silently, which is the bug this path exists to fix.
_fail(
"No chat model is currently loaded, so there are no settings to apply. "
"Re-run with --model naming the model to load."
)
return None, None
identifier = status.get("model_identifier")
if identifier:
return identifier, public_id
# A native path lease redacts the internal path; inventing one from the basename would address the wrong file, so only a hub id can be posted back.
if _is_hub_model_id(public_id):
return public_id, public_id
_fail(
f"Unsloth is serving '{public_id}' from a local path it does not expose, so these "
"settings cannot be applied by attaching. Re-run with --model naming that path."
)
# /api/inference/status field to the /api/inference/load field that reproduces it. The "requested_" values are what the load was INVOKED with, which is what has to be resent; the bare names are the resolved ones and would pin a value the user never chose.
_RESIDENT_RUNTIME_FIELDS = {
"cache_type_kv": "cache_type_kv",
"chat_template_override": "chat_template_override",
"disable_vision": "disable_vision",
"gpu_memory_mode": "gpu_memory_mode",
"gpu_layers": "gpu_layers",
"n_cpu_moe": "n_cpu_moe",
"tensor_split": "tensor_split",
"tensor_parallel": "tensor_parallel",
"speculative_type": "speculative_type",
"spec_draft_n_max": "spec_draft_n_max",
"requested_reasoning_budget": "reasoning_budget",
"requested_reasoning_budget_message": "reasoning_budget_message",
# The applied value is null when the runtime refused the request.
# Scheme and width together; a bare width reads back as mx.quantize, so TurboQuant would reload as it. The width stays for servers without mlx_kv_quant.
"mlx_kv_quant_requested": "mlx_kv_quant",
"mlx_kv_bits_requested": "mlx_kv_bits",
# LoadRequest defaults this to True, so omitting it would reload a full-precision model in 4-bit. Null on GGUF, which has no such setting.
"load_in_4bit": "load_in_4bit",
# Same trap: max_seq_length defaults to 0, which _gguf_request_intent copies into n_ctx, so changing another knob would reset a custom context to automatic.
"requested_context_length": "max_seq_length",
"requested_gpu_ids": "gpu_ids",
"requested_parallel_slots": "n_parallel",
"requested_n_batch": "n_batch",
"requested_n_ubatch": "n_ubatch",
"requested_load_mode": "load_mode",
"requested_ctx_checkpoints": "ctx_checkpoints",
"requested_cache_ram": "cache_ram",
"requested_spec_draft_cache_type": "spec_draft_cache_type",
"requested_llama_extra_args": "llama_extra_args",
}
def _resident_runtime_payload(status: dict, payload: dict) -> dict:
"""The resident's own settings for knobs this load did not name. None means "never set" for every one of these, so it is dropped rather than sent: omitting a field is what lets the server inherit, while sending null would pin the absence. An explicit empty list is kept, since that is a real "launch with none"."""
if not status:
return {}
carried = {}
for field, load_field in _RESIDENT_RUNTIME_FIELDS.items():
if load_field in payload:
continue
value = status.get(field)
if value is None:
continue
carried[load_field] = value
offload = status.get("mlx_offload") or {}
for part, load_field in (("ple", "mlx_ple_offload"), ("experts", "mlx_expert_offload")):
requested = (offload.get(part) or {}).get("requested")
if load_field not in payload and requested is not None:
carried[load_field] = requested
return carried
def _resident_variant(status: dict) -> Optional[str]:
return status.get("gguf_variant") if status.get("is_gguf") or status.get("is_mlx") else None
def _resident_serves_variant(status: dict, wanted: Optional[str]) -> bool:
resident = _resident_variant(status)
if not resident:
return False
# Hub folder names are case-sensitive; llama.cpp quant labels are not.
if status.get("is_mlx"):
return str(resident).strip() == str(wanted).strip()
return str(resident).strip().lower() == str(wanted).strip().lower()
def _load_settings_differ(status: dict, load: LoadOptions, overrides: frozenset) -> bool:
"""Whether applying these settings can restart the resident. Unproven equality counts as a difference: a silent restart is worse than a spurious warning."""
if not status:
return True
# _runtime_matches_intent rejects an identical intent while a spec probe, a DFlash drafter or a changed speculative binary is waiting to be retried, so the server reloads regardless of what the CLI asked for. Equality of the overrides is then no proof of a no-op, and claiming one would skip the gate and the warning.
if any(
status.get(field)
for field in (
"spec_probe_retry_pending",
"spec_dflash_retry_pending",
"spec_fallback_binary_changed",
)
):
return True
for name in overrides:
if name == "gguf_variant":
# Casefold, not _normalized_variant, which strips separators: a mistyped Q4KM would read as equal here yet still really reload on the server. The preload gate below already compares this way, and the two have to agree.
if not _resident_serves_variant(status, load.gguf_variant):
return True
elif name == "max_seq_length":
# Requested, not resolved: llama.cpp clamps n_ctx at fit time.
resident = status.get("requested_context_length")
if resident is None or int(resident) != int(load.max_seq_length):
return True
elif name == "load_in_4bit":
# GGUF has no 4-bit setting and reports null, which would read as "differs" and warn about an unload the server is not going to perform.
if status.get("is_gguf"):
continue
resident = status.get("load_in_4bit")
if resident is None or bool(resident) != bool(load.load_in_4bit):
return True
elif name == "tensor_parallel":
# llama.cpp only. The standard load never forwards it, so a restart would apply nothing.
if not status.get("is_gguf"):
continue
# The architecture gate can normalize a tensor request to layer mode and say so, so asking for it AGAIN is the request already applied, not a difference, and the backend dedupes exactly this state. Asking to turn it OFF is the opposite: the backend keeps the tensor intent behind that fallback and does not read a bare false as an explicit drop (the UI sends false routinely), so only a real reload can clear it.
if status.get("tensor_parallel_dropped_by_arch_gate"):
if load.tensor_parallel:
continue
return True
if bool(status.get("tensor_parallel")) != bool(load.tensor_parallel):
return True
elif name == "gpu_memory_mode":
if not status.get("is_gguf"):
continue
# A paravirtual host pins every placement request to the same runtime, and a CPU fallback is preserved across reloads by _preserve_cpu_fallback_intent, so in both cases the raw mode cannot tell two requests apart. resident-config-match.ts skips placement on exactly these two for the same reason.
if status.get("gpu_placement_paravirtual") or status.get("cpu_fallback_reason"):
continue
if status.get("gpu_memory_mode") != load.gpu_memory_mode:
return True
# Manual to manual is a real no-op: the payload only sends the implicit gpu_layers = -1 when switching INTO manual, so a resident already pinned to a layer count keeps it through the round-trip and nothing changes.
return False
def _resolve_model(
base: str,
key: str,
requested: Optional[str],
load: LoadOptions = LoadOptions(),
preload_check = None,
infer_resident: bool = True,
) -> dict:
models = _loaded_models(base, key)
load_requested = False
# Only casefold-match ids against a loopback Unsloth, where _is_hub_model_id's local existence probe can actually reject a server-side path; see the note there.
allow_casefold = is_loopback_url(base)
# The loaded listing carries the active GGUF variant only while that quant reference still resolves, and never the runtime load settings, so an id match alone can hide the wrong quant (Q8_0 serving while the user asked for UD-Q4_K_XL). When the user passed any explicit load knob, defer to /api/inference/load: the server's already-loaded dedup answers "already_loaded" without reloading when the variant AND settings match, so a second session running the same command still attaches without evicting the first.
overrides = load.overrides()
load_has_overrides = bool(overrides)
# Inferred-attach path only: `requested` becomes the resident's internal identifier (possibly a server path), so this is the id to show and to match on.
attach_public_id = None
status_snapshot = None
# Whether the inferred settings can restart the resident. Computed once: the preload gate, the warning, the consent refusal and force_reload must all agree, and asking twice against a snapshot taken at different times is how they drift apart.
inferred_differs = False
same_checkpoint = True
if requested is None and load_has_overrides and infer_resident:
status_snapshot = _inference_status(base, key)
requested, attach_public_id = _resident_load_target(models, status_snapshot, allow_casefold)
inferred_differs = _load_settings_differ(status_snapshot, load, overrides)
# preload_check deliberately survives: it is the only gate before the load evicts the shared model (_require_gguf_for_codex runs after _connect returns). An older server answers this listing from the full catalog, which also carries cached-but-unloaded entries (loaded == False); matching one would skip /api/inference/load and leave the agent pointed at a model that is not resident, so only attach to an entry that is actually loaded.
loaded_match = next(
(
m
for m in models
if _model_id_matches(m.get("id"), requested, allow_casefold = allow_casefold)
and m.get("loaded") is not False
),
None,
)
match = None if requested and load_has_overrides else loaded_match
if requested and match is None:
load_requested = True
if attach_public_id is None and loaded_match is not None:
# A full load resets omitted settings, so read the named resident's own slot to carry them.
status_snapshot = _inference_status(base, key, loaded_match["id"])
# The listing shows a local checkpoint by basename, so ./foo matches a resident old/foo: inherit only from the checkpoint this load resolves to.
wanted_path = os.path.abspath(os.path.expanduser(requested))
# A snapshot naming another model (replaced since the listing, or a server ignoring ?model=) describes nothing of this one.
same_checkpoint = _model_id_matches(
status_snapshot.get("active_model"),
loaded_match["id"],
allow_casefold = allow_casefold,
) and (
_is_hub_model_id(requested)
or any(
os.path.abspath(os.path.expanduser(str(status_snapshot.get(field))))
== wanted_path
for field in ("model_identifier", "gguf_path", "model_path")
if status_snapshot.get(field)
)
)
# Only here is an evicting load certain: the gate must not reject a request the resident model already satisfies (a path-loaded GGUF shown as a bare basename can collide with a non-GGUF unsloth/<name>).
# A load of a model already served replaces it in its own slot, which may not be the primary.
active = loaded_match or next((m for m in models if m.get("loaded") is not False), None)
# On the inferred path the target came from status, so catalog order can name a different entry (a speech sidecar listed first). Using it would make the survivor probe below report the wrong model as still serving.
if attach_public_id is not None:
active = next(
(
m
for m in models
if _model_id_matches(
m.get("id"), attach_public_id, allow_casefold = allow_casefold
)
and m.get("loaded") is not False
),
None,
) or {"id": attach_public_id}
if preload_check is not None:
# An explicit knob forces match to None so the server's disk-free dedupe can answer already_loaded; gating it would reject a second session for the model already serving, whose file may have moved. Only the quant is checked below: any other run knob changes the runtime intent, a real reload nothing dedupes.
other_overrides = bool(overrides - {"gguf_variant"})
# Match public path IDs before deciding whether to rerun the gate.
wanted_ids = {requested} | _public_model_ids(requested)
resident_serves_request = not other_overrides and any(
m.get("loaded") is not False
and any(
_model_id_matches(m.get("id"), want, allow_casefold = allow_casefold)
for want in wanted_ids
)
for m in models
)
# A proven no-op evicts nothing, so the gate has nothing to protect, and running it would reject an attach the disk-free already-loaded path can still serve (a direct .gguf the server has mapped but that has since moved).
if attach_public_id is not None and not inferred_differs:
resident_serves_request = True
# The loaded listing shows only the basename, so confirm a path request against the identifier the server loaded, else /new/foo.gguf reads as resident because /old/foo.gguf is.
if resident_serves_request and _is_model_path(requested):
try:
status = _model_status(base, key, requested)
except Exception:
status = {}
loaded_paths = {
str(status.get(field))
for field in ("model_identifier", "gguf_path", "model_path")
if status.get(field)
}
wanted_path = os.path.abspath(os.path.expanduser(requested))
resident_serves_request = any(
os.path.abspath(os.path.expanduser(path)) == wanted_path
for path in loaded_paths
)
if resident_serves_request and load.gguf_variant:
try:
status = _model_status(base, key, requested)
except Exception:
status = {}
# Casefold, not _normalized_variant, which strips separators: a mistyped Q4KM would skip the gate here yet still really reload on the server.
resident_serves_request = _resident_serves_variant(status, load.gguf_variant)
if not resident_serves_request:
preload_check(base, key, requested, load.gguf_variant)
active_id = active.get("id") if active else None
announced_switch = False
# Public IDs can collide and status hides paths: wait for the load result.
switch_unknown = False
if attach_public_id is not None:
# An inferred attach never switches model, so the comparison below would misreport a switch and print the server's path.
if inferred_differs:
typer.echo(f"Applying new load settings to {attach_public_id}.")
typer.echo("This unloads the current model for every attached session.")
announced_switch = True
elif active_id and not _model_id_matches(
active_id,
requested,
allow_casefold = allow_casefold,
):
if any(
_model_id_matches(active_id, listed, allow_casefold = allow_casefold)
for listed in _public_model_ids(requested)
):
switch_unknown = True
else:
typer.echo(f"Switching the Unsloth server from {active_id} to {requested}.")
typer.echo("This unloads the current model for every attached session.")
announced_switch = True
elif active_id and load.gguf_variant:
# Same repo id but an explicit quant still replaces the resident weights; the loaded listing does not carry a variant for every resident model, so ask the status endpoint.
try:
status = _model_status(base, key, active_id)
except Exception:
status = {}
resident = _resident_variant(status)
switching = (
not _resident_serves_variant(status, load.gguf_variant)
if status.get("is_mlx")
else _normalized_variant(resident) != _normalized_variant(load.gguf_variant)
)
if resident and switching:
typer.echo(
f"Switching the Unsloth server from {active_id}:{resident} "
f"to {requested}:{load.gguf_variant}."
)
typer.echo("This unloads the current model for every attached session.")
announced_switch = True
elif loaded_match is not None and _load_settings_differ(status, load, overrides):
typer.echo(f"Applying new load settings to {active_id}.")
typer.echo("This unloads the current model for every attached session.")
announced_switch = True
elif active_id and loaded_match is not None:
try:
status = _model_status(base, key, active_id)
except Exception:
status = {}
if _load_settings_differ(status, load, overrides):
typer.echo(f"Applying new load settings to {active_id}.")
typer.echo("This unloads the current model for every attached session.")
announced_switch = True
elif not active_id and _inference_status(base, key).get("yours") is False:
typer.echo(
"Switching the Unsloth server from another account's model to "
f"{_display_model_spec(requested, load.gguf_variant)}."
)
typer.echo(
"This unloads it for every attached session, unless it is the same model and quant."
)
# Mirror `unsloth run`'s load knobs; keep the default payload as just model_path so a bare `--model` load is unchanged. Membership decides, not truthiness: a reset like --context-length 0 equals the default yet must be sent.
payload = {"model_path": requested}
if "gguf_variant" in overrides and load.gguf_variant:
direct_file = attach_public_id is not None and str(requested).lower().endswith(".gguf")
if direct_file:
# from_identifier consults a variant only for a DIRECTORY, so a DIFFERENT quant cannot be selected: posting one would reload the very same file and label it with a quant that does not describe its weights. Restating the one already running asks for no change, so drop the inapplicable field and let the other overrides through.
resident_variant = status_snapshot.get("gguf_variant")
same = (
bool(resident_variant)
and str(resident_variant).strip().lower()
== str(load.gguf_variant).strip().lower()
)
if not same:
_fail(
f"'{attach_public_id}' was loaded from a single .gguf file, so "
f"--gguf-variant {load.gguf_variant} cannot select a different quant. "
"Re-run with --model naming the repository to switch quants."
)
else:
payload["gguf_variant"] = load.gguf_variant
elif attach_public_id is not None and (
status_snapshot.get("is_gguf") or status_snapshot.get("is_mlx")
):
# Re-send the running quant: a repo id carries none, so from_identifier would auto-pick (GGUF_QUANT_PREFERENCE, UD-Q4_K_XL first) and changing only the context would evict a chosen Q8_0 to download a different quant. Skip a .gguf path, which loads as itself; the server gates on the same suffix.
resident_variant = status_snapshot.get("gguf_variant")
if resident_variant and not str(requested).lower().endswith(".gguf"):
payload["gguf_variant"] = resident_variant
elif loaded_match is not None and not str(requested).lower().endswith(".gguf"):
# Same for a named model already served, read from the slot serving it.
if (
status_snapshot.get("is_gguf") or status_snapshot.get("is_mlx")
) and status_snapshot.get("gguf_variant"):
payload["gguf_variant"] = status_snapshot["gguf_variant"]
if "max_seq_length" in overrides:
payload["max_seq_length"] = load.max_seq_length
if "load_in_4bit" in overrides:
payload["load_in_4bit"] = load.load_in_4bit
if "tensor_parallel" in overrides:
payload["tensor_parallel"] = load.tensor_parallel
if "gpu_memory_mode" in overrides and load.gpu_memory_mode is not None:
payload["gpu_memory_mode"] = load.gpu_memory_mode
# -1 means "pick the layers", which is right when the user is switching INTO manual, but on an inferred attach to a resident already in manual it would throw away the layer count it was pinned to. Leave it for the round-trip.
already_manual = (
same_checkpoint
and bool(status_snapshot)
and status_snapshot.get("gpu_memory_mode") == "manual"
)
if load.gpu_memory_mode == "manual" and not already_manual:
payload["gpu_layers"] = -1
if (
attach_public_id is not None
and inferred_differs
and status_snapshot.get("requires_trust_remote_code")
):
# The reload cannot reproduce the consent: the payload has no trust_remote_code and no approval fingerprint, and the standard backend tears the worker down BEFORE the replacement is accepted, so a rejected custom-code load leaves nothing resident. Refuse while the model is still serving; naming it with --model goes through the normal consent path.
_fail(
f"'{attach_public_id}' was loaded with trust_remote_code, which an attach "
"cannot re-authorize. Re-run with --model naming it to apply these settings."
)
if attach_public_id is not None or loaded_match is not None:
# A resident reload is a full load, not a PATCH: carry the knobs the user did not name, or changing the context alone drops their KV dtype, slot count, batch sizes and GPU placement.
carried = _resident_runtime_payload(status_snapshot, payload)
if attach_public_id is None:
# Omitted extras are inherited server-side, shadow-stripped against the fields sent: a copied list would beat --context-length, and a carried field would strip an extra that won. So extras mean no carry.
if not same_checkpoint or status_snapshot.get("requested_llama_extra_args"):
carried = {}
carried.pop("llama_extra_args", None)
# Outside manual, status reports the planner's emitted ratio, not the request (LlamaCppBackend.tensor_split); sending it pins an Auto split and reloads.
if {**payload, **carried}.get("gpu_memory_mode") != "manual":
carried.pop("tensor_split", None)
# Status cannot say whether the slot count was the default, and a sent count stops Auto cutting slots to keep a drafter (n_parallel_from_default).
carried.pop("n_parallel", None)
payload.update(carried)
# The server cannot tell an explicit `--context-length 0` reset from the 0 that every UI load sends, so it treats 0 as "no preference" and would answer already_loaded. Say outright that this one is a reload, but only when status PROVED a difference: on an older server _load_settings_differ cannot tell, and forcing there would evict on every attach.
if attach_public_id is not None and status_snapshot and inferred_differs:
payload["force_reload"] = True
try:
loaded = _load_model_with_progress(base, key, requested, load, payload)
except Exception:
# The warning above promised an unload; if the server refused the load before evicting anything, say so. Not BaseException: Ctrl+C must stay immediate, without a probe or a survivor claim.
if announced_switch and _model_still_loaded(base, key, active_id):
typer.echo(f"Nothing was unloaded; {active_id} is still serving.", err = True)
# Report an unannounced eviction only if the listing confirms it.
if switch_unknown and _model_loaded_state(base, key, active_id) is False:
typer.echo(f"{active_id} was unloaded for every attached session.", err = True)
raise
if loaded.get("status") == "already_loaded":
# Show the public id on the inferred path; `requested` may be a server path.
shown = attach_public_id or requested
typer.echo(f"Reusing loaded model: {_display_model_spec(shown, load.gguf_variant)}")
elif switch_unknown:
typer.echo(f"Loaded {requested} in place of {active_id}.")
typer.echo("This unloaded the previous model for every attached session.")
# Match public IDs and load-response names, since the listing may omit paths; keep attach_public_id for inferred opaque IDs.
wanted = ({requested, attach_public_id} - {None}) | _public_model_ids(requested)
if isinstance(loaded, dict):
wanted |= {loaded.get("model"), loaded.get("display_name")} - {None}
models = _loaded_models(base, key)
match = next(
(
m
for m in models
if m.get("loaded") is not False
and any(
_model_id_matches(m.get("id"), w, allow_casefold = allow_casefold) for w in wanted
)
),
None,
)
if match is not None:
if requested and not load_requested:
typer.echo(f"Reusing loaded model: {_display_model_spec(requested, load.gguf_variant)}")
return match
if requested:
# We asked Unsloth to load it and it did not surface as loaded; do not silently hand back an unrelated loaded model.
_fail(
f"Unsloth didn't report '{requested}' as loaded. Double-check the model "
"id, or load it from the model dropdown in the UI."
)
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)
# Empty and unloaded-only listings mean the same; the server version decides which it sends.
_fail(
"No model is loaded in Unsloth. Load one from the model dropdown in "
"the UI, or pass --model <hf-id-or-path> to load it from here."
)
return resident
_HF_OFFLINE_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
def _hf_offline() -> bool:
return any(
os.environ.get(var, "").strip().lower() in _HF_OFFLINE_TRUE_VALUES
for var in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE")
)
def _hub_gguf_files(repo: str) -> Optional[list]:
names = _hub_repo_files(repo)
if names is None:
return None
ggufs = [n for n in names if n.lower().endswith(".gguf")]
return [n for n in ggufs if not _is_auxiliary_gguf(n)]
def _hub_repo_files(repo: str) -> Optional[list]:
if _hf_offline():
return None
endpoint = os.environ.get("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
try:
request = urllib.request.Request(
f"{endpoint}/api/models/{repo}",
headers = {"User-Agent": _USER_AGENT},
)
with urllib.request.urlopen(request, timeout = 10) as response:
info = json.loads(response.read().decode() or "{}")
except Exception:
return None
siblings = info.get("siblings")
if not isinstance(siblings, list) or not siblings:
return None
return [
s["rfilename"]
for s in siblings
if isinstance(s, dict) and isinstance(s.get("rfilename"), str)
]
# Keep in sync with utils/gguf_names.py; the remote CLI cannot require backend imports.
_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
_DRAFTER_DIR_KINDS = ("mtp", "dspark")
def _is_auxiliary_gguf(filename: str) -> bool:
# Mirrors detect_gguf_model_remote (hub.utils.gguf.is_mtp_drafter_path): projectors, separate-file drafters and big-endian builds are not loadable weights. Drafters match by basename prefix or exact parent dir, never substring, since the kind names double as family names and Qwen3.6-...-DFlash-Q4_K_M.gguf IS the model. Only the root-level trailing -be form is filtered; the fuller quant-aware check would over-reject here.
p = filename.lower().replace("\\", "/")
parts = [segment for segment in p.split("/") if segment]
if not parts:
return False
name, parents = parts[-1], parts[:-1]
if "mmproj" in p:
return True
if any(name.startswith(f"{kind}-") for kind in _DRAFTER_KINDS):
return True
if any(kind in parents for kind in _DRAFTER_DIR_KINDS):
return True
stem = name.rsplit(".", 1)[0]
return not parents and stem.endswith(("-be", "_be"))
def _direct_gguf_is_companion(path: str) -> bool:
"""Whether the server refuses this .gguf path as a model in its own right. A strict subset of detect_gguf_model / gguf_variants._direct_gguf_loads: projector and drafter prefixes read off the basename, companion-only folders off the immediate parent, the same context the server reads, so nothing loadable is refused here. Big-endian is left out on purpose: that check needs quant context the CLI cannot mirror."""
parts = [segment for segment in path.replace("\\", "/").split("/") if segment]
if not parts:
return False
name = parts[-1].lower()
if not name.endswith(".gguf"):
return False
# Root-independent refusals only: name prefixes read the basename alone, so they mean the same under any model root. A drafter FOLDER does not.
if "mmproj" in name:
return True
return any(name.startswith(f"{kind}-") for kind in _DRAFTER_KINDS)
def _path_syntax_is_native(path: str) -> bool:
"""Whether *path* is spelled the way this OS spells paths. A Windows path read from WSL, or a POSIX one read from Windows, parses into something this process cannot judge (``C:\\models\\m.gguf`` has parent ``.`` here), so its absence locally says nothing about the server's disk."""
windows_drive = len(path) >= 2 and path[1] == ":" and path[0].isalpha()
if os.name == "nt":
return True
return not windows_drive and "\\" not in path
def _direct_gguf_companion_is_uncertain(path: str) -> bool:
"""Whether only the server can say if this path is a companion. detect_gguf_model reads drafter folders relative to the registered model root, so ``/models/MTP/foo-Q8_0.gguf`` is refused or loaded depending on where that root sits, a question only the server can answer since this process does not know its roots."""
parts = [segment for segment in path.replace("\\", "/").split("/") if segment]
return any(segment.lower() in _DRAFTER_DIR_KINDS for segment in parts[:-1])
# Mirrors model_config._extract_quant_label's pattern; change in lockstep.
_QUANT_LABEL_RE = re.compile(
r"(UD-)?"
r"(MXFP[0-9]+(?:_[A-Z0-9]+)*"
r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
r"|P?TQ[0-9]+_[0-9]+"
r"|Q[0-9]+_K_[A-Z]+"
r"|P?Q[0-9]+_(?:[0-9]+(?:_G[0-9]+)?|G[0-9]+)"
r"|Q[0-9]+_K"
r"|BF16|F16|F32)"
r"(-[0-9]+(?:\.[0-9]+)?bpw)?",
re.IGNORECASE,
)
def _direct_gguf_variant_labels(path: str) -> tuple:
"""The labels the server's direct-file resolver accepts for *path*. Mirrors _direct_gguf_for_variant: the quant label read from the basename first, the immediate parent only when the basename carries none, plus the shard-stripped stem itself. The basename wins the disagreement: a Q8_0/foo-Q4_K_M.gguf answers Q4_K_M, so its parent must not vouch for Q8_0 here while the load resolves nothing and evicts."""
norm = path.replace("\\", "/").rstrip("/")
name = norm.rsplit("/", 1)[-1]
stem = re.sub(r"-\d{3,}-of-\d{3,}$", "", name.rsplit(".", 1)[0])
match = _QUANT_LABEL_RE.search(stem)
if match is None and "/" in norm:
match = _QUANT_LABEL_RE.search(norm.rsplit("/", 2)[-2])
labels = [stem]
if match is not None:
label = f"{match.group(1) or ''}{match.group(2)}{match.group(3) or ''}"
labels.append(label)
# The resolver also accepts the hub-style bpw-stripped spelling.
stripped = re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", label, flags = re.IGNORECASE)
if stripped != label:
labels.append(stripped)
else:
# The extractor's own fallback: the last hyphen-separated segment.
labels.append(stem.split("-")[-1])
return tuple(labels)
# Mirrors hub.utils.gguf._BIG_ENDIAN_GGUF_FILENAME_RE; change in lockstep.
_BIG_ENDIAN_FILENAME_RE = re.compile(r"(^|[-_])be(?:[._-]|$)", re.IGNORECASE)
def _direct_gguf_is_big_endian(path: str) -> bool:
"""Mirrors hub.utils.gguf.is_big_endian_gguf_path over the same one-parent context detect_gguf_model reads; change in lockstep. A quant-named parent exempts a bare -be basename (that file loads); a be marker at or after a basename quant does not."""
norm = path.replace("\\", "/").rstrip("/")
parts = [segment for segment in norm.split("/") if segment]
name = parts[-1]
stem = name.rsplit(".", 1)[0].lower()
quant_stem = re.sub(r"-\d{3,}-of-\d{3,}$", "", stem)
match = _QUANT_LABEL_RE.search(quant_stem)
parent = parts[-2].lower() if len(parts) > 1 else ""
if match is None and parent:
match = _QUANT_LABEL_RE.search(parent)
quant_key = (
f"{match.group(1) or ''}{match.group(2)}{match.group(3) or ''}".lower()
if match is not None
else quant_stem.split("-")[-1]
)
quant_index = stem.find(quant_key) if quant_key else -1
quant_in_parent_only = (
bool(parent)
and quant_index < 0
and (
(quant_key and quant_key in parent)
or (not quant_key and _QUANT_LABEL_RE.search(parent))
)
)
for be in _BIG_ENDIAN_FILENAME_RE.finditer(stem):
if quant_index >= 0 and quant_index < be.start():
return True
tail = stem[be.end() :].lstrip("._-")
if not tail or _QUANT_LABEL_RE.search(tail) is None:
return not quant_in_parent_only
return False
# Mirrors gguf_variants._DIRECT_SPLIT_RE / the load path's _GGUF_SPLIT_FILE_RE; change in lockstep. Five digits exactly: a shorter -001-of-002 name loads as an ordinary file.
_DIRECT_SPLIT_FILE_RE = re.compile(
r"^(?P<stem>.+)-(?P<index>\d{5})-of-(?P<total>\d{5})$", re.IGNORECASE
)
def _direct_gguf_file_is_ready(path: str) -> bool:
"""Whether a CLI-visible direct .gguf file can actually serve a load. Mirrors the backend's completeness rules: zero bytes is an interrupted copy, and a split needs every sibling index present and non-empty. Unknowable reports ready, so a path this process cannot judge never blocks the load."""
def _split_set_complete(candidate: Path) -> Optional[bool]:
match = _DIRECT_SPLIT_FILE_RE.match(candidate.name.rsplit(".", 1)[0])
if match is None:
return None
total = int(match.group("total"))
if total < 2:
return None
sibling = re.compile(
re.escape(match.group("stem"))
+ r"-(\d{"
+ str(len(match.group("index")))
+ r"})-of-"
+ re.escape(match.group("total"))
+ r"\.gguf$",
re.IGNORECASE,
)
found = {
int(m.group(1))
for q in candidate.parent.iterdir()
if (m := sibling.match(q.name)) and q.is_file() and q.stat().st_size > 0
}
return found >= set(range(1, total + 1))
try:
p = Path(os.path.expanduser(path))
# A broken symlink is visible here, and the .gguf suffix alone still makes it a load, which fails after teardown.
if p.is_symlink() and not p.exists():
return False
if not p.is_file():
return True
if p.stat().st_size == 0:
return False
whole = _split_set_complete(p)
if whole is not False:
return True
# Mirror _local_gguf_load_path: an incomplete nominal set still loads when the shard is a symlink whose target sits with the full set.
if p.is_symlink():
target = p.resolve()
return _split_set_complete(target) is not False
return False
except OSError:
return True
def _answer_offers_variant(
variants: list,
variant: str,
strict: bool = False,
) -> bool:
"""Whether a live variants answer can resolve *variant* to a file. Mirrors llama.cpp's resolution, case-insensitively: quant label first, then the whole-token filename fallback, which is as loose as it gets since a separator-differing label resolves to nothing there either. A row missing both fields cannot be disproven, so it vouches. ``strict`` drops the filename-token tier: the LOCAL resolver takes only exact labels, so a local answer must not vouch for a shorter token (Q4 inside model-Q4_K_M.gguf) the load would never resolve."""
wanted = str(variant).strip().lower()
if not wanted:
return True
token = re.compile(r"(?<![a-z0-9])" + re.escape(wanted) + r"(?![a-z0-9])")
for row in variants:
if not isinstance(row, dict):
return True
# A torn local row cannot vouch in strict mode; hub partials stay resumable.
if strict and row.get("partial") is True:
continue
quant = row.get("quant")
filename = row.get("filename")
if not isinstance(quant, str) and not isinstance(filename, str):
return True
if isinstance(quant, str):
label = quant.strip().lower()
# The resolver also accepts the hub-style bpw-stripped spelling.
if wanted in (label, re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", label)):
return True
if isinstance(filename, str):
# Local resolver also takes the exact shard-stripped stem, full relative spelling only, never a nested file's bare basename.
stem = re.sub(r"-\d{3,}-of-\d{3,}$", "", filename.rsplit(".", 1)[0]).lower()
if wanted == stem:
return True
# Any whole quant token of the basename (F16-checkpoint-Q4_K_M -> Q4_K_M).
if any(
wanted
in (
f"{m.group(1) or ''}{m.group(2)}".lower(),
# Keeps the bpw modifier the hub extractor drops, so both spellings match.
f"{m.group(1) or ''}{m.group(2)}{m.group(3) or ''}".lower(),
)
for m in _QUANT_LABEL_RE.finditer(stem.rsplit("/", 1)[-1])
):
return True
if strict:
if not isinstance(quant, str):
return True
continue
if isinstance(filename, str) and token.search(filename.lower()):
return True
return False
class _GgufAgent(NamedTuple):
label: str
command: str
_CODEX_GGUF_AGENT = _GgufAgent("Codex", "codex")
_CLAUDE_GGUF_AGENT = _GgufAgent("Claude Code", "claude")
def _fail_gguf_variant_missing(model_id: str, variant: str, variants: list) -> NoReturn:
offered = [
row.get("quant")
for row in variants
if isinstance(row, dict) and isinstance(row.get("quant"), str) and row.get("quant")
]
message = f"{model_id} has no GGUF variant {variant}."
if offered:
message += " Available: " + ", ".join(dict.fromkeys(offered))
_fail(message)
def _refuse_npu_model(model: Optional[str]) -> None:
from unsloth_cli._npu import npu_model_path
npu_path = npu_model_path(model)
if npu_path:
model_id = npu_path.split(":", 1)[1]
# Unchecked, `lemonade:<id>` was split into a GGUF lookup for a repo named "lemonade".
_fail(
f"{model_id} is an AMD NPU model. `unsloth start` runs coding agents on GGUF models; "
f"chat with {model_id} in Unsloth Studio or with `unsloth chat {model_id}`."
)
def _fail_agent_needs_gguf(agent: _GgufAgent, model_id: str) -> NoReturn:
message = (
f"{agent.label} needs a GGUF model served by llama-server, " f"but {model_id} is not one."
)
guess = f"{model_id}-GGUF"
if "gguf" not in model_id.lower() and _is_hub_model_id(guess) and _hub_gguf_files(guess):
message += f" Try: unsloth start {agent.command} --model {guess}"
_fail(message)
# Mirrors the frontend's NO_MLX_REASONS: an Apple Silicon host that still cannot load MLX.
_NO_MLX_REASONS = frozenset(
{"mlx_unavailable", "no_torch", "intel_mac", "rosetta", "detection_failed"}
)
# Mirrors the backend's PRECISION_FOLDER_SOURCE: an MLX precision subfolder (6-bit/), not a GGUF quant.
_MLX_PRECISION_FOLDER_RE = re.compile(
"(?:mlx[-_]?)?(?:[0-9]{1,2}[-_]?bits?(?:[-_][a-z0-9]+)*"
"|bf16|fp16|f16|fp32|f32|fp8|mxfp4|nvfp4)",
re.IGNORECASE,
)
def _asks_gguf_quant(variant: Optional[str]) -> bool:
return bool(variant) and not _MLX_PRECISION_FOLDER_RE.fullmatch(str(variant).strip())
def _this_host_loads_mlx() -> bool:
import platform
return sys.platform == "darwin" and platform.machine() == "arm64"
def _server_loads_mlx(base: str, key: str) -> bool:
deadline = time.monotonic() + 30
while True:
try:
health = _http_json("GET", f"{base}/api/health?detect_hardware=true", key, timeout = 30)
except Exception:
return False
if not (isinstance(health, dict) and health.get("hardware_detecting")):
break
if time.monotonic() >= deadline:
return False
time.sleep(1)
return (
isinstance(health, dict)
and health.get("device_type") == "mac"
and health.get("apple_silicon") is True
and health.get("chat_only_reason") not in _NO_MLX_REASONS
)
def _refuse_non_gguf(
agent: _GgufAgent, model_id: str, base: str, key: str, variant: Optional[str]
) -> None:
# A requested quant or a .gguf file asks for GGUF, which an MLX load would silently drop.
if variant or model_id.lower().endswith(".gguf") or not _server_loads_mlx(base, key):
_fail_agent_needs_gguf(agent, model_id)
def _preflight_agent_gguf(
agent: _GgufAgent,
model: Optional[str],
*,
serve: bool = True,
launch: bool = True,
gguf_variant: Optional[str] = None,
) -> None:
# Hub-listing preflight for the auto-start path only: with a server running, identifiers
# resolve against its cwd/cache/token, so _attach_gguf_check asks the server instead.
# Only a complete listing with no .gguf files rejects; unknown defers to the
# post-connect check. Mirrors _require_studio's auto-start condition, so with no start
# possible its "no running server" error comes first, without a hub probe.
_refuse_npu_model(model)
if not (serve and launch and model):
return
expected = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")
if not is_loopback_url(expected) or urlparse(expected).scheme != "http":
return
if find_studio_server() is not None:
return
repo, inline_variant = _split_repo_variant(model)
# A bare foo.gguf naming no local file is a shorthand, canonicalized like any owner-less name.
if "/" not in repo and (not _is_model_path(repo) or repo.lower().endswith(".gguf")):
# The server canonicalizes owner-less shorthands to unsloth/<name>.
try:
if Path(os.path.expanduser(repo)).exists():
return
except OSError:
return
repo = f"unsloth/{repo}"
if not _is_hub_model_id(repo):
return
files = _hub_gguf_files(repo)
variant = gguf_variant or inline_variant
asks_gguf = _asks_gguf_quant(variant) or repo.lower().endswith(".gguf")
if files is not None and not files and (asks_gguf or not _this_host_loads_mlx()):
_fail_agent_needs_gguf(agent, repo)
if files is not None and not files and variant:
names = _hub_repo_files(repo)
if names is not None and f"{variant.strip()}/config.json" not in names:
_fail(f"{repo} has no precision folder {variant}.")
def _attach_gguf_check(
agent: _GgufAgent,
base: str,
key: str,
model: Optional[str],
variant: Optional[str] = None,
) -> None:
# Ask the server before the load evicts the resident model: only a live empty list is definitive; any error, older servers included, defers.
if not model:
return
repo, inline_variant = _split_repo_variant(model)
# `--model repo:QUANT` is split before the gate runs, so the caller passes the quant on.
variant = variant or inline_variant
# A .gguf filesystem path is GGUF by definition; only the hub-id shape owner/name.gguf is probed.
bare_missing_gguf = False
if repo.lower().endswith(".gguf") and not _is_model_path(repo.rsplit(".", 1)[0]):
try:
bare_missing_gguf = not Path(os.path.expanduser(repo)).exists()
except OSError:
bare_missing_gguf = False
if (
repo.lower().endswith(".gguf")
and not bare_missing_gguf
and not (
repo.count("/") == 1
and not repo.startswith(("/", ".", "~"))
and ":" not in repo
and "\\" not in repo
)
):
# Refuse companion or big-endian builds by name: otherwise load falls to transformers and unloads llama-server before failing.
refused = _direct_gguf_is_companion(repo) or _direct_gguf_is_big_endian(repo)
if refused:
_fail_agent_needs_gguf(agent, repo)
# A drafter folder further up is the server's call.
uncertain = _direct_gguf_companion_is_uncertain(repo)
# A direct file loads as itself; a matching sibling is never substituted.
if not refused and not uncertain:
# Only when this machine shares the server's filesystem, confirmed by identity (loopback may be an SSH or container forward), else defer.
# Otherwise an incomplete file loads and llama-server finds bytes missing only after teardown.
if is_loopback_url(base) and verify_studio_identity(base):
# A .gguf-NAMED DIRECTORY is scanned, not loaded, so the suffix proves nothing.
try:
is_gguf_dir = Path(os.path.expanduser(repo)).is_dir()
except OSError:
is_gguf_dir = False
if not is_gguf_dir:
# On loopback this reads the server's filesystem: a name missing from a listable dir is missing for the load too; unreadable parent defers.
try:
probe = Path(os.path.expanduser(repo))
missing = (
# A Windows path seen from WSL parses to nonsense, so defer.
_path_syntax_is_native(repo)
and not probe.is_symlink()
and probe.parent.is_dir()
and not probe.exists()
)
except OSError:
missing = False
if missing:
_fail(
f"{repo} does not exist. Check the path before "
f"pointing {agent.label} at it."
)
if not _direct_gguf_file_is_ready(repo):
_fail(
f"{repo} is incomplete (zero bytes or a split missing shards); "
f"re-download or re-copy it before pointing {agent.label} at it."
)
# Settle here only a spelling this OS can judge: a WSL-read Windows path would vouch for an unchecked file; explicit variant goes to probe.
if not variant and _path_syntax_is_native(repo):
return
# Do not read a remote server's filesystem; the load treats the .gguf suffix as authoritative, so ask the server. Errors still defer.
# Check the raw name first, as the load does; fall back to unsloth/<name> only when the raw name errors.
# A live answer settles the raw id; otherwise a non-GGUF directory in the server's cwd would pass the gate and evict.
candidates = [repo]
if "/" not in repo and (not _is_model_path(repo) or bare_missing_gguf):
candidates.append(f"unsloth/{repo}")
for candidate in candidates:
try:
info = _http_json(
"GET", f"{base}/api/models/gguf-variants?{urlencode({'repo_id': candidate})}", key
)
except Exception:
continue
variants = info.get("variants") if isinstance(info, dict) else None
if isinstance(variants, list):
# A cleanable row is an empty leftover <quant>/ folder, never weights.
variants = [
row for row in variants if not (isinstance(row, dict) and row.get("cleanable"))
]
# Non-local raw answers settle nothing; a server lacking the flag still counts its raw answer.
if (
"/" not in candidate
and candidate != candidates[-1]
and isinstance(info, dict)
and "resolved_locally" in info
and not info["resolved_locally"]
):
continue
# Server answer from the load resolver settles the round, even empty: a root-blind lister can miss a file the load still finds.
# MLX precision folders download on load, so the downloaded-only allow-list does not apply.
if (
isinstance(variants, list)
and isinstance(info, dict)
and info.get("variant_format") == "mlx"
):
folders = {row.get("quant") for row in variants if isinstance(row, dict)}
if variant and variant.strip() not in folders:
_fail_gguf_variant_missing(candidate, variant, variants)
_refuse_non_gguf(agent, candidate, base, key, None)
return
if isinstance(variants, list) and isinstance(info, dict):
offered = info.get("loadable_variants")
# No allow-list means a direct file, which loads as itself whatever the quant, so the variantless verdict decides.
if variant and offered is None and isinstance(info.get("loadable"), bool):
if not info["loadable"]:
_fail_agent_needs_gguf(agent, candidate)
return
if variant and isinstance(offered, list):
wanted_variant = str(variant).strip().lower()
if not any(
isinstance(q, str) and q.strip().lower() == wanted_variant for q in offered
):
_fail_gguf_variant_missing(candidate, variant, variants)
return
if not variant and isinstance(info.get("loadable"), bool):
if not info["loadable"]:
if variants:
_fail_agent_needs_gguf(agent, candidate)
_refuse_non_gguf(agent, candidate, base, key, variant)
return
if isinstance(variants, list) and variants:
# llama.cpp kills the resident model before resolving the quant, so settle it here; local answers take exact labels only.
# owner/name.gguf is exempt like a direct file, since a remote answer judged local would face local-only rules.
hub_shaped = (
candidate.count("/") == 1
and not candidate.startswith(("/", ".", "~"))
and ":" not in candidate
and "\\" not in candidate
)
local_answer = bool(info.get("resolved_locally")) or (
not hub_shaped and (_is_model_path(candidate) or "/" not in candidate)
)
# Only torn local rows: llama-server would fail after teardown.
if local_answer and all(
isinstance(row, dict) and row.get("partial") is True for row in variants
):
_fail(
f"{candidate} has only incomplete GGUF weights on the server; "
f"finish or re-copy the download before pointing {agent.label} at it."
)
# Variantless local load reads only the top level, so subdirectory-only rows need the variant; else it evicts for a load finding nothing.
if (
local_answer
and not variant
and variants
and all(
isinstance(row, dict)
and isinstance(row.get("filename"), str)
and "/" in row["filename"]
for row in variants
)
):
offered = ", ".join(
dict.fromkeys(
row["quant"]
for row in variants
if isinstance(row.get("quant"), str) and row["quant"]
)
)
_fail(
f"{candidate} keeps its GGUF weights in quant subdirectories, which a "
"variantless load cannot pick. Pass --gguf-variant"
+ (f" (available: {offered})." if offered else ".")
)
if variant and not _answer_offers_variant(variants, variant, strict = local_answer):
_fail_gguf_variant_missing(candidate, variant, variants)
return
if isinstance(variants, list):
# Explicit local syntax resolves locally on every server version, so its live empty answer settles the load; deferring would let the same GGUF-less directory go down the transformers path and evict. Only marker-less names keep deferring: older servers read them as hub ids, and a local hit may be a server-side model from the server's cwd, unless it reports resolved_locally. A bare foo.gguf naming no local file is only the canonicalized spelling, so it settles nothing until the canonical form has answered too.
if bare_missing_gguf and candidate != candidates[-1]:
continue
if not _is_model_path(repo) and not info.get("resolved_locally"):
try:
if Path(os.path.expanduser(repo)).exists():
return
except OSError:
return
_refuse_non_gguf(agent, candidate, base, key, variant)
return
def _require_gguf_for_agent(agent: _GgufAgent, base: str, key: str, model_id: str) -> None:
# Only a definite "no" rejects: the callers wrap this in `except BaseException: _shutdown_auto_served()`, so guessing kills a server that may have just loaded a GGUF.
try:
status = _model_status(base, key, model_id)
except urllib.error.HTTPError:
# Not evidence: get_status 500s from its own probes with a GGUF resident.
return
except (OSError, ValueError, http.client.HTTPException):
# Named explicitly, not `except Exception`, so typer.Exit and real bugs still surface.
return
if not isinstance(status, dict):
return
is_gguf = status.get("is_gguf")
# InferenceStatusResponse declares is_gguf non-optional under a response_model, so a current server always sends it. Absent means "not that endpoint", never "non-GGUF".
if is_gguf is None or is_gguf or status.get("is_mlx"):
return
# is_gguf carries a False default, so an idle server answers False while naming no model. The request that follows gets the server's own "No GGUF model loaded" anyway.
if not (status.get("active_model") or status.get("model_identifier")):
return
_fail_agent_needs_gguf(agent, model_id)
_DYNAMIC_SECTIONS_FLAG = "--exclude-dynamic-system-prompt-sections"
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 {})
settings_env.update(
{
"CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
"CLAUDE_CODE_SUBAGENT_MODEL": "inherit",
}
)
return json.dumps(
{
**(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 _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)
return settings
def _claude_version() -> Optional[tuple]:
# None means no local `claude` (a --no-launch printout for another machine; assume a current build). An unparseable version is treated as too old for the new flags.
executable = _which_with_install_dirs("claude")
if executable is None:
return None
try:
result = subprocess.run(
[executable, "--version"],
capture_output = True,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 10,
env = _probe_env(),
)
# Pull the X.Y.Z out of the output rather than assuming it is the first token: claude prints it first today ("2.1.98 (Claude Code)"), but a format change should not silently drop the optimization flags. No match falls through to "too old", same as an unparseable version.
match = re.search(r"(\d+)\.(\d+)\.(\d+)", result.stdout)
return tuple(int(part) for part in match.groups()) if match else (0,)
except Exception:
return (0,)
def _claude_flags(model_id: str, settings: Optional[str] = None) -> list:
# KV-cache-preserving flags: move per-session context out of the system prompt and pass the session overlay. claude < 2.1.98 rejects the dynamic-sections flag but already supports --settings; no local binary means a printout for another machine, so assume a current build.
version = _claude_version()
settings_flags = ["--settings", settings or _claude_settings_overlay(model_id)]
if version is not None and version < (2, 1, 98):
return settings_flags
return [_DYNAMIC_SECTIONS_FLAG, *settings_flags]
def _claude_local_command(model_id: str, settings: str, yolo: bool, passthrough: list) -> list:
local_args = [
"--model",
model_id,
*_claude_flags(model_id, settings),
*_yolo_command_flags("claude", yolo),
]
forwarded = list(passthrough)
separator = forwarded.index("--") if "--" in forwarded else len(forwarded)
before_separator = forwarded[:separator]
forwarded_settings = []
remaining = []
index = 0
while index < len(before_separator):
arg = before_separator[index]
if arg == "--settings" and index + 1 < len(before_separator):
forwarded_settings.extend(before_separator[index : index + 2])
index += 2
continue
if arg.startswith("--settings="):
forwarded_settings.append(arg)
else:
remaining.append(arg)
index += 1
return [
"claude",
*forwarded_settings,
*local_args,
*remaining,
*forwarded[separator:],
]
def _claude_local_env(
base: str,
key: str,
entry: dict,
extra_body: Optional[dict] = None,
) -> dict:
"""Build the local endpoint, cache, display, and compaction environment."""
model_id = entry["id"]
env = {
"ANTHROPIC_BASE_URL": base,
"ANTHROPIC_AUTH_TOKEN": key,
"ANTHROPIC_MODEL": model_id,
"CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
# Per-tool countdown reminders change the system prefix on local models.
"CLAUDE_CODE_TOTAL_TOKENS_REMINDER": "off",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
"CLAUDE_CODE_NO_FLICKER": "1",
}
window = entry.get("context_length") or entry.get("max_context_length")
if window:
# claude assumes 200k for a model id it does not recognize, and clamps AUTO_COMPACT_WINDOW to [100k, that]. MAX_CONTEXT_TOKENS sets the window itself.
env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] = str(int(window))
# Blank, not omitted, below the floor so an inherited value cannot apply; MAX_CONTEXT_TOKENS still bounds compaction there.
env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = (
str(int(window)) if int(window) >= _CLAUDE_MIN_AUTO_COMPACT_WINDOW else ""
)
env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] = "90"
# claude reserves min(max output, 20k) + 3k before compacting, so its 32k default output would take 20k of a 32k window; above 20k the cap gains no room.
output = opencode_output_limit(int(window))
if output < _CLAUDE_COMPACT_OUTPUT_RESERVE:
env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] = str(output)
if extra_body:
env["CLAUDE_CODE_EXTRA_BODY"] = json.dumps(extra_body)
return env
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 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'
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 + _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.
_CODEX_FALLBACK_PROMPT = Path(__file__).parent.parent / "codex_fallback_prompt.md"
_CODEX_MODEL_CATALOG_MIN_VERSION = (0, 110, 0)
_CODEX_PROFILE_FILE_MIN_VERSION = (0, 134, 0)
_CODEX_PATCH_LINE_ENDINGS_MIN_VERSION = (0, 148, 0)
# Older Codex sends no reasoning for a model without reasoning summaries, and older Pi has no samplingParams.
_CODEX_REASONING_REQUEST_MIN_VERSION = (0, 145, 0)
_PI_SAMPLING_PARAMS_MIN_VERSION = (0, 84, 0)
def _codex_executable_version(executable: str) -> Optional[tuple[int, int, int]]:
try:
output = subprocess.check_output(
[executable, "--version"],
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 10,
stderr = subprocess.DEVNULL,
env = _probe_env(),
)
except Exception:
return None
match = re.search(r"(\d+)\.(\d+)\.(\d+)", output)
return tuple(int(part) for part in match.groups()) if match else None
def _codex_update_hint(executable: str) -> Optional[str]:
# Update the copy that resolves: a new one in ~/.local/bin sits behind an older one earlier on PATH, so an unknown install gets None.
if any(part in ("Cellar", "Caskroom") for part in Path(os.path.realpath(executable)).parts):
return "brew upgrade codex"
directory = Path(executable).parent
prefix = directory if os.name == "nt" else directory.parent
package = prefix / ("node_modules" if os.name == "nt" else "lib/node_modules") / "@openai/codex"
if package.is_dir():
return _npm_install_hint("@openai/codex@latest", prefix = prefix)
return None
def _codex_supports_model_catalog() -> bool:
executable = _which_with_install_dirs("codex")
if executable is None:
# A --no-launch recipe may be copied to another machine; assume a current Codex.
return True
version = _codex_executable_version(executable)
return version is not None and version >= _CODEX_MODEL_CATALOG_MIN_VERSION
def _agent_version_at_least(command: str, minimum: tuple) -> bool:
executable = _which_with_install_dirs(command)
if executable is None:
# Only --no-launch gets here without the agent; its recipe may run elsewhere.
return True
version = _codex_executable_version(executable)
return version is not None and version >= minimum
def _codex_supports_patch_line_endings() -> bool:
executable = _which_with_install_dirs("codex")
if executable is None:
# A normal launch installs Codex after this check; no-launch may run elsewhere.
return True
version = _codex_executable_version(executable)
return version is not None and version >= _CODEX_PATCH_LINE_ENDINGS_MIN_VERSION
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")
entry = {
"slug": model_id,
"display_name": model_id,
"description": "Model served by Unsloth Studio",
"supported_reasoning_levels": [],
"shell_type": "default",
"visibility": visibility,
"supported_in_api": True,
"priority": 99,
"availability_nux": None,
"upgrade": None,
"base_instructions": _CODEX_FALLBACK_PROMPT.read_text(encoding = "utf-8"),
"supports_reasoning_summaries": False,
"supports_reasoning_summary_parameter": False,
"support_verbosity": False,
"default_verbosity": None,
"apply_patch_tool_type": "freeform",
"truncation_policy": {"mode": "bytes", "limit": 10_000},
"supports_parallel_tool_calls": False,
"experimental_supported_tools": [],
}
if window:
entry["context_window"] = int(window)
entry["max_context_window"] = int(window)
return {"models": [entry]}
_TOML_KEY_PART = re.compile(
r"""[ \t]*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|([A-Za-z0-9_-]+))[ \t]*([.\]])"""
)
_TOML_STRING = re.compile(r'"(?:[^"\\]|\\.)*"|\'[^\']*\'')
def _toml_table_path(chunk: str) -> Optional[tuple]:
"""Key path of the [table] or [[array]] header opening chunk, whatever its quoting or comment."""
line = chunk.lstrip(" \t")
if not line.startswith("["):
return None
parts, pos = [], 2 if line.startswith("[[") else 1
while True:
m = _TOML_KEY_PART.match(line, pos)
if m is None:
return None
parts.append(next(g for g in m.groups()[:3] if g is not None))
pos = m.end()
if m.group(4) == "]":
return tuple(parts)
def _toml_chunks(text: str) -> list:
"""Split before each table header; a "[" line inside a string or an array is not one."""
chunks, current, delim, depth = [], "", None, 0
for line in text.splitlines(True):
if delim is None and depth == 0 and line.lstrip(" \t").startswith("["):
chunks.append(current)
current = line
continue
current += line
i = 0
while i < len(line):
if delim is not None:
if line.startswith(delim, i):
# Up to two quotes may end the string just before its closing delimiter.
run = len(line) - i - len(line[i:].lstrip(delim[0]))
delim, i = None, i + min(run, 5)
else:
i += 2 if delim == '"""' and line[i] == "\\" else 1
continue
c = line[i]
if c == "#":
break
if line.startswith(('"""', "'''"), i):
delim, i = line[i : i + 3], i + 3
continue
if c in "\"'":
m = _TOML_STRING.match(line, i)
i = m.end() if m else len(line)
continue
depth += (c in "[{") - (c in "]}")
i += 1
chunks.append(current)
return chunks
def _toml_loads():
try:
import tomllib # novermin
except ImportError:
try:
import tomli as tomllib
except ImportError:
return None
return tomllib.loads
def _toml_parses(text: str) -> Optional[bool]:
loads = _toml_loads()
if loads is None:
return None
try:
loads(text)
except ValueError:
return False
return True
def _toml_key(key: str) -> str:
return key if re.fullmatch(r"[A-Za-z0-9_-]+", key) else _toml_value(key)
def _toml_value(value) -> str:
if isinstance(value, bool):
return "true" if value else "false"
if isinstance(value, str):
# JSON string escapes are TOML's, except that TOML also forbids a raw DEL.
return json.dumps(value, ensure_ascii = False).replace("\x7f", "\\u007f")
if isinstance(value, float) and value != value:
return "nan"
if isinstance(value, float) and value in (float("inf"), float("-inf")):
return "inf" if value > 0 else "-inf"
if isinstance(value, (int, float)):
return repr(value)
if isinstance(value, list):
return "[" + ", ".join(_toml_value(v) for v in value) + "]"
if isinstance(value, dict):
return (
"{ " + ", ".join(f"{_toml_key(k)} = {_toml_value(v)}" for k, v in value.items()) + " }"
)
return value.isoformat() # TOML dates and times
_CODEX_MCP_MANIFEST = "unsloth_mcp_servers.json"
def _codex_mcp_server(chunk: str) -> Optional[tuple]:
# The server a [mcp_servers.NAME...] table belongs to: owning NAME owns its subtables. A bare
# [mcp_servers] table can mix servers from two homes, so it is never owned as a whole.
path = _toml_table_path(chunk)
return path[:2] if path and len(path) > 1 and path[0] == "mcp_servers" else None
def _codex_mcp_manifest(home: Path) -> tuple:
"""(home it was built from, the user's own home at the end of that chain, inherited servers)."""
try:
state = json.loads((home / _CODEX_MCP_MANIFEST).read_text(encoding = "utf-8"))
inherited = {tuple(path)[:2] for path in state["tables"]}
source, origin = state.get("source"), state.get("origin")
except (OSError, ValueError, TypeError, KeyError, AttributeError):
return None, None, set()
source = source if isinstance(source, str) else None
return source, origin if isinstance(origin, str) else source, inherited
def _codex_mcp_followed(home: Path) -> Optional[Path]:
# A source that was itself a temporary session home is gone once that session exits.
source, origin, _ = _codex_mcp_manifest(home)
for candidate in (source, origin):
if candidate and Path(candidate).is_dir():
return Path(candidate)
return None
def _codex_mcp_tables(source: Path, seen: frozenset) -> list:
"""MCP tables in source's config; a home Unsloth built trades its inherited ones for its origin's."""
try:
text = (source / "config.toml").read_text(encoding = "utf-8-sig")
except OSError:
return []
loads = _toml_loads()
try:
# Parsed, so root dotted keys, inline tables and a bare [mcp_servers] all count.
servers = loads(text).get("mcp_servers") if loads else None
except ValueError:
loads = (
None # TOML 1.1, which Codex reads and tomllib does not: copy the tables as written.
)
if loads is None:
tables = [c for c in _toml_chunks(text) if _codex_mcp_server(c)]
else:
tables = [
f"[mcp_servers.{_toml_key(name)}]\n"
+ "".join(f"{_toml_key(k)} = {_toml_value(v)}\n" for k, v in spec.items())
+ "\n"
for name, spec in (servers.items() if isinstance(servers, dict) else ())
if isinstance(spec, dict)
]
_, _, inherited = _codex_mcp_manifest(source)
upstream_home = _codex_mcp_followed(source)
if upstream_home is not None and str(upstream_home.resolve(strict = False)) not in seen:
upstream = _codex_mcp_tables(
upstream_home, seen | {str(upstream_home.resolve(strict = False))}
)
# The origin wins a name clash, as it does when that saved home is synced.
taken = inherited | {_codex_mcp_server(c) for c in upstream}
tables = [c for c in tables if _codex_mcp_server(c) not in taken] + upstream
return tables
def _codex_user_home(home: Path) -> Path:
source = _codex_source_home()
home_key = home.resolve(strict = False)
if source.resolve(strict = False) != home_key:
return source
# The printed recipe exports CODEX_HOME=home: keep reading the home it was built from.
followed = _codex_mcp_followed(home)
if followed is not None and followed.resolve(strict = False) != home_key:
return followed
return _codex_source_home(ignore_configured = True)
def _with_user_codex_mcp_servers(text: str, home: Path, source: Path) -> str:
_, _, carried = _codex_mcp_manifest(home)
home_key = home.resolve(strict = False)
source_key = str(source.resolve(strict = False))
tables = _codex_mcp_tables(source, frozenset({str(home_key), source_key}))
# Only replace what came from the user's config; servers added in this home stay.
servers = {_codex_mcp_server(c) for c in tables}
carried |= servers
out = "".join(c for c in _toml_chunks(text) if _codex_mcp_server(c) not in carried)
if tables:
out = out.rstrip("\n") + "\n\n" + "\n\n".join(c.rstrip("\n") for c in tables) + "\n"
if _toml_parses(out) is False:
return text
_, origin, _ = _codex_mcp_manifest(source)
# Written even when empty: a recipe shell's CODEX_HOME=home must still find a custom origin.
(home / _CODEX_MCP_MANIFEST).write_text(
json.dumps(
{"source": source_key, "origin": origin or source_key, "tables": sorted(servers)}
)
+ "\n",
encoding = "utf-8",
)
return out
def write_codex_config(
base: str,
model: dict,
home: Path,
reasoning_effort: Optional[str] = None,
keep_mcp_servers: bool = False,
) -> None:
home.mkdir(parents = True, exist_ok = True)
config = home / "config.toml"
existing = config.read_text(encoding = "utf-8") if config.exists() else ""
merged = _merge_codex_config(existing, base)
if keep_mcp_servers:
source = _codex_user_home(home)
merged = _with_user_codex_mcp_servers(merged, home, source)
_link_codex_user_files(home, source)
if merged != existing:
config.write_text(merged, encoding = "utf-8")
typer.echo(f"Updated {config}")
# oss_provider here too: codex --oss picks the provider from it, and the profile layer must beat a user-set value ("ollama") in config.toml.
profile_text = (
f'oss_provider = "{_CODEX_PROFILE}"\n'
f'model_provider = "{_CODEX_PROFILE}"\n'
f"model = {json.dumps(model['id'])}\n"
)
if _codex_supports_patch_line_endings():
profile_text += (
"suppress_unstable_features_warning = true\n"
"features.apply_patch_preserve_line_endings = true\n"
)
if _codex_supports_model_catalog() and _CODEX_FALLBACK_PROMPT.is_file():
catalog = home / "model-catalog.json"
catalog_text = json.dumps(_codex_model_catalog(model), indent = 2) + "\n"
if not catalog.exists() or catalog.read_text(encoding = "utf-8") != catalog_text:
catalog.write_text(catalog_text, encoding = "utf-8")
typer.echo(f"Updated {catalog}")
# Resolve relative to the profile file. This also survives WSL launching a Windows Codex binary, where a Linux absolute path inside TOML would not be usable.
profile_text += f"model_catalog_json = {json.dumps(catalog.name)}\n"
window = model.get("context_length") or model.get("max_context_length")
if window:
profile_text += f"model_context_window = {int(window)}\n"
if reasoning_effort:
profile_text += f"model_reasoning_effort = {json.dumps(reasoning_effort)}\n"
profile = home / f"{_CODEX_PROFILE}.config.toml"
if not profile.exists() or profile.read_text(encoding = "utf-8") != profile_text:
profile.write_text(profile_text, encoding = "utf-8")
typer.echo(f"Updated {profile}")
def write_codex_subagent_bridge(
base: str,
key: str,
model: dict,
home: Path,
*,
yolo: bool,
reasoning_effort: Optional[str] = None,
auto_route: bool = False,
) -> Path:
"""Write private config for an explicit local Codex child launched through MCP."""
child_home = home / "child"
write_codex_config(base, model, child_home, reasoning_effort)
path = home / "subagent.json"
_write_private_json(
path,
{
"api_key": key,
"codex_home": str(child_home),
"bypass_permissions": yolo,
**({"auto_route": True} if auto_route else {}),
},
)
return path
def _wsl_windows_user_profile(executable: str, app: str = "Codex") -> Path:
"""Return the Windows user profile as a path accessible from WSL."""
profile = os.environ.get("USERPROFILE", "").strip()
if not profile:
try:
profile = subprocess.check_output(
["cmd.exe", "/d", "/c", "echo %USERPROFILE%"],
text = True,
encoding = "utf-8",
# The path is the value: a corrupted home is worse than a loud failure.
errors = "strict",
stderr = subprocess.DEVNULL,
cwd = str(Path(executable).parent),
).strip()
except UnicodeDecodeError as exc:
_fail(
f"Could not read the Windows user profile for {app} ({exc}); "
"set USERPROFILE in the WSL environment, for example through WSLENV."
)
except (OSError, subprocess.CalledProcessError) as exc:
_fail(f"Could not find the Windows user profile for {app}: {exc}")
if not profile or profile == "%USERPROFILE%":
_fail(f"Could not find the Windows user profile for {app}.")
if profile.startswith("/"):
return Path(profile)
try:
translated = subprocess.check_output(
["wslpath", "-u", profile],
text = True,
encoding = "utf-8",
errors = "replace",
stderr = subprocess.DEVNULL,
).strip()
except (OSError, subprocess.CalledProcessError) as exc:
_fail(f"Could not translate Windows user profile {profile}: {exc}")
if not translated:
_fail(f"Could not translate Windows user profile {profile}.")
return Path(translated)
def _codex_source_home(*, ignore_configured: bool = False) -> Path:
configured = None if ignore_configured else os.environ.get("CODEX_HOME")
if configured:
if _wsl_windows_executable(["codex"]) and _looks_like_path(configured):
if not configured.startswith("/"):
try:
configured = subprocess.check_output(
["wslpath", "-u", configured],
text = True,
encoding = "utf-8",
errors = "replace",
stderr = subprocess.DEVNULL,
).strip()
except (OSError, subprocess.CalledProcessError) as exc:
_fail(f"Could not translate Windows CODEX_HOME {configured}: {exc}")
if not configured:
_fail("Could not translate Windows CODEX_HOME.")
return Path(configured).expanduser()
executable = _wsl_windows_executable(["codex"])
if executable:
return _wsl_windows_user_profile(executable) / ".codex"
return Path.home() / ".codex"
def _is_junction(path: Path) -> bool:
# Path.is_junction() was added in Python 3.12.
if hasattr(path, "is_junction"):
return path.is_junction()
try:
return (
getattr(os.lstat(path), "st_reparse_tag", None) == 0xA0000003
) # IO_REPARSE_TAG_MOUNT_POINT
except OSError:
return False
def _is_directory_link(path: Path) -> bool:
# lstat reads the link, so FILE_ATTRIBUTE_DIRECTORY answers even when dangling.
try:
return bool(getattr(os.lstat(path), "st_file_attributes", 0) & 0x10)
except OSError:
return False
def _remove_overlay_entry(path: Path) -> None:
if _is_junction(path):
path.rmdir()
elif os.name == "nt" and path.is_symlink() and _is_directory_link(path):
# DeleteFileW, which unlink maps to, refuses a directory entry; rmdir drops the link.
path.rmdir()
elif path.is_symlink() or path.is_file():
path.unlink()
elif path.is_dir():
shutil.rmtree(path)
elif path.exists():
path.unlink()
def _create_directory_junction(source: Path, target: Path) -> bool:
if os.name != "nt":
return False
try:
result = subprocess.run(
["cmd.exe", "/d", "/c", "mklink", "/J", str(target), str(source)],
capture_output = True,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 30,
check = False,
)
except (OSError, subprocess.SubprocessError):
return False
return result.returncode == 0
def _link_codex_entry(source: Path, target: Path) -> bool:
_remove_overlay_entry(target)
try:
target.symlink_to(source, target_is_directory = source.is_dir())
return True
except OSError:
pass
if source.is_file():
# Only auth.json: Codex rewrites it in place, but a SQLite db under a second name keeps its own WAL and corrupts (sqlite.org/howtocorrupt.html 2.6).
if source.name == "auth.json":
with contextlib.suppress(OSError):
os.link(source, target)
return True
shutil.copy2(source, target)
return True
if source.is_dir():
if _create_directory_junction(source, target):
return True
if source.name in _CODEX_COPIED_DIRS:
shutil.copytree(source, target)
return True
return False
def _link_codex_user_files(home: Path, source: Path) -> None:
manifest = home / _CODEX_USER_FILES_MANIFEST
try:
linked = json.loads(manifest.read_text(encoding = "utf-8"))["entries"]
except (OSError, ValueError, TypeError, KeyError):
linked = []
for entry in linked if isinstance(linked, list) else []:
parts = entry.split("/") if isinstance(entry, str) else []
if (
0 < len(parts) <= 2
and parts[0] in _CODEX_USER_FILES
and all(part not in ("", ".", "..") and "\\" not in part for part in parts)
and os.path.lexists(home.joinpath(*parts))
):
_remove_overlay_entry(home.joinpath(*parts))
entries = []
for name in _CODEX_USER_FILES:
# Resolved: a relative or temporary source would leave dangling links.
entry = (source / name).resolve(strict = False)
target = home / name
if not entry.exists():
continue
if name == "rules" and entry.is_dir() and not os.path.lexists(target):
# Codex appends approvals to rules/default.rules: a linked dir would write them into the user's.
target.mkdir()
if not os.path.lexists(target):
if _link_codex_entry(entry, target):
entries.append(name)
elif (
entry.is_dir()
and target.is_dir()
and not target.is_symlink()
and not _is_junction(target)
):
# Codex creates skills/.system in every home it runs in.
for child in entry.iterdir():
child_target = target / child.name
if name == "rules" and child.is_file():
# Codex skips symlinked *.rules (DirEntry::file_type); default.rules stays this home's.
if child.name == "default.rules" or os.path.lexists(child_target):
child_target = target / f"user-{child.name}"
if os.path.lexists(child_target):
continue
try:
os.link(child.resolve(strict = False), child_target)
except OSError:
shutil.copy2(child, child_target)
elif os.path.lexists(child_target) or not _link_codex_entry(
child.resolve(strict = False), child_target
):
continue
entries.append(f"{name}/{child_target.name}")
_write_private_json(manifest, {"entries": entries})
def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:
"""Add local-agent routing without replacing the cloud parent's configuration."""
overlay.mkdir(parents = True, exist_ok = True, mode = 0o700)
manifest_path = overlay / _CODEX_PARENT_OVERLAY_MANIFEST
try:
manifest = json.loads(manifest_path.read_text(encoding = "utf-8"))
except (FileNotFoundError, OSError, json.JSONDecodeError):
manifest = None
source_home = _codex_source_home()
overlay_key = str(overlay.resolve(strict = False))
source_key = str(source_home.resolve(strict = False))
if source_key == overlay_key:
previous_source = manifest.get("source_home") if isinstance(manifest, dict) else None
if isinstance(previous_source, str) and previous_source:
candidate = Path(previous_source).expanduser()
if str(candidate.resolve(strict = False)) != overlay_key:
source_home = candidate
else:
source_home = _codex_source_home(ignore_configured = True)
else:
source_home = _codex_source_home(ignore_configured = True)
source_key = str(source_home.resolve(strict = False))
same_source = isinstance(manifest, dict) and manifest.get("source_home") == source_key
if same_source:
managed_entries = manifest.get("entries", [])
if not isinstance(managed_entries, list):
managed_entries = []
for name in managed_entries:
if isinstance(name, str) and name not in {"", ".", ".."} and Path(name).name == name:
_remove_overlay_entry(overlay / name)
else:
# A reused overlay must never mix credentials, config, or plugins from two different Codex homes. Legacy overlays have no manifest, so rebuild them once.
for target in list(overlay.iterdir()):
_remove_overlay_entry(target)
entries = []
if source_home.is_dir():
for source in source_home.iterdir():
if source.name in {
"AGENTS.md",
"AGENTS.override.md",
_CODEX_PARENT_OVERLAY_MANIFEST,
}:
continue
if _link_codex_entry(source, overlay / source.name):
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,
{"source_home": source_key, "entries": sorted(entries)},
)
inherited = ""
instruction_name = "AGENTS.md"
for candidate in (source_home / "AGENTS.override.md", source_home / "AGENTS.md"):
try:
text = candidate.read_text(encoding = "utf-8")
except FileNotFoundError:
continue
except OSError as exc:
_fail(f"Could not preserve Codex instructions from {candidate}: {exc}")
if text.strip():
inherited = text.rstrip()
instruction_name = candidate.name
break
other_name = "AGENTS.md" if instruction_name == "AGENTS.override.md" else "AGENTS.override.md"
other = overlay / other_name
if other.is_file() or other.is_symlink():
other.unlink()
routing = _CODEX_SUBAGENT_ROUTING_INSTRUCTIONS
if auto_route:
routing = f"{routing}\n\n{_CODEX_AUTO_ROUTE_INSTRUCTIONS}"
combined = f"{inherited}\n\n{routing}\n" if inherited else f"{routing}\n"
_write_private_text(overlay / instruction_name, combined)
return overlay
def _agent_config_path(path: Path, command: list) -> str:
"""Translate a generated config path when a Windows agent runs through WSL."""
return _wsl_windows_path(path) if _wsl_windows_executable(command) else str(path)
_OPENCODE_ROUTE_PLUGIN_SCRIPT = """\
const LOCAL = new Set(%(local)s);
const ROUTED = new Set(%(routed)s);
const HIDDEN = new Set(["title", "summary", "compaction"]);
const agents = new Map();
// Set when a local run fails, so the parent can do that step itself until the next local run succeeds.
let failed = false;
export const UnslothAutoRoute = async () => ({
"chat.params": async ({ sessionID, agent }) => {
if (!HIDDEN.has(agent)) agents.set(sessionID, agent);
},
event: async ({ event }) => {
const { sessionID, error } = event.properties ?? {};
if (event.type === "session.error" && LOCAL.has(agents.get(sessionID)) && error?.name !== "MessageAbortedError") failed = true;
},
"tool.execute.after": async ({ tool, args }) => {
if (tool === "task" && LOCAL.has(args?.subagent_type)) failed = false;
},
"tool.execute.before": async ({ tool, sessionID }) => {
const agent = agents.get(sessionID);
if (failed || !ROUTED.has(tool) || LOCAL.has(agent)) return;
throw new Error(
"Blocked by Unsloth --auto-route: files and the shell are only reachable through the local " +
"agent. Hand the complete task to the @" + (agent === "plan" ? %(plan)s : %(build)s) +
" subagent with the task tool instead.",
);
},
});
""" % {
"local": json.dumps([_SUBAGENT_NAME, _OPENCODE_PLAN_SUBAGENT_NAME]),
"routed": json.dumps(list(_OPENCODE_ROUTED_TOOLS)),
"plan": json.dumps(_OPENCODE_PLAN_SUBAGENT_NAME),
"build": json.dumps(_SUBAGENT_NAME),
}
def _opencode_subagent_inline_config(
path: Path,
permission: dict,
command: str = "opencode",
v2: bool = False,
auto_route: bool = False,
) -> dict:
"""Keep the local provider visible without hiding the parent's allowed providers."""
inline: dict = {}
inherited = os.environ.get("OPENCODE_CONFIG_CONTENT")
if inherited:
try:
parsed = json.loads(inherited)
except ValueError:
_fail("OPENCODE_CONFIG_CONTENT is not valid JSON.")
if not isinstance(parsed, dict):
_fail("OPENCODE_CONFIG_CONTENT must contain a JSON object.")
inline.update(parsed)
def merge_provider_filters(effective_config: dict) -> None:
enabled = effective_config.get("enabled_providers")
if isinstance(enabled, list):
inherited_enabled = inline.get("enabled_providers")
if not isinstance(inherited_enabled, list):
inherited_enabled = []
providers = [
provider
for provider in [*inherited_enabled, *enabled]
if provider != _OPENCODE_PROVIDER
]
inline["enabled_providers"] = list(dict.fromkeys([*providers, _OPENCODE_PROVIDER]))
disabled = effective_config.get("disabled_providers")
if isinstance(disabled, list) and _OPENCODE_PROVIDER in disabled:
inline["disabled_providers"] = [
provider for provider in disabled if provider != _OPENCODE_PROVIDER
]
# Keep an inherited inline allowlist usable by the local provider. V2 turns these filters into policies where global/project rules still intentionally outrank this content; the message at launch makes that boundary explicit.
merge_provider_filters(inline)
effective = inline
executable = None if v2 else _which_with_install_dirs(command)
if v2:
legacy_depth = inline.pop("subagent_depth", None)
if (
isinstance(legacy_depth, int)
and not isinstance(legacy_depth, bool)
and legacy_depth > 0
):
experimental = inline.get("experimental")
if not isinstance(experimental, dict):
experimental = {}
experimental.setdefault("subagent_depth", legacy_depth)
inline["experimental"] = experimental
elif executable is None:
typer.echo(
f"Warning: OpenCode is not installed, so provider filters could not be checked. "
f"The target configuration must allow '{_OPENCODE_PROVIDER}'.",
err = True,
)
else:
env = _probe_env(OPENCODE_CONFIG = _agent_config_path(path, [command]))
try:
resolved = subprocess.run(
[executable, "debug", "config"],
capture_output = True,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 15,
env = env,
)
except Exception as exc:
_fail(f"Could not inspect OpenCode provider filters: {exc}")
if resolved.returncode != 0:
detail = resolved.stderr.strip() or resolved.stdout.strip()
_fail(f"Could not inspect OpenCode provider filters: {detail or 'unknown error'}")
try:
effective = json.loads(resolved.stdout)
except ValueError:
_fail("Could not inspect OpenCode provider filters: invalid JSON response.")
if not isinstance(effective, dict):
_fail("Could not inspect OpenCode provider filters: expected a JSON object.")
merge_provider_filters(effective)
if not v2:
depth = effective.get("subagent_depth")
inline["subagent_depth"] = (
depth if isinstance(depth, int) and not isinstance(depth, bool) and depth > 0 else 1
)
if permission:
inline["permission"] = permission
plugin = path.parent / _OPENCODE_ROUTE_PLUGIN
if auto_route and not v2:
_write_private_text(plugin, _OPENCODE_ROUTE_PLUGIN_SCRIPT)
# OpenCode adds each layer's plugins to the others', so only an inherited inline list needs keeping.
plugins = inline.get("plugin")
inline["plugin"] = [
*(plugins if isinstance(plugins, list) else []),
_agent_config_path(plugin, [command]),
]
else:
# A persisted session dir may still hold the plugin from an earlier --auto-route run.
plugin.unlink(missing_ok = True)
if auto_route:
# The V2 CLI has no tool hooks, so there read and bash fall back to permission rules.
denied = _OPENCODE_HIDDEN_TOOLS + (_OPENCODE_ROUTED_TOOLS if v2 else ())
permission = {
**dict.fromkeys((*denied, "edit"), "deny"),
"task": {"*": "deny", _SUBAGENT_NAME: "allow"},
}
# Plan keeps its own edit rules (it may write only its plan file) and reaches the read-only agent.
plan_permission = {
**dict.fromkeys(denied, "deny"),
"task": {"*": "deny", _OPENCODE_PLAN_SUBAGENT_NAME: "allow"},
}
# An agent's own permission outranks the global one, so restrict by name every agent a user can be in (an @mention skips the task rule).
agents = _subdict(inline, "agent")
configured = effective.get("agent")
names = {
"build",
"general",
"explore",
*(configured if isinstance(configured, dict) else ()),
}
for name in names - {"plan", _SUBAGENT_NAME, _OPENCODE_PLAN_SUBAGENT_NAME}:
_subdict(_subdict(agents, name), "permission").update(permission)
_subdict(_subdict(agents, "plan"), "permission").update(plan_permission)
return inline
def _b64_path(path: Path) -> str:
"""Path as base64, so it can cross a shell without being expanded."""
return base64.b64encode(str(path).encode("utf-8")).decode("ascii")
_CLAUDE_PLAN_GATE_SCRIPT = '''\
"""Deny the editing agent while the parent session is in plan mode."""
import json, sys
try:
mode = (json.load(sys.stdin) or {}).get("permission_mode")
except Exception:
sys.exit(0) # fail open: a hook error must never block the parent session
if mode == "plan":
print(json.dumps({"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": (
"Plan mode is active. Call the read-only Unsloth plan agent "
"(unsloth_plan_agent) instead of unsloth_agent."
),
}}))
sys.exit(0)
'''
_CLAUDE_ROUTE_GATE_SCRIPT = """\
import json, os, sys
# The local agent server leaves this file after a failed run, so the parent can do that step itself.
if os.path.exists(os.path.join(os.path.dirname(__file__), "local-agent-failed")):
sys.exit(0)
print(json.dumps({"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": (
"Blocked by Unsloth --auto-route: files and the shell are only reachable through "
"the local agent. Call the unsloth_agent tool with the complete task instead."
),
}}))
sys.exit(0)
"""
# PowerShell is the shell on Windows without Git Bash, Monitor runs commands too, and Agent (Task before Claude Code 2) would hand the same work to a cloud subagent.
_CLAUDE_ROUTE_GATE_MATCHER = "Read|Grep|Glob|Bash|PowerShell|Monitor|NotebookRead|Agent|Task"
_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.
"command": (
f'"{sys.executable}" -c '
f'"import base64,runpy; runpy.run_path('
f"base64.b64decode('{_b64_path(gate)}').decode())\""
),
# A hook with no timeout stalls the parent for as long as it hangs; measured unbounded past 400s.
"timeout": 10,
}
def write_claude_subagent_plugin(path: Path, server_env: dict) -> Path:
"""Write a session plugin that exposes the local Claude child through MCP."""
plugin = path / "unsloth-local-agent"
command = sys.executable
args = ["-m", _CLAUDE_SUBAGENT_MCP_MODULE]
mcp_env = dict(server_env)
base = server_env.get("UNSLOTH_CLAUDE_SUBAGENT_BASE_URL")
key = server_env.get("UNSLOTH_CLAUDE_SUBAGENT_API_KEY")
model_id = server_env.get("UNSLOTH_CLAUDE_SUBAGENT_MODEL")
if base and key and model_id:
entry = {
"id": model_id,
"context_length": int(
server_env.get("UNSLOTH_CLAUDE_SUBAGENT_CONTEXT_WINDOW", "0") or 0
),
}
local_env = _claude_local_env(base, key, entry)
if "CLAUDE_CODE_EXTRA_BODY" in server_env:
local_env["CLAUDE_CODE_EXTRA_BODY"] = server_env["CLAUDE_CODE_EXTRA_BODY"]
settings = _write_claude_settings(plugin, model_id, local_env)
mcp_env[_CLAUDE_SUBAGENT_SETTINGS_ENV] = str(settings)
if _wsl_windows_executable(["claude"]):
command = "wsl.exe"
args = [
"-d",
os.environ["WSL_DISTRO_NAME"],
"--",
sys.executable,
"-m",
_CLAUDE_SUBAGENT_MCP_MODULE,
]
mcp_env["WSLENV"] = _merge_wslenv(
os.environ.get("WSLENV", ""),
(
*_wsl_bridge_names(server_env, ()),
*([_CLAUDE_SUBAGENT_SETTINGS_ENV] if base and key and model_id else []),
),
)
auto_route = server_env.get(_CLAUDE_SUBAGENT_AUTO_ROUTE_ENV) == "1"
fallback = plugin / "hooks" / _CLAUDE_ROUTE_FALLBACK_FILE
if auto_route and command != "wsl.exe":
mcp_env[_CLAUDE_SUBAGENT_FALLBACK_ENV] = str(fallback)
_write_private_json(
plugin / ".claude-plugin" / "plugin.json",
{
"name": "unsloth-local-agent",
"version": "1.0.0",
"description": _SUBAGENT_DESCRIPTION,
"author": {"name": "Unsloth AI"},
},
)
_write_private_json(
plugin / ".mcp.json",
{
"mcpServers": {
"unsloth": {
"type": "stdio",
"command": command,
"args": args,
"env": mcp_env,
}
}
},
)
# Claude already refuses the editing tool in plan mode, since it advertises readOnlyHint false. This PreToolUse hook replaces that dead end with a reason naming the read-only tool to call instead. Skipped under the WSL bridge, where the gate is a Linux path but the hook would run beside the Windows claude.
gate = plugin / "hooks" / "plan_gate.py"
route_gate = plugin / "hooks" / "route_gate.py"
# A persisted plugin dir may still hold gates, or a failure left by an earlier session.
fallback.unlink(missing_ok = True)
if command == "wsl.exe" or not auto_route:
route_gate.unlink(missing_ok = True)
if command == "wsl.exe":
for stale in (gate, plugin / "hooks" / "hooks.json"):
stale.unlink(missing_ok = True)
else:
_write_private_text(gate, _CLAUDE_PLAN_GATE_SCRIPT)
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, exec_form)],
}
)
_write_private_json(plugin / "hooks" / "hooks.json", {"hooks": {"PreToolUse": entries}})
skill = plugin / "skills" / "local-agent" / "SKILL.md"
skill.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
when = (
"Use it for routine, self-contained work (codebase search, reading files, running "
"tests or commands, mechanical edits) without being asked, and whenever the user asks "
"for an Unsloth or local agent."
if auto_route
else "Use when the user asks to spawn an Unsloth agent or local agent."
)
skill.write_text(
"---\n"
f"description: Delegate a task to the local agent powered by Unsloth. {when}\n"
"---\n\n"
"Call the Unsloth local agent tool once with the complete task. In plan mode, call "
"the read-only Unsloth plan agent instead. Return its result to the user without "
"claiming that the cloud parent completed the local work.\n",
encoding = "utf-8",
)
return plugin
def _codex_subagent_flags(path: Path) -> list[str]:
command = sys.executable
package_root = str(Path(__file__).resolve().parents[2])
bootstrap = (
f"import sys;sys.path.insert(0,{json.dumps(package_root)});"
f"from {_CODEX_SUBAGENT_MCP_MODULE} import main;main()"
)
args = ["-c", bootstrap, str(path)]
if _wsl_windows_executable(["codex"]):
command = "wsl.exe"
args = [
"-d",
os.environ["WSL_DISTRO_NAME"],
"--",
sys.executable,
"-c",
bootstrap,
str(path),
]
server = (
"{ "
f"command = {json.dumps(command)}, "
f"args = {json.dumps(args)}, "
f"required = true, enabled_tools = [{json.dumps(_CODEX_SUBAGENT_MCP_TOOL)}], "
'default_tools_approval_mode = "approve", '
"startup_timeout_sec = 15, tool_timeout_sec = 3600 }"
)
return ["-c", f"mcp_servers.{_CODEX_SUBAGENT_MCP_SERVER}={server}"]
def _wsl_windows_executable(command: list) -> Optional[str]:
if os.name == "nt" or not os.environ.get("WSL_DISTRO_NAME"):
return None
executable = shutil.which(command[0])
if executable and executable.startswith("/mnt/"):
return executable
return None
def _wsl_windows_path(path: Path) -> str:
try:
translated = subprocess.check_output(
["wslpath", "-w", str(path)], text = True, encoding = "utf-8", errors = "replace"
).strip()
except (OSError, subprocess.CalledProcessError) as exc:
_fail(f"Could not translate WSL path {path}: {exc}")
if not translated:
_fail(f"Could not translate WSL path {path}")
return translated
def _looks_like_path(value: str) -> bool:
# A var only wants the WSLENV /p flag if its value is a filesystem path: an absolute POSIX path (/...), a UNC path (\\\\...), or a drive-qualified Windows path (C:...). Scalar knobs such as a numeric context window must pass through untranslated, so they get no flag.
return bool(value) and (value.startswith(("/", "\\")) or (len(value) >= 2 and value[1] == ":"))
def _wsl_bridge_names(env: dict, unset_env: tuple) -> tuple:
# Build the WSLENV share list for a Windows shim reached from WSL. Path-valued vars get /p so WSLENV translates them to the Windows path the /mnt shim can actually open; a cleared var carries no value to translate.
names = [name + ("/p" if _looks_like_path(value) else "") for name, value in env.items()]
names.extend(unset_env)
return tuple(dict.fromkeys(names))
def _merge_wslenv(current: str, names: tuple) -> str:
# Index WSLENV entries by bare var name, preserving first-seen order. The vars we bridge are applied last so our entry wins: a user's pre-existing unflagged "HOME" is upgraded to "HOME/p" rather than left as-is, since WSLENV ignores a duplicate name and a bare entry would leave the path untranslated for a Windows shim.
ordered = []
by_name = {}
for entry in (*current.split(":"), *names):
if not entry:
continue
base = entry.split("/", 1)[0]
if base not in by_name:
ordered.append(base)
by_name[base] = entry
return ":".join(by_name[base] for base in ordered)
def _powershell_quote(arg: str) -> str:
# PowerShell reads single-quoted strings literally (an embedded ' is doubled), so JSON args such as `--settings {"env":...}` survive intact. list2cmdline's backslash-escaped double quotes are cmd.exe syntax and PowerShell mis-parses them.
if arg and re.fullmatch(r"[A-Za-z0-9_./:=+-]+", arg):
return arg
return "'" + arg.replace("'", "''") + "'"
def _print_env(
env: dict,
command: list,
unset_env: tuple = (),
wsl_env_bridge: tuple = (),
cwd_env: tuple = (),
) -> None:
if os.name == "nt":
for name in unset_env:
typer.echo(f"Remove-Item Env:{name} -ErrorAction SilentlyContinue")
for name, value in env.items():
# PowerShell: ` is the escape char, and $ triggers expansion inside "".
escaped = value.replace("`", "``").replace('"', '`"').replace("$", "`$")
typer.echo(f'$env:{name} = "{escaped}"')
for name in cwd_env:
typer.echo(f"$env:{name} = (Get-Location).Path")
typer.echo(" ".join(_powershell_quote(arg) for arg in command))
return
for name in unset_env:
typer.echo(f"export {name}=" if wsl_env_bridge else f"unset {name}")
for name, value in env.items():
typer.echo(f"export {name}={shlex.quote(value)}")
for name in cwd_env:
typer.echo(f'export {name}="$PWD"')
if wsl_env_bridge:
typer.echo(
f"export WSLENV={shlex.quote(_merge_wslenv(os.environ.get('WSLENV', ''), wsl_env_bridge))}"
)
# The final line is a SELF-CONTAINED one-liner (inline env, VAR=... cmd) rather than a bare command. People copy just the last line, and a bare `codex`/`claude` would then run against their real ~/.codex or Anthropic credentials with zero isolation, for example inheriting a pre-existing damaged ~/.codex state DB and blaming the recipe. Inline assignments scope every var, and empty-string the conflicting ones, to this single invocation, so a partial copy behaves the same as pasting the whole block.
inline = [f"{name}=" for name in unset_env]
inline += [f"{name}={shlex.quote(value)}" for name, value in env.items()]
inline += [f'{name}="$PWD"' for name in cwd_env]
if wsl_env_bridge:
inline.append(
f"WSLENV={shlex.quote(_merge_wslenv(os.environ.get('WSLENV', ''), wsl_env_bridge))}"
)
typer.echo(" ".join((*inline, shlex.join(command))))
def _refresh_windows_path() -> None:
# Merge Windows registry PATH hives after the current process PATH so a freshly installed agent is visible without changing existing precedence.
if os.name != "nt":
return
try:
import winreg
except Exception:
return
entries = []
seen = set()
def add_path(value: str) -> bool:
added = False
for entry in str(value).split(os.pathsep):
entry = entry.strip()
if not entry:
continue
key = os.path.normcase(entry).casefold()
if key in seen:
continue
seen.add(key)
entries.append(entry)
added = True
return added
add_path(os.environ.get("PATH", ""))
added_registry = False
hives = (
(winreg.HKEY_CURRENT_USER, "Environment"),
(
winreg.HKEY_LOCAL_MACHINE,
r"SYSTEM\CurrentControlSet\Control\Session Manager\Environment",
),
)
for root, sub in hives:
try:
with winreg.OpenKey(root, sub) as key:
value, _ = winreg.QueryValueEx(key, "Path")
except OSError:
continue
if value:
added_registry = add_path(os.path.expandvars(str(value))) or added_registry
if added_registry:
os.environ["PATH"] = os.pathsep.join(entries)
def _managed_node_tools() -> Optional[tuple[Path, Path, bool]]:
# Best-effort: any failure here means "no managed Node", never a broken launch.
try:
# Discovery only: must not create the cache tree (the launch may target a remote server).
ensure_studio_backend_path(seed_cache_env = False)
from utils.node_runtime import managed_node_binary, resolve_node_executable
node = Path(managed_node_binary())
except (ImportError, OSError, RuntimeError, TypeError, ValueError):
return None
npm = node.with_name("npm.cmd" if os.name == "nt" else "npm")
try:
usable = node.is_file() and npm.is_file()
if os.name != "nt":
usable = usable and os.access(node, os.X_OK) and os.access(npm, os.X_OK)
except OSError:
return None
if not usable:
return None
try:
resolved = resolve_node_executable()
preferred = bool(resolved) and Path(resolved).resolve() == node.resolve()
except (OSError, RuntimeError, TypeError, ValueError):
preferred = False
return node, npm, preferred
def _augment_path_with_install_dirs() -> None:
# Add known install dirs to PATH so a freshly installed agent resolves without a new shell. User dirs are appended (existing tools keep precedence); a preferred managed Node is prepended so Node-backed shims use it. Only user dirs need a home, so a missing home must not drop the managed Node, or a shim fails on `env node` under a bare container UID.
try:
home = Path.home()
except (RuntimeError, OSError):
home = None
candidates = [home / ".local" / "bin", home / ".opencode" / "bin"] if home is not None else []
if os.name == "nt":
appdata = os.environ.get("APPDATA")
if appdata:
candidates.append(Path(appdata) / "npm")
managed_node = _managed_node_tools()
if managed_node is not None and not managed_node[2]:
candidates.append(managed_node[0].parent)
current = os.environ.get("PATH")
if current is None:
# PATH unset: shutil.which() and exec*p* fall back to os.defpath (/bin:/usr/bin), so keep that default instead of collapsing to just the install dirs, which would hide a system-installed agent and strip the launched child's normal PATH. An explicitly empty PATH is left as-is: like shutil.which, it means "search nothing", not os.defpath.
current = os.defpath
preferred_node = (
str(managed_node[0].parent) if managed_node is not None and managed_node[2] else None
)
if preferred_node:
preferred_key = os.path.normcase(preferred_node)
current = os.pathsep.join(
entry
for entry in current.split(os.pathsep)
if not entry or os.path.normcase(entry) != preferred_key
)
seen = {os.path.normcase(entry) for entry in current.split(os.pathsep) if entry}
additions = [
str(directory)
for directory in candidates
if directory.is_dir() and os.path.normcase(str(directory)) not in seen
]
if preferred_node or additions:
parts = [part for part in (preferred_node, current, *additions) if part]
os.environ["PATH"] = os.pathsep.join(parts)
def _probe_env(**extra: str) -> dict:
"""Environment for probes that RUN a resolved shim. _which_with_install_dirs restores PATH before returning, so a shim backed by Unsloth's managed Node would not find that node when executed."""
original = os.environ.get("PATH")
_augment_path_with_install_dirs()
env = os.environ.copy()
if original is None:
os.environ.pop("PATH", None)
else:
os.environ["PATH"] = original
env.update(extra)
return env
def _prefer_windows_cmd_sibling(executable: Optional[str]) -> Optional[str]:
"""Prefer the sibling .cmd when Windows resolved an extensionless npm/pnpm shim. cmd-shim writes ``to``, ``to.cmd`` and ``to.ps1``, and shutil.which can return the extensionless POSIX shim, which CreateProcess rejects with WinError 193. Measured on windows-latest: 3.12.0 probes the bare name before PATHEXT (gh-109590) and 3.12.1 onwards do not, and a PATHEXT holding "." reaches the same place on any version. Substituted only when the file opens with a shebang, so a real PE keeps priority over a stale wrapper beside it; matched on not-a-Windows-suffix so a dotted bin name is caught too."""
if executable is None or os.name != "nt":
return executable
if Path(executable).suffix.lower() in {".exe", ".com", ".cmd", ".bat", ".ps1"}:
return executable
with contextlib.suppress(OSError):
with open(executable, "rb") as resolved_file:
if resolved_file.read(2) == b"#!":
# .CMD only matters on case-sensitive volumes; no writer emits .bat.
for extension in (".cmd", ".CMD"):
sibling = Path(executable + extension)
if sibling.is_file():
return str(sibling)
return executable
def _which_with_install_dirs(name: str) -> Optional[str]:
# Probe lookup also searches agent install dirs so it matches _launch(); else flags reach an older build it rejects; PATH is restored.
original = os.environ.get("PATH")
_augment_path_with_install_dirs()
try:
# Callers spawn this result directly, so the shim rescue is needed here too, not only in _resolved_launch_command.
return _prefer_windows_cmd_sibling(shutil.which(name))
finally:
if original is None:
os.environ.pop("PATH", None)
else:
os.environ["PATH"] = original
def _which_deepseek_harness_with_install_dirs() -> Optional[str]:
"""Find the first valid DeepSeek Harness even when another ``dsh`` shadows it."""
original = os.environ.get("PATH")
_augment_path_with_install_dirs()
try:
for executable in deepseek_harness_executables_on_path():
executable = _prefer_windows_cmd_sibling(executable)
if executable is not None and is_deepseek_harness_executable(executable):
return executable
return None
finally:
if original is None:
os.environ.pop("PATH", None)
else:
os.environ["PATH"] = original
def _install_source(install_hint: str) -> Optional[str]:
"""The first http(s) URL an install hint fetches, or None (e.g. an npm install)."""
match = re.search(r"https?://[^\s'\")]+", install_hint)
return match.group(0) if match else None
def _pinned_raw_github_commit(source: str) -> Optional[str]:
"""Return the immutable full commit in a raw GitHub URL, if present."""
match = re.match(
r"^https://raw\.githubusercontent\.com/[^/]+/[^/]+/([0-9a-f]{40})/",
source,
flags = re.IGNORECASE,
)
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]):
executable = _prefer_windows_cmd_sibling(shutil.which("npm"))
if executable and not _wsl_windows_executable([executable]):
return executable
if executable:
# WSL inherits the Windows PATH, so the rejected shim may shadow a native npm.
for directory in os.get_exec_path():
candidate = _prefer_windows_cmd_sibling(shutil.which("npm", path = directory))
if candidate and not _wsl_windows_executable([candidate]):
return candidate
return str(managed_node[1]) if managed_node is not None else None
def _install_command(install_hint: str) -> tuple[list[str], Optional[dict]]:
if not re.match(r"^\s*npm(?:\s|$)", install_hint):
if os.name == "nt":
return (
[
"powershell",
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-Command",
install_hint,
],
None,
)
return ["/bin/sh", "-c", install_hint], None
npm = _npm_executable()
if npm is None:
_fail(
"npm is required to install this agent, but no native system npm or usable "
"Unsloth-managed Node installation was found. Install Node.js with npm, "
"then re-run."
)
env = dict(os.environ)
# dirname, not Path().parent: Path picks its flavour from os.name, which the tests override. Empty means npm is a bare name; prepending "" would put the cwd on PATH.
npm_dir = os.path.dirname(npm)
current_path = env.get("PATH", "")
if npm_dir:
env["PATH"] = os.pathsep.join([npm_dir, current_path]) if current_path else npm_dir
if os.name == "nt":
# The hint is already PowerShell-quoted; shlex would drop the doubled ' of a path like O'Brien.
command = "& " + _powershell_quote(npm) + install_hint.lstrip()[len("npm") :]
return (
[
"powershell",
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-Command",
command,
],
env,
)
return [npm, *shlex.split(install_hint)[1:]], env
def _install_agent(
name: str,
install_hint: str,
*,
update: bool = False,
) -> Optional[str]:
# Missing agent under --launch: offer to run its documented install command, then re-resolve it on PATH. Consent-based, and a non-interactive stdin cannot answer the prompt, so both the no-TTY and declined cases return None and let the caller print the hint and exit.
if not sys.stdin.isatty():
return None
typer.echo(f"`{name}` is {'too old' if update else 'not installed'}.")
# Make the supply-chain risk explicit before the prompt: these are the vendors' own installers (curl | bash, irm | iex, npm), run with the user's privileges, and nothing checks a signature or hash on the fetched content. Naming the source turns a blind "yes" into informed consent.
source = _install_source(install_hint)
if source:
pinned_commit = _pinned_raw_github_commit(source)
if pinned_commit:
warning = (
"Security warning: This will download and execute a third-party script "
f"from {source} with your privileges. Unsloth pins this content to "
f"immutable upstream commit {pinned_commit}, but does not independently "
"verify or sandbox it. Continue only if you trust this source and commit."
)
else:
warning = (
"Security warning: This will download and execute an unverified third-party "
f"script from {source} with your privileges. Unsloth does not pin or verify "
"the downloaded content. Continue only if you trust this source."
)
else:
warning = (
f"This will RUN `{install_hint}` with your privileges; "
"there is no signature or hash check."
)
typer.secho(warning, fg = "yellow", err = True)
action = "Update" if update else "Install"
if not typer.confirm(f"{action} `{name}` now with `{install_hint}`?", default = False):
return None
install_command, install_env = _install_command(install_hint)
try:
result = subprocess.run(install_command, env = install_env)
except OSError as exc:
_fail(
f"Could not run the install command: {exc}. "
f"Run it yourself, then re-run: {install_hint}"
)
if result.returncode != 0:
message = f"Install command failed. Run it yourself, then re-run: {install_hint}"
if os.name == "nt":
# A hand-run retry can still hit the policy; point at the one-time per-user fix.
message += (
"\nIf it fails because running scripts is disabled (PSSecurityException), "
"allow local scripts for your user, then retry:\n"
" Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned"
)
_fail(message)
# Resolve the freshly installed agent without a shell restart: pull registry PATH (Windows) plus well-known install dirs the installer may not have added to PATH.
_refresh_windows_path()
_augment_path_with_install_dirs()
executable = shutil.which(name)
if executable is None:
_fail(
f"`{name}` installed but isn't on PATH yet. Open a new shell (or add it to "
f"PATH), then re-run. Install command: {install_hint}"
)
return executable
def _resolve_or_install_agent(name: str, install_hint: str, resolver) -> str:
executable = resolver(name)
invalid_executable = None
if executable is not None:
if name != "dsh" or is_deepseek_harness_executable(executable):
return executable
invalid_executable = executable
executable = _which_deepseek_harness_with_install_dirs()
if executable is not None:
return executable
executable = _install_agent(name, install_hint)
if executable is not None:
if name != "dsh" or is_deepseek_harness_executable(executable):
return executable
invalid_executable = executable
if name == "dsh":
executable = _which_deepseek_harness_with_install_dirs()
if executable is not None:
return executable
if invalid_executable is not None:
_fail(
f"`{invalid_executable}` is not DeepSeek Harness. Install DeepSeek Harness "
f"with: {install_hint}"
)
_fail(f"`{name}` not found on PATH. Install it with: {install_hint}")
def _require_agent_for_launch(name: str, install_hint: str, launch: bool) -> Optional[str]:
if not launch:
return None
return _resolve_or_install_agent(name, install_hint, _which_with_install_dirs)
def _wsl_shim_env(
command: list,
env: dict,
unset_env: tuple,
cwd_env: tuple = (),
) -> tuple[dict, tuple]:
if not _wsl_windows_executable(command):
return env, ()
wsl_env_bridge = _wsl_bridge_names(env, unset_env)
if not wsl_env_bridge and not cwd_env:
return env, ()
# Bridge PWD via WSLENV (PWD/p) so the Windows shim finds its project root from the live cwd, not a stale inherited Linux PWD. Do not freeze env["PWD"]: a --no-launch recipe must translate the live PWD when run, not when generated; _launch overrides it. cwd_env values likewise resolve at execution time and are always filesystem paths.
return env, tuple(dict.fromkeys((*wsl_env_bridge, *(f"{name}/p" for name in cwd_env), "PWD/p")))
_NPM_CMD_SHIM_HEAD = (
"@ECHO off\n"
"GOTO start\n"
":find_dp0\n"
"SET dp0=%~dp0\n"
"EXIT /b\n"
":start\n"
"SETLOCAL\n"
"CALL :find_dp0\n"
)
_NPM_NODE_CMD_SHIM_PREFIX = (
re.escape(_NPM_CMD_SHIM_HEAD)
+ r"(?P<environment>(?:@SET [^=\r\n]+=[^\r\n]+\n)*)"
+ re.escape(
'\nIF EXIST "%dp0%\\node.exe" (\n'
+ ' SET "_prog=%dp0%\\node.exe"\n'
+ ") ELSE (\n"
+ ' SET "_prog=node"\n'
)
)
_NPM_NODE_CMD_SHIM_SUFFIX = (
r"(?P<node_args>[^\r\n]*?)[ \t]+" + r'"%dp0%\\(?P<target>[^"\r\n]+)"[ \t]+%\*'
)
_NPM_NODE_CMD_SHIMS = (
re.compile(
_NPM_NODE_CMD_SHIM_PREFIX
+ re.escape(
" SET PATHEXT=%PATHEXT:;.JS;=;%\n"
+ ")\n\n"
+ 'endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"'
)
+ _NPM_NODE_CMD_SHIM_SUFFIX,
re.IGNORECASE,
),
re.compile(
_NPM_NODE_CMD_SHIM_PREFIX
+ re.escape(
")\n\n"
+ "endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "
+ "set PATHEXT=%PATHEXT:;.JS;=;% & "
+ '"%_prog%"'
)
+ _NPM_NODE_CMD_SHIM_SUFFIX,
re.IGNORECASE,
),
)
_NPM_NATIVE_CMD_SHIM = re.compile(
re.escape(_NPM_CMD_SHIM_HEAD) + r'"%dp0%\\(?P<target>[^"\r\n]+)"[ \t]+%\*',
re.IGNORECASE,
)
_NPM_NODE_SHEBANG = re.compile(
r"^#!\s*(?:/usr/bin/env\s+(?:-S\s+)?((?:[^ \t=]+=[^ \t=]+\s+)*))?([^ \t]+)(.*)$"
)
_NPM_SHEBANG_DOLLAR = re.compile(r"\$\{?([^$@#?\- \t{}:]+)\}?")
def _npm_batch_environment(declarations: str) -> str:
lines = []
for declaration in declarations.split():
name, separator, value = declaration.partition("=")
name = name.strip()
value = value.strip()
if separator and name and value:
value = _NPM_SHEBANG_DOLLAR.sub(lambda match: f"%{match.group(1)}%", value)
lines.append(f"@SET {name}={value}\n")
return "".join(lines)
def _windows_expand_environment(value: str, environment: dict) -> str:
folded = {name.casefold(): item for name, item in environment.items()}
return re.sub(
r"%([^%\r\n]+)%",
lambda match: folded.get(match.group(1).casefold(), ""),
value,
)
def _npm_node_shim_metadata(target: Path, match, environment: dict) -> Optional[tuple]:
environment_block = match.group("environment") or ""
node_args_text = (match.group("node_args") or "").strip()
known_node_suffix = target.suffix.lower() in {".js", ".cjs", ".mjs"}
if not environment_block and not node_args_text and known_node_suffix:
return [], {}
first_line = target.read_text(encoding = "utf-8").splitlines()[0]
shebang = _NPM_NODE_SHEBANG.fullmatch(first_line)
if shebang is None or Path(shebang.group(2)).name.casefold() not in {"node", "node.exe"}:
return None
declarations = shebang.group(1) or ""
if _npm_batch_environment(declarations).casefold() != environment_block.casefold():
return None
if (shebang.group(3) or "").strip() != node_args_text:
return None
try:
node_args = shlex.split(node_args_text) if node_args_text else []
except ValueError:
return None
updates = {}
expanded_environment = dict(environment)
for line in environment_block.splitlines():
name, value = line.removeprefix("@SET ").split("=", 1)
expanded = _windows_expand_environment(value, expanded_environment)
expanded_environment[name] = expanded
updates[name] = expanded
return node_args, updates
def _apply_windows_environment(environment: dict, updates: dict) -> None:
for name, value in updates.items():
existing = next((key for key in environment if key.casefold() == name.casefold()), None)
if existing is not None and existing != name:
del environment[existing]
environment[name] = value
def _resolved_launch_command(
executable: str,
arguments: list,
environment: Optional[dict] = None,
) -> list:
"""Return an argv that preserves arguments through standard Windows npm shims."""
# _launch resolves with raw shutil.which, so rescue here too; the sibling then enters the parser below.
executable = _prefer_windows_cmd_sibling(executable)
if os.name == "nt" and Path(executable).suffix.lower() in {".cmd", ".bat"}:
# cmd.exe treats CR/LF inside `%*` as command separators, and Windows PowerShell's native-command bridge also rewrites embedded quotes. Match complete cmd-shim templates so custom wrappers keep their setup behavior.
with contextlib.suppress(OSError, UnicodeError, IndexError):
shim = Path(executable)
contents = shim.read_text(encoding = "utf-8").replace("\r\n", "\n").strip()
for pattern in _NPM_NODE_CMD_SHIMS:
match = pattern.fullmatch(contents)
if match is None:
continue
relative = Path(*re.split(r"[\\/]+", match.group("target")))
target = (shim.parent / relative).resolve()
if not target.is_file() or not any(
part.casefold() == "node_modules" for part in target.parts
):
continue
metadata = _npm_node_shim_metadata(target, match, environment or os.environ)
if metadata is None:
continue
node_args, environment_updates = metadata
bundled_node = shim.parent / "node.exe"
node = str(bundled_node) if bundled_node.is_file() else shutil.which("node.exe")
if node:
if environment is not None:
_apply_windows_environment(environment, environment_updates)
return [node, *node_args, str(target), *arguments]
match = _NPM_NATIVE_CMD_SHIM.fullmatch(contents)
if match is not None:
relative = Path(*re.split(r"[\\/]+", match.group("target")))
target = (shim.parent / relative).resolve()
if (
target.is_file()
and any(part.casefold() == "node_modules" for part in target.parts)
and target.suffix.lower() in {".exe", ".com"}
):
return [str(target), *arguments]
return [executable, *arguments]
def _launch(
command: list,
env: dict,
install_hint: str,
unset_env: tuple = (),
cwd_env: tuple = (),
) -> int:
# Resolve well-known install dirs (~/.local/bin) first, so an already-installed agent not yet on PATH is found instead of prompting a needless reinstall.
_augment_path_with_install_dirs()
executable = _resolve_or_install_agent(command[0], install_hint, shutil.which)
env, wsl_env_bridge = _wsl_shim_env(command, env, unset_env, cwd_env)
env = {**env, **{name: os.getcwd() for name in cwd_env}}
child_env = dict(os.environ)
if wsl_env_bridge:
# Override stale inherited PWD with the real cwd so the shim resolves the project root.
env = {**env, "PWD": os.getcwd()}
child_env["WSLENV"] = _merge_wslenv(child_env.get("WSLENV", ""), wsl_env_bridge)
for name in unset_env:
child_env[name] = ""
else:
for name in unset_env:
child_env.pop(name, None)
child_env.update(env)
if os.name != "nt" and not wsl_env_bridge:
# Keep POSIX child processes from seeing a stale inherited PWD when subprocess cwd was changed by the caller. Some Node CLIs use PWD for project-root discovery instead of process.cwd().
child_env["PWD"] = os.getcwd()
# Ctrl+C cancels a turn inside the agent; do not let it kill this wrapper. A no-op handler, not SIG_IGN: exec preserves an ignored signal but resets a caught one.
previous = signal.signal(signal.SIGINT, lambda *_: None)
try:
launch_command = _resolved_launch_command(executable, command[1:], child_env)
code = subprocess.run(launch_command, env = child_env).returncode
finally:
signal.signal(signal.SIGINT, previous)
# Negative returncode means killed by signal N; shells expect 128+N.
return code if code >= 0 else 128 - code
_CONNECTION_MODEL_PREFIX = "external::"
def _connection_entry(base: str, key: str, model: Optional[str]) -> Optional[dict]:
# Studio names a Connection model external::<connection id>::<url-encoded model>; a bare name counts when one enabled Connection lists it and no loaded model has it.
if not model:
return None
explicit = model.startswith(_CONNECTION_MODEL_PREFIX)
if not explicit and any(
_model_id_matches(entry.get("id"), name, allow_casefold = is_loopback_url(base))
for entry in _loaded_models(base, key)
if entry.get("loaded") is not False
for name in (model, _split_repo_variant(model)[0])
):
return None
try:
providers = _http_json("GET", f"{base}/api/providers/", key)
except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
# A 4xx is an older server or a key without Connections; anything else must not fall
# through to a load that could evict the resident model.
if explicit or not (isinstance(exc, urllib.error.HTTPError) and exc.code < 500):
_fail_request(exc, "Couldn't list Connections")
return None
enabled = [p for p in providers or [] if isinstance(p, dict) and p.get("is_enabled")]
if explicit:
provider_id = model[len(_CONNECTION_MODEL_PREFIX) :].partition("::")[0]
matches = [p for p in enabled if p.get("id") == provider_id]
if not matches:
_fail(f"No enabled Connection {provider_id!r} on {base}. Check Settings → Connections.")
else:
matches = [p for p in enabled if model in (p.get("models") or [])]
if not matches:
return None
usable = [p for p in matches if p.get("auth_kind") != "chatgpt_oauth"]
if not usable:
_fail(
f"{model} is on a ChatGPT subscription Connection, which only the Unsloth chat can use."
)
if explicit:
return {"id": model, "connection": usable[0].get("display_name") or usable[0]["id"]}
ids = [f"{_CONNECTION_MODEL_PREFIX}{p['id']}::{quote(model, safe = '')}" for p in usable]
if len(ids) > 1:
_fail(f"{model} is offered by more than one Connection. Pass one of: {', '.join(ids)}")
return {"id": ids[0], "connection": usable[0].get("display_name") or usable[0]["id"]}
def _connect(
api_key: Optional[str],
model: Optional[str],
load: LoadOptions = LoadOptions(),
*,
serve: bool = False,
launch: bool = True,
server_options: ServerOptions = ServerOptions(),
preload_check = None,
connections: bool = False,
) -> tuple:
_refuse_npu_model(model)
requested = model
explicit_connection = bool(model) and model.startswith(_CONNECTION_MODEL_PREFIX)
# `--model org/name:QUANT` is shorthand for `--model org/name --gguf-variant QUANT`. Split it before we match or serve so the attach path resolves against the already-loaded `org/name` (listed without the suffix) instead of reloading a `:`-suffixed repo id, which Unsloth rejects and which would evict a model another session is using.
unsplit = None
if model and not explicit_connection:
repo, variant = _split_repo_variant(model)
if variant:
unsplit = (model, load)
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,
serve = serve and not explicit_connection,
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)
# Studio's own ids can carry a tag (ollama/qwen3:8b), so a loaded model of that exact id wins over the split.
if (
unsplit
and server is None
and any(
entry.get("loaded") is not False
and _model_id_matches(
entry.get("id"), requested, allow_casefold = is_loopback_url(base)
)
for entry in _loaded_models(base, key)
)
):
model, load = unsplit
connection = None if server is not None else _connection_entry(base, key, requested)
if connection is not None:
if not connections:
_fail(
f"{requested} is a Connection model, and this agent can only use models "
"loaded in Unsloth. Connection models work with `unsloth start claude`, "
"`unsloth start codex` and `unsloth start opencode`."
)
typer.echo(f"Using {requested} from the Connection {connection['connection']}.")
# A Connection reports no context window; an explicit one lets agents size compaction.
if load.max_seq_length > 0:
connection["context_length"] = load.max_seq_length
else:
typer.echo(
"Pass --max-seq-length with the model's context window so the agent can "
"compact before the provider runs out of context.",
err = True,
)
if (
key not in _cached_keys(_key_cache_path(), base, "minted")
and not api_key
and is_loopback_url(base)
and verify_studio_identity(base)
):
key = _agent_api_key(base, None, minted_only = True)
if key not in _cached_keys(_key_cache_path(), base, "minted"):
typer.echo(
"Warning: Unsloth Studio only sends a Connection's saved API key for the key "
"`unsloth start` issues, so drop --api-key / UNSLOTH_API_KEY unless this "
"Connection needs no key.",
err = True,
)
return base, key, connection
# A server we just started has exactly the requested model loaded, so resolve to whatever it is serving instead of re-matching the raw --model string. Only an attach can still trigger an evicting load, so _resolve_model gets the pre-load check and runs it only when that load is imminent.
entry = _resolve_model(
base,
key,
None if server is not None else model,
load,
preload_check = None if server is not None else preload_check,
# That server was started FROM these knobs, so inferring a target here would reload what was just loaded.
infer_resident = server is None,
)
status = _inference_status(base, key, entry["id"]) if model else {}
# A GGUF can be active while the resolved entry is another resident model.
if status.get("memory_warning") and any(
_model_id_matches(
(entry or {}).get("id"), status_id, allow_casefold = is_loopback_url(base)
)
for status_id in (status.get("active_model"), status.get("model_identifier"))
if status_id
):
typer.echo(f"Warning: {status['memory_warning']}", err = True)
except BaseException:
_shutdown_auto_served()
raise
return base, key, entry
def _run(
base: str,
entry: dict,
env: dict,
command: list,
*,
launch: bool,
install_hint: str,
unset_env: tuple = (),
clear_screen: bool = False,
cwd_env: tuple = (),
) -> None:
# Some agents (Pi) render inline from wherever the cursor sits: their first paint assumes a clean screen rather than clearing or entering the alternate screen themselves. Hand them one so the session does not start mid-scroll under our connection output. click.clear() is cross-platform and a no-op when stdout is not a terminal, so transcripts and --no-launch recipes stay intact.
if launch and clear_screen:
click.clear()
typer.echo(f"Unsloth ready at {base} · model {entry['id']}")
if not launch:
env, wsl_env_bridge = _wsl_shim_env(command, env, unset_env, cwd_env)
_print_env(
env,
command,
unset_env = unset_env,
wsl_env_bridge = wsl_env_bridge,
cwd_env = cwd_env,
)
if _keep_auto_served():
typer.echo(f"Unsloth Studio is still running at {base}.")
typer.echo("Stop it with: unsloth studio stop")
return
try:
code = _launch(
command,
env,
install_hint = install_hint,
unset_env = unset_env,
cwd_env = cwd_env,
)
except BaseException:
# Startup succeeded but the agent failed to launch; tear the server down rather than orphan it.
_shutdown_auto_served()
raise
auto_started = _auto_served_server is not None
kept = _keep_auto_served()
if auto_started and not kept:
typer.echo(f"The auto-started Unsloth server at {base} stopped during the session.")
raise typer.Exit(code = code)
if code:
# The server status below must not read as a successful agent session.
typer.echo(f"The agent exited with code {code}.")
if is_loopback_url(base):
typer.echo(f"Unsloth Studio is still running at {base}.")
typer.echo("Stop it with: unsloth studio stop")
else:
typer.echo(f"The remote Unsloth server is still running at {base}.")
raise typer.Exit(code = code)
def _agents_config_root() -> Path:
return _studio_auth_root() / "agents"
@contextlib.contextmanager
def _temporary_agent_config(prefix: str):
# Nothing else prunes Unsloth's auth tree, so reuse the locked session helper: the next launch reclaims homes left by a killed wrapper, and the lock spares live sessions.
temp_root = _agents_config_root() / ".tmp"
with contextlib.ExitStack() as stack:
try:
temp_root.mkdir(parents = True, exist_ok = True, mode = 0o700)
path = stack.enter_context(_short_ephemeral_session(temp_root, prefix))
except OSError:
# Attaching to a remote or running Unsloth needs no local auth tree, so it may be absent or unwritable. Fall back to the system temp dir, as before: no reclamation there, but the OS prunes it.
path = Path(tempfile.mkdtemp(prefix = prefix))
stack.callback(shutil.rmtree, path, ignore_errors = True)
yield path
# codex-subagent nests CODEX_HOME under <home>/parent, so it needs the short root too.
_CODEX_SHORT_HOME_AGENTS = ("codex", "codex-subagent")
def _ephemeral_session_parent(agent: str) -> Optional[Path]:
"""Return a non-system-temp parent when an agent needs one."""
if os.name != "nt" or agent not in _CODEX_SHORT_HOME_AGENTS:
return None
# Codex creates a deeply nested curated-plugin checkout below CODEX_HOME. A normal %TEMP%\\unsloth-codex-* home can exceed legacy Windows path limits during startup, and Codex also refuses to create its PATH helpers below the system temp directory. Keep the throwaway home short but still private to the current user; _session_config removes it on exit.
root = Path.home() / ".unsloth" / ".tmp"
root.mkdir(parents = True, exist_ok = True, mode = 0o700)
return root
def _ephemeral_session_prefix(agent: str, parent: Optional[Path]) -> str:
"""Return the platform-specific prefix for an ephemeral agent home."""
if agent in _CODEX_SHORT_HOME_AGENTS and parent is not None:
return "u-codex-"
return f"unsloth-{agent}-"
@contextlib.contextmanager
def _locked_file(path: Path, blocking: bool = True):
"""Yield whether an advisory lock was acquired for the first byte of path."""
handle = path.open("a+b")
acquired = False
try:
if os.name == "nt":
import msvcrt
handle.seek(0, os.SEEK_END)
if handle.tell() == 0:
handle.write(b"\0")
handle.flush()
handle.seek(0)
while True:
try:
msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
acquired = True
break
except OSError as exc:
if exc.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
raise
if not blocking:
break
# LK_LOCK gives up after roughly ten seconds. Poll LK_NBLCK instead so a large stale plugin checkout cannot make a concurrent launch fail just because cleanup takes longer.
time.sleep(0.05)
else:
import fcntl
mode = fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB)
try:
fcntl.flock(handle.fileno(), mode)
acquired = True
except BlockingIOError:
acquired = False
yield acquired
finally:
if acquired:
if os.name == "nt":
handle.seek(0)
msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
else:
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
handle.close()
def _reclaim_stale_ephemeral_sessions(parent: Path, prefix: str) -> None:
"""Remove abandoned session homes while preserving locked live sessions."""
for path in parent.glob(f"{prefix}*"):
if not path.is_dir():
continue
active_lock = path / ".active.lock"
try:
modified = active_lock.stat().st_mtime if active_lock.exists() else path.stat().st_mtime
except FileNotFoundError:
continue
# The wrapper owns the advisory lock, not the Codex child. If only the wrapper is killed, its child may still be using CODEX_HOME; give that process a full day to finish before treating the unlocked home as stale.
if time.time() - modified < _CODEX_EPHEMERAL_STALE_SECONDS:
continue
try:
with _locked_file(active_lock, blocking = False) as stale:
pass
except FileNotFoundError:
# A normally exiting session may have removed itself after the glob.
continue
if stale:
shutil.rmtree(path, ignore_errors = True)
def _refresh_ephemeral_session_marker(path: Path, stop: threading.Event) -> None:
"""Keep the stale grace period relative to wrapper death, not session start."""
while not stop.wait(_CODEX_EPHEMERAL_HEARTBEAT_SECONDS):
with contextlib.suppress(OSError):
os.utime(path, None)
@contextlib.contextmanager
def _short_ephemeral_session(parent: Path, prefix: str = "u-codex-"):
"""Create a session home whose lock makes crash cleanup concurrency-safe."""
path = None
active_lock = contextlib.ExitStack()
heartbeat_stop = None
heartbeat = None
try:
with _locked_file(parent / ".cleanup.lock") as cleanup_lock:
if not cleanup_lock: # The blocking acquisition should always succeed.
raise RuntimeError(f"Could not lock ephemeral session root: {parent}")
_reclaim_stale_ephemeral_sessions(parent, prefix)
path = Path(tempfile.mkdtemp(prefix = prefix, dir = parent))
locked = active_lock.enter_context(_locked_file(path / ".active.lock"))
if not locked:
raise RuntimeError(f"Could not lock ephemeral session home: {path}")
heartbeat_stop = threading.Event()
heartbeat = threading.Thread(
target = _refresh_ephemeral_session_marker,
args = (path / ".active.lock", heartbeat_stop),
name = "unsloth-agent-home-heartbeat",
daemon = True,
)
heartbeat.start()
yield path
finally:
if heartbeat_stop is not None:
heartbeat_stop.set()
if heartbeat is not None:
heartbeat.join(timeout = 1)
try:
with _locked_file(parent / ".cleanup.lock") as cleanup_lock:
if not cleanup_lock: # The blocking acquisition should always succeed.
raise RuntimeError(f"Could not lock ephemeral session root: {parent}")
# Release the live marker only after deletion is serialized with startup scavenging, so no scanner can race this rmtree.
active_lock.close()
if path is not None:
shutil.rmtree(path, ignore_errors = True)
finally:
active_lock.close()
@contextlib.contextmanager
def _session_config(
agent: str,
launch: bool,
persist: bool = False,
):
"""Yield a private directory for an agent's session config (never the user's own). launch (the default) uses an ephemeral temp dir removed after the agent process exits, so nothing persists; no-launch uses a stable Unsloth-owned dir, since the printed recipe is run later on this machine; persist (from --persist) uses that same stable dir even for a launch, so the agent's session survives the exit and can be resumed. Either way the user's real ~/.<agent> config is left untouched."""
if launch and not persist:
# Windows codex keeps #7519's short home (MAX_PATH); everyone else uses Unsloth's root.
parent = _ephemeral_session_parent(agent)
prefix = _ephemeral_session_prefix(agent, parent)
if parent is not None:
with _short_ephemeral_session(parent, prefix) as path:
yield path
else:
with _temporary_agent_config(prefix) as path:
yield path
else:
# Never wipe this dir: a previously printed recipe may still be running an agent whose sessions and state live here, and every config writer merges idempotently into an existing home anyway. Writers must also reset any state a previous run's flags left behind (--yolo especially), since files here outlive the invocation that wrote them.
path = _agents_config_root() / agent
path.mkdir(parents = True, exist_ok = True, mode = 0o700)
yield path
def _studio_embedding_model(base: str, key: str) -> Optional[str]:
"""Studio's configured embedding model, or None when this server cannot say. Not a model name: a name this server will not serve, beside fallback "none", is the one combination OpenClaw cannot degrade out of, so the caller writes provider "none" instead."""
try:
info = _http_json("GET", f"{base}/api/settings/embedding-model", key, timeout = 10)
# typer.Exit is a RuntimeError subclass: the broad catch would swallow a deliberate abort.
except (typer.Exit, typer.Abort, click.exceptions.Exit, click.exceptions.Abort):
raise
except Exception: # noqa: BLE001 - an older or unreachable server still gets a working config
return None
name = info.get("embedding_model") if isinstance(info, dict) else None
if not isinstance(name, str) or not name.strip():
return None
# OpenClaw sends this to /v1/embeddings verbatim; Settings stores what was typed.
return name.strip()
def _openclaw_provider(
base: str,
key: str,
model: dict,
max_tokens: Optional[int] = None,
vision: bool = False,
) -> dict:
# Unsloth is a generic OpenAI-compatible /v1 endpoint (the vLLM/LM Studio path).
provider_model = {"id": model["id"], "name": model["id"]}
if vision:
provider_model["input"] = ["text", "image"]
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 _openclaw_doctor_command(path: Path, *, windows: bool) -> str:
"""`openclaw doctor --fix` against Unsloth's managed config, in the user's shell syntax."""
env = {"OPENCLAW_CONFIG_PATH": str(path), "OPENCLAW_STATE_DIR": str(path.parent)}
if windows:
sets = "; ".join(
f'$env:{name} = "{value.replace("`", "``").replace(chr(34), "`" + chr(34)).replace("$", "`$")}"'
for name, value in env.items()
)
return f"{sets}; openclaw doctor --fix"
inline = " ".join(f"{name}={shlex.quote(value)}" for name, value in env.items())
return f"{inline} openclaw doctor --fix"
def write_openclaw_config(
base: str,
key: str,
model: dict,
path: Path,
yolo: bool = False,
workspace_path: Optional[str] = None,
embedding_model: Optional[str] = None,
request_body: Optional[dict] = None,
max_tokens: Optional[int] = None,
vision: bool = False,
) -> None:
config = _read_json_object(path)
if config is None:
typer.echo(
f"Warning: couldn't parse {path} — add an 'unsloth' provider there "
"yourself, or move the file aside and re-run.",
err = True,
)
return
before = json.dumps(config, sort_keys = True)
models = _subdict(config, "models")
models.setdefault("mode", "merge")
_subdict(models, "providers")["unsloth"] = _openclaw_provider(
base, key, model, max_tokens, vision
)
# 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:
search.update(
{
"provider": "openai-compatible",
"model": embedding_model,
"fallback": "none",
"remote": {"baseUrl": f"{base}/v1", "apiKey": key},
}
)
else:
# "none" is OpenClaw's keyword-only mode: no network call, and search still returns hits. Clearing the remote stops a reused --persist config aiming at a dead endpoint.
search.update({"provider": "none", "fallback": "none"})
search.pop("model", None)
search.pop("remote", None)
# ORed with OPENCLAW_LOAD_SHELL_ENV: a persisted true re-enables the login-shell key import.
_subdict(_subdict(config, "env"), "shellEnv")["enabled"] = False
# Pin a default model, else OpenClaw drops into its setup agent ("no models available").
agents = _subdict(config, "agents")
defaults = _subdict(agents, "defaults")
_subdict(defaults, "model")["primary"] = f"unsloth/{model['id']}"
# OpenClaw applies extra_body last; its own params only read camelCase keys, so top_p would be lost.
model_ref = f"unsloth/{model['id']}"
model_settings = defaults.get("models")
if request_body or (isinstance(model_settings, dict) and model_ref in model_settings):
params = _subdict(_subdict(_subdict(defaults, "models"), model_ref), "params")
_merge_request_body(params, "extra_body", request_body or {})
# `unsloth start openclaw` is a coding-agent entry point, so the selected project may already contain its own AGENTS.md and git metadata. Do not seed OpenClaw's personal-assistant bootstrap files or initialize a repository in it.
defaults["skipBootstrap"] = True
# OPENCLAW_STATE_DIR does not relocate the workspace. Callers normally pin it to the directory where `unsloth start openclaw` was invoked so OpenClaw edits the same project as every other coding agent. Keep the managed fallback for direct config-writer callers that do not provide an explicit workspace.
if workspace_path is None:
workspace = path.parent / "workspace"
workspace.mkdir(parents = True, exist_ok = True, mode = 0o700)
workspace_path = str(workspace)
defaults["workspace"] = workspace_path
# Per-agent paths override agents.defaults.workspace and OPENCLAW_STATE_DIR. This config is itself an isolated Unsloth copy, so remove stale explicit paths and let OpenClaw resolve every listed agent beneath the managed defaults/state directory.
# OpenClaw 2026.10.1 keys agents by id under agents.entries; older configs carry an agents.list array.
agent_list = agents.get("list")
agent_entries = agents.get("entries")
listed = list(agent_list) if isinstance(agent_list, list) else []
if isinstance(agent_entries, dict):
listed += list(agent_entries.values())
for agent_config in listed:
if isinstance(agent_config, dict):
agent_config.pop("workspace", None)
agent_config.pop("agentDir", None)
if isinstance(agent_list, list):
# 2026.10.1 rejects agents.list. Converting it (id normalization, ownership, channel bindings,
# workspace pins) is OpenClaw's own migration, so point at it rather than half-reimplement it.
typer.echo(
f"Note: {path} still has the legacy agents.list, which OpenClaw 2026.10.1+ rejects. "
f"Migrate it with: {_openclaw_doctor_command(path, windows = os.name == 'nt')}",
err = True,
)
# Unauthenticated loopback gateway: without auth.mode=none the client will not open the websocket. The daemon must still be started separately (`openclaw gateway`).
gateway = _subdict(config, "gateway")
gateway.setdefault("mode", "local")
_subdict(gateway, "auth").setdefault("mode", "none")
if yolo:
# OpenClaw has no --yolo flag. Its host approvals document (SQLite since 2026.8.1) falls back to tools.exec for omitted fields, so the config side is enough.
exec_policy = _subdict(_subdict(config, "tools"), "exec")
exec_policy["host"] = "gateway"
exec_policy["security"] = "full"
exec_policy["ask"] = "off"
else:
# The no-launch config dir is reused across runs, so a previous --yolo run may have left auto-approval state behind. OpenClaw treats an omitted exec policy as security=full, ask=off on the gateway host, so deleting the keys would keep auto-approval on: a non-yolo run must WRITE a prompting policy. Only a permissive/yolo policy is replaced; a stricter one set by hand survives.
tools = config.get("tools")
exec_policy = tools.get("exec") if isinstance(tools, dict) else None
exec_policy = exec_policy if isinstance(exec_policy, dict) else {}
# Match ONLY the exact fingerprint --yolo writes (host=gateway, security=full, ask=off, all explicit, no mode); anything else is left untouched. host=auto or an omitted host resolves to security=deny under an active sandbox, so treating those as the permissive gateway default would broaden a fresh sandboxed config from deny to allowlist. host=node and host=sandbox are user-set (--yolo only writes gateway). tools.exec.mode is OpenClaw's normalized knob, cannot be combined with security/ask, and OpenClaw never rewrites our security/ask write into it, so a mode is always a deliberate user policy; never clobber it.
permissive = (
"mode" not in exec_policy
and exec_policy.get("host") == "gateway"
and exec_policy.get("security") == "full"
and exec_policy.get("ask") == "off"
)
if permissive:
exec_policy = _subdict(_subdict(config, "tools"), "exec")
exec_policy.pop("host", None) # routing only; defaults to the gateway host
exec_policy["security"] = "allowlist" # only allowlisted commands skip approval
exec_policy["ask"] = "on-miss" # prompt on every non-allowlisted command
# Older Unsloth wrote --yolo defaults here; OpenClaw 2026.8.1+ refuses every run while this legacy file exists, so drop ours in both modes and keep any other policy.
approvals = path.parent / "exec-approvals.json"
if approvals.exists():
state = _read_json_object(approvals)
if state is not None:
defaults = state.get("defaults")
# Exact yolo fingerprint only: a user policy merely sharing askFallback=full must survive.
yolo_defaults = (("security", "full"), ("ask", "off"), ("askFallback", "full"))
is_yolo = isinstance(defaults, dict) and all(
defaults.get(k) == v for k, v in yolo_defaults
)
if is_yolo:
for k, _ in yolo_defaults:
del defaults[k]
if not defaults:
del state["defaults"]
# Socket metadata and an empty agents map carry no policy (doctor retires such a stub too).
if all(
k in ("version", "socket") or (k == "agents" and not v)
for k, v in state.items()
):
approvals.unlink()
typer.echo(f"Removed {approvals}")
else:
_write_private_json(approvals, state)
typer.echo(f"Updated {approvals}")
if approvals.exists():
# The rest is user policy; importing it is OpenClaw's migration, not ours.
typer.echo(
f"Note: {approvals} is a legacy exec approvals file, which OpenClaw 2026.8.1+ refuses to run with. "
f"Import it with: {_openclaw_doctor_command(path, windows = os.name == 'nt')}",
err = True,
)
if json.dumps(config, sort_keys = True) != before:
_write_private_json(path, config)
typer.echo(f"Updated {path}")
def opencode_output_limit(window: int, max_tokens: Optional[int] = None) -> int:
if max_tokens:
return max(1, min(int(max_tokens), window // 2))
return max(1, min(window // 4, _OPENCODE_OUTPUT_TOKEN_MAX))
def _agent_output_limit(window: int, max_tokens: Optional[int]) -> int:
output = opencode_output_limit(window, max_tokens)
if max_tokens and output < max_tokens:
typer.echo(
f"Warning: --max-tokens {max_tokens} leaves too little of the {window:,}-token "
f"context for the conversation; using {output:,}.",
err = True,
)
return output
def opencode_compaction_reserved(window: int, output: int) -> int:
return max(1, min(output, max(window // 10, 8192)))
def _agent_compacts_at(
agent: str,
window: int,
max_tokens: Optional[int] = None,
) -> int:
if agent == "claude":
output = min(opencode_output_limit(window), _CLAUDE_COMPACT_OUTPUT_RESERVE)
return min(window * 9 // 10, window - output - _CLAUDE_COMPACT_BUFFER)
return window - opencode_compaction_reserved(window, opencode_output_limit(window, max_tokens))
_CLAUDE_RESUME_ARGS = ({"-c", "--continue", "--fork-session"}, {"-r", "--resume", "--session-id"})
_OPENCODE_RESUME_ARGS = ({"-c", "--continue", "--fork", "--no-replay"}, {"-s", "--session"})
def _only_resumes(args: list, resume_args: tuple) -> bool:
"""True when the forwarded args only reopen an interactive session, which keeps the stock prompt."""
flags, valued = resume_args
rest = list(args)
while rest:
arg = rest.pop(0)
name = arg.split("=", 1)[0]
if name in flags:
continue
if name not in valued:
return False
if "=" not in arg and rest and not rest[0].startswith("-"):
rest.pop(0)
return True
def _early_context_check(model: Optional[str], check):
"""Run check now, or return it for _before_load when a running Studio could resolve model to a Connection."""
# A Connection is only known once _connect asks that server, and it never loads; an auto-started one serves no Connections.
if model and find_studio_server() is not None:
return check
check()
return None
def _before_load(context_check, preload = None):
if context_check is None:
return preload
def check(base, key, requested, gguf_variant):
context_check()
if preload is not None:
preload(base, key, requested, gguf_variant)
return check
def _command_line_options(ctx, quote) -> Optional[list]:
"""The options typed on this command line, minus --max-seq-length and --api-key."""
# Duck-typed: typer may vendor its own click, so isinstance / enum identity against ours fails.
if ctx is None:
return None
parts = []
for param in ctx.command.params:
if param.param_type_name != "option" or param.name in ("max_seq_length", "api_key"):
continue
if getattr(ctx.get_parameter_source(param.name), "name", None) != "COMMANDLINE":
continue
value = ctx.params.get(param.name)
if param.is_flag:
if value:
parts.append(param.opts[0])
elif param.secondary_opts:
parts.append(param.secondary_opts[0])
continue
for item in value if param.multiple else [value]:
if item is not None:
item = getattr(item, "value", item)
parts += [param.opts[0], quote(str(item))]
return parts
def _check_agent_context(
agent: str,
name: str,
entry: dict,
prompt_tokens: int,
max_tokens: Optional[int] = None,
loaded: bool = True,
refuse: bool = True,
model: Optional[str] = None,
gguf_variant: Optional[str] = None,
ctx = None,
) -> None:
window = entry.get("context_length") or entry.get("max_context_length")
if not window:
return
window = int(window)
roomy = 2 * prompt_tokens
compacts_at = _agent_compacts_at(agent, window, max_tokens)
# Before the load only refuse; the window Studio actually fits is checked again after it.
if compacts_at >= roomy or (not loaded and (compacts_at >= prompt_tokens or not refuse)):
return
suggested = next(
(
size
for size in (1 << bits for bits in range(14, 21))
if _agent_compacts_at(agent, size, max_tokens) >= roomy
),
1 << 20,
)
native = int(entry.get("native_context_length") or 0)
if native:
suggested = min(suggested, native)
if entry.get("connection"):
# --max-seq-length only labels a Connection's window; it cannot grow the provider's.
hint = "A Connection's context is set by its provider, so pick a model with a longer one."
elif native and (
native <= window or _agent_compacts_at(agent, native, max_tokens) < prompt_tokens
):
hint = f"Its full context is {native:,} tokens, so pick a model with a longer one."
else:
quote = _powershell_quote if os.name == "nt" else shlex.quote
given = _command_line_options(ctx, quote) or []
# A positional org/name (or none at all, outside a command) never reaches the option sources.
if model and not {"--model", "-m"} & set(given):
given = ["--model", quote(model), *given]
if gguf_variant and "--gguf-variant" not in given:
given += ["--gguf-variant", quote(gguf_variant)]
if max_tokens and "--max-tokens" not in given:
given += ["--max-tokens", str(int(max_tokens))]
if ctx is not None and ctx.get_parameter_source("api_key").name == "COMMANDLINE":
# Not remembered yet before the load; never echo the key itself.
given += ["--api-key", "<your key>"]
forwarded = list(ctx.args) if ctx is not None else []
target = "".join(f" {part}" for part in given)
# Only a refused launch's args (none, or resume flags) are echoed: scripted ones can carry a prompt.
if refuse:
tail = "".join(f" {quote(arg)}" for arg in forwarded)
else:
tail = " plus your other arguments" if forwarded else ""
hint = (
f"Run unsloth start {agent}{target} --max-seq-length {suggested}{tail} "
"(a smaller quant if that does not fit in memory"
+ ("" if loaded else "; for a Connection, a model with a longer context")
+ ")."
)
state = "is loaded" if loaded else "would load"
if compacts_at < prompt_tokens:
message = (
f"{entry['id']} {state} with {window:,} tokens of context, too few for {name}: "
f"its own instructions and tools take about {prompt_tokens:,}, so it would compact "
f"on every message. {hint}"
)
if refuse:
_fail(message)
typer.echo(f"Warning: {message}", err = True)
return
typer.echo(
f"Warning: {entry['id']} {state} with {window:,} tokens of context, and {name}'s "
f"instructions and tools take about {prompt_tokens:,} of it (more with MCP servers), "
f"so it will compact often. {hint}",
err = True,
)
def _opencode_output_env(model: dict, max_tokens: Optional[int]) -> dict:
"""Lift OpenCode's output ceiling when --max-tokens exceeds it; re-emit an inherited one so a --no-launch recipe keeps it."""
window = model.get("context_length") or model.get("max_context_length")
if not max_tokens:
return {}
if not window:
typer.echo(
"Warning: Unsloth Studio did not report the model's context length, so --max-tokens is ignored.",
err = True,
)
return {}
output = _agent_output_limit(int(window), max_tokens)
raw = os.environ.get(_OPENCODE_OUTPUT_TOKEN_MAX_ENV, "")
inherited = int(raw) if raw.isdigit() and int(raw) > 0 else None
ceiling = inherited or _OPENCODE_OUTPUT_TOKEN_MAX
if output <= ceiling and inherited is None:
return {}
return {_OPENCODE_OUTPUT_TOKEN_MAX_ENV: str(max(output, ceiling))}
def _opencode_provider(
base: str,
key: str,
model: dict,
max_tokens: Optional[int] = None,
request_body: Optional[dict] = None,
vision: bool = False,
) -> dict:
model_entry = {"name": model["id"]}
if vision:
model_entry["attachment"] = True
model_entry["modalities"] = {"input": ["text", "image"], "output": ["text"]}
window = model.get("context_length") or model.get("max_context_length")
if window:
window = int(window)
output = opencode_output_limit(window, max_tokens)
# 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}
if request_body:
# OpenCode 1.x sends model options, reading the effort only as reasoningEffort; 2.x sends only the provider body.
model_entry["options"] = {
"reasoningEffort" if name == "reasoning_effort" else name: value
for name, value in request_body.items()
}
if "temperature" in request_body:
model_entry["temperature"] = True
provider_options["body"] = request_body
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,
vision: bool = False,
) -> 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, vision
)
# 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:
for field in ("model", "small_model"):
if str(config.get(field) or "").startswith(f"{_OPENCODE_PROVIDER}/"):
config.pop(field, None)
# Drop a managed compaction block, current or legacy value.
managed = {reserved, max(1, window // 10)} if window else set()
compaction = config.get("compaction")
if (
isinstance(compaction, dict)
and compaction.keys() == {"auto", "reserved"}
and compaction["auto"] is True
and compaction["reserved"] in managed
):
config.pop("compaction", None)
_subdict(config, "agent")[_SUBAGENT_NAME] = {
"description": _SUBAGENT_DESCRIPTION,
"mode": "subagent",
"model": opencode_model,
"prompt": _SUBAGENT_INSTRUCTIONS,
}
else:
config["model"] = opencode_model
agents = config.get("agent")
if isinstance(agents, dict):
agents.pop(_SUBAGENT_NAME, None)
if not agents:
config.pop("agent", None)
if window and not as_subagent:
# The fixed 20k-token default buffer over-compacts, or never settles, on a small local context.
compaction = _subdict(config, "compaction")
compaction["auto"] = True
compaction["reserved"] = reserved
tools = ("edit", "bash", "webfetch", *(("task",) if as_subagent else ()))
if yolo:
# Fallback for commands without native --auto and for the append-safe bare --no-launch command, where the subcommand is not known yet. Rides inline (OPENCODE_CONFIG_CONTENT) so it wins over a project config. TUI and `run` launches use --auto and call here with yolo=False, letting OpenCode preserve explicit deny rules.
session_permission = {t: "allow" for t in tools}
session_permission["external_directory"] = {"*": "allow"}
config["permission"] = dict(session_permission)
else:
# Undo only what --yolo wrote: our yolo sets an explicit per-tool "allow" for these three tools, so flip exactly those explicit allows back to "ask". A "deny"/"ask", a granular object, a string, or a "*" catch-all is the user's own rule and is left untouched. We do NOT carry a permission inline for a non-yolo session: since OPENCODE_CONFIG_CONTENT outranks the project opencode.json we cannot read, any value forced there would override the user's project rules, weakening a project deny or auto-approving through a granular object's permissive default. Clearing our own persisted yolo state is the fix.
session_permission: dict = {}
permission = config.get("permission")
if isinstance(permission, dict):
for tool in tools:
if permission.get(tool) == "allow":
permission[tool] = "ask"
if permission.get("external_directory") == {"*": "allow"}:
permission["external_directory"] = {"*": "ask"}
if json.dumps(config, sort_keys = True) != before:
_write_private_json(path, config)
typer.echo(f"Updated {path}")
return session_permission
def _set_hermes_provider(
config: dict,
base: str,
model: dict,
request_body: Optional[dict] = None,
) -> None:
# 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}",
default = model["id"],
api_mode = "openai",
)
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
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)
# 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
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]
# Merge, not replace: Hermes refuses to resume a session once a field it froze on this entry (a user's api_key) is gone.
provider = _subdict(providers, _HERMES_PROVIDER)
provider.update(base_url = f"{base}/v1", api_mode = "openai", key_env = _HERMES_ENV_KEY)
if request_body:
provider["extra_body"] = request_body
else:
provider.pop("extra_body", None)
def _hermes_mcp_manifest(home: Path) -> tuple:
try:
state = json.loads((home / _HERMES_MCP_MANIFEST).read_text(encoding = "utf-8"))
origin, servers = state.get("origin"), set(state["servers"])
owned = set(state.get("env", ()))
except (OSError, ValueError, TypeError, KeyError, AttributeError):
return None, set(), set()
return (origin if isinstance(origin, str) else None), servers, owned
def _hermes_mcp_servers(home: Path) -> Optional[dict]:
import yaml
try:
config = yaml.safe_load((home / "config.yaml").read_text(encoding = "utf-8"))
except OSError:
return {}
except (yaml.YAMLError, ValueError):
return None
servers = config.get("mcp_servers") if isinstance(config, dict) else None
return servers if isinstance(servers, dict) else {}
def _with_user_hermes_mcp_servers(config: dict, home: Path) -> None:
home_key = home.resolve(strict = False)
configured = os.environ.get("HERMES_HOME", "").strip()
built = None
if configured:
configured = str(Path(configured).expanduser().resolve(strict = False))
origin = _hermes_mcp_manifest(Path(configured))[0]
if origin is not None:
# A home Unsloth built (the recipe exports HERMES_HOME=home) points back at its origin.
built, configured = Path(configured), origin
source = _hermes_user_home(configured)
if source.resolve(strict = False) == home_key:
configured = ""
source = _hermes_user_home()
if source.resolve(strict = False) == home_key:
return
servers = _hermes_mcp_servers(source)
if servers is None:
return
if built is not None and built.resolve(strict = False) != home_key:
# Servers added in that saved home (hermes mcp add in the recipe shell); the origin wins a clash.
inherited = _hermes_mcp_manifest(built)[1]
local = _hermes_mcp_servers(built) or {}
servers = {
**{n: v for n, v in local.items() if n not in inherited and n not in servers},
**servers,
}
carried = _hermes_mcp_manifest(home)[1]
current = config.get("mcp_servers")
# Only replace what came from the user's config; servers added in this home stay.
kept = {
name: spec
for name, spec in (current.items() if isinstance(current, dict) else ())
if name not in carried and name not in servers
}
if kept or servers:
config["mcp_servers"] = {**kept, **servers}
else:
config.pop("mcp_servers", None)
sources = ((source, set()), (built, _hermes_mcp_manifest(built)[2] if built else set()))
owned = _carry_hermes_mcp_env(home, config.get("mcp_servers", {}), sources)
(home / _HERMES_MCP_MANIFEST).write_text(
json.dumps({"origin": configured, "servers": sorted(servers), "env": owned}) + "\n",
encoding = "utf-8",
)
def _hermes_env_key(line: str) -> str:
return line.strip().removeprefix("export ").partition("=")[0].strip()
def _carry_hermes_mcp_env(home: Path, servers: dict, sources: tuple) -> list:
# Hermes fills ${VAR} in mcp_servers from HERMES_HOME/.env (hermes mcp add --auth bearer keeps tokens there): copy only those lines, verbatim, so Hermes parses them itself.
path = home / ".env"
try:
current = path.read_text(encoding = "utf-8").splitlines()
except (OSError, ValueError):
current = []
owned = _hermes_mcp_manifest(home)[2]
found = {_hermes_env_key(line) for line in current} - owned
wanted = set()
for ref in re.findall(r"\$\{([^}]+)\}", json.dumps(servers)):
ref = ref.strip()
wanted.add(ref[4:].strip() if ref.startswith("env:") else ref)
carried, local = [], set(found)
# A saved home's own copies are skipped so a key removed at the origin stays removed.
for source, skip in sources:
if source is None or source.resolve(strict = False) == home.resolve(strict = False):
continue
try:
lines = (source / ".env").read_text(encoding = "utf-8").splitlines()
except (OSError, ValueError):
continue
keys = {_hermes_env_key(line) for line in lines} & (wanted - found - skip)
carried += [line for line in lines if _hermes_env_key(line) in keys]
found |= keys
lines = [line for line in current if _hermes_env_key(line) in local] + carried
if lines != current:
if lines:
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w", encoding = "utf-8") as handle:
handle.write("\n".join(lines) + "\n")
else:
path.unlink(missing_ok = True)
return sorted(found - local)
def write_hermes_config(
base: str,
model: dict,
path: Path,
request_body: Optional[dict] = None,
keep_mcp_servers: bool = False,
) -> None:
import yaml
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)
if keep_mcp_servers:
_with_user_hermes_mcp_servers(config, path.parent)
text = yaml.safe_dump(config, sort_keys = False)
if not path.exists() or path.read_text(encoding = "utf-8") != text:
path.parent.mkdir(parents = True, exist_ok = True)
path.write_text(text, encoding = "utf-8")
typer.echo(f"Updated {path}")
def _vibe_env(
base: str,
model: dict,
request_body: Optional[dict] = None,
vision: bool = False,
) -> dict:
"""VIBE_* env vars outrank config.toml, so the user's Vibe config is never written."""
entry = {"name": model["id"], "provider": _VIBE_PROVIDER, "alias": _VIBE_MODEL_ALIAS}
if vision:
entry["supports_images"] = True
# Vibe sends its own temperature (0.2 by default) with every request.
temperature = (request_body or {}).get("temperature")
if temperature is not None:
entry["temperature"] = float(temperature)
window = model.get("context_length") or model.get("max_context_length")
if window:
window = int(window)
entry["max_context_length"] = window
# Vibe's 200k default is past most local windows; Vibe 3 needs min(24k, window / 4) free.
entry["auto_compact_threshold"] = min(
int(window * 0.9), window - min(24_000, math.ceil(window / 4))
)
provider = {
"name": _VIBE_PROVIDER,
"api_base": f"{base}/v1",
"api_key_env_var": _VIBE_ENV_KEY,
"api_style": "openai",
"backend": "generic",
}
return {
"VIBE_PROVIDERS": json.dumps([provider]),
"VIBE_MODELS": json.dumps([entry]),
"VIBE_ACTIVE_MODEL": _VIBE_MODEL_ALIAS,
# An inherited allowlist or resumed cloud session would select a hosted model.
"VIBE_ALLOWED_MODELS": json.dumps(["re:" + re.escape(model["id"])]),
"VIBE_ENABLE_TELEMETRY": "false",
"VIBE_ENABLE_UPDATE_CHECKS": "false",
"VIBE_ENABLE_AUTO_UPDATE": "false",
"VIBE_ENABLE_NOTIFICATIONS": "false",
}
def write_pi_config(
base: str,
key: str,
model: dict,
path: Path,
*,
max_tokens: Optional[int] = None,
request_body: Optional[dict] = None,
vision: bool = False,
) -> None:
config = _read_json_object(path)
if config is None:
typer.echo(
f"Warning: couldn't parse {path} — add an 'unsloth' provider there "
"yourself, or move the file aside and re-run.",
err = True,
)
return
before = json.dumps(config, sort_keys = True)
# Pi reads custom providers from $PI_CODING_AGENT_DIR/models.json; the key lives there, not in the env, matching openclaw/opencode.
provider_model = {"id": model["id"]}
if vision:
provider_model["input"] = ["text", "image"]
window = model.get("context_length") or model.get("max_context_length")
if window:
window = int(window)
# An unspecified model defaults to contextWindow 128000 / maxTokens 16384, far larger than a small Unsloth context, so Pi compacts too late and overflows the server. Pin the real window and a sane output cap, mirroring OpenCode.
provider_model["contextWindow"] = window
provider_model["maxTokens"] = _agent_output_limit(window, max_tokens)
elif max_tokens:
provider_model["maxTokens"] = max_tokens
if request_body:
provider_model["samplingParams"] = request_body
_subdict(config, "providers")[_PI_PROVIDER] = {
"api": "openai-completions",
"baseUrl": f"{base}/v1",
"apiKey": key,
"models": [provider_model],
}
if json.dumps(config, sort_keys = True) != before:
_write_private_json(path, config)
typer.echo(f"Updated {path}")
def _link_user_dir(source: Path, target: Path) -> bool:
"""Expose source at target. True once target resolves to source."""
# Refresh links, but preserve real session directories.
if target.is_symlink() or _is_junction(target):
_remove_overlay_entry(target)
if target.exists() or not source.is_dir():
return False
target.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
try:
target.symlink_to(source, target_is_directory = True)
except OSError:
if not _create_directory_junction(source, target):
typer.echo(f"Warning: couldn't link {source} into the Pi session.", err = True)
return False
return True
def _pi_local_entry(entry: str, source: Path, home: Path, linked: frozenset) -> str:
"""Re-anchor a user path from the original Pi agent directory."""
value = entry.strip()
if not value or value == "." or value.startswith("file:"):
# Nothing to anchor: "" and "." would name the whole agent directory.
return entry
if value == "~" or value.startswith(("~/", "~" + os.sep)):
target = os.path.join(home, value[2:])
else:
# Pi stores local packages relative to its agent directory.
target = os.path.join(source, value)
target = os.path.normpath(target)
try:
relative = os.path.relpath(target, source)
except ValueError: # on another Windows drive
return target
# Session-relative only where the link landed; where a real session directory blocks it, the entry would point into that directory instead.
if relative.split(os.sep)[0] in linked:
return relative
return target
def _pi_settings_entries(key: str, entries, source: Path, home: Path, linked: frozenset) -> list:
if not isinstance(entries, list):
return []
result = []
for entry in entries:
if key == "packages":
spec = entry.get("source") if isinstance(entry, dict) else entry
# All other package sources are local paths.
if isinstance(spec, str) and not spec.strip().startswith(
("npm:", "git:", "github:", "http:", "https:", "ssh:")
):
spec = _pi_local_entry(spec, source, home, linked)
entry = {**entry, "source": spec} if isinstance(entry, dict) else spec
elif isinstance(entry, str):
prefix = entry[:1] if entry.startswith(("!", "+", "-")) else ""
pattern = entry[len(prefix) :]
if not prefix and "*" not in entry and "?" not in entry:
entry = _pi_local_entry(entry, source, home, linked)
elif not pattern.strip().startswith("~"): # Pi does not expand ~ in patterns
# The agent directory moved; keep the original too, it still matches basenames.
anchored = prefix + _pi_local_entry(
pattern,
source,
home,
linked,
)
if anchored != entry:
result.append(entry)
entry = anchored
result.append(entry)
return result
def _clear_pi_user_resources(agent_dir: Path) -> None:
"""Undo what an earlier launch linked and copied, leaving session state alone."""
for target in (agent_dir / name for name in _PI_USER_RESOURCE_DIRS):
if target.is_symlink() or _is_junction(target):
_remove_overlay_entry(target)
manifest_path = agent_dir / _PI_USER_RESOURCES_MANIFEST
previous = _read_json_object(manifest_path)
if not previous:
return
settings_path = agent_dir / "settings.json"
settings = _read_json_object(settings_path)
if settings is None:
return
before = json.dumps(settings, sort_keys = True)
for key, copied in previous.items():
own = settings.get(key)
if key in _PI_USER_VERBATIM_SETTINGS:
# An argument vector, not entries: subtracting drops whatever the two share.
if own == copied:
settings.pop(key, None)
elif isinstance(copied, list) and isinstance(own, list):
rest = [item for item in own if item not in copied]
if rest:
settings[key] = rest
else:
settings.pop(key, None)
elif own == copied:
settings.pop(key, None)
if json.dumps(settings, sort_keys = True) != before:
_write_private_json(settings_path, settings)
manifest_path.unlink(missing_ok = True)
def write_pi_user_resources(agent_dir: Path) -> None:
"""Expose selected user Pi resources inside an isolated session."""
if _wsl_windows_executable(["pi"]):
# Windows Pi cannot follow WSL links into mounted drives; drop those.
_clear_pi_user_resources(agent_dir)
return
user_home = Path.home()
configured = os.environ.get("PI_CODING_AGENT_DIR")
configured = configured.strip() if configured else ""
# Pi resolves a relative override from the launch directory.
source = (
Path(os.path.abspath(os.path.expanduser(configured)))
if configured
else user_home / ".pi" / "agent"
)
if source.resolve(strict = False) == agent_dir.resolve(strict = False):
# Do not treat this session as its own resource source.
source = user_home / ".pi" / "agent"
if configured and not source.is_dir():
# Otherwise this looks exactly like the bug this function exists to fix.
typer.echo(
f"Warning: PI_CODING_AGENT_DIR points at {source}, which is not a directory; "
"no Pi extensions or packages will load in this session.",
err = True,
)
linked = frozenset(
name for name in _PI_USER_RESOURCE_DIRS if _link_user_dir(source / name, agent_dir / name)
)
user_settings_path = source / "settings.json"
user_settings = _read_json_object(user_settings_path)
if user_settings is None:
typer.echo(
f"Warning: couldn't parse {user_settings_path}; "
"Pi packages listed there won't load in this session.",
err = True,
)
user_settings = {}
settings_path = agent_dir / "settings.json"
settings = _read_json_object(settings_path)
if settings is None:
typer.echo(
f"Warning: couldn't parse {settings_path}; your Pi packages won't load in this session.",
err = True,
)
return
manifest_path = agent_dir / _PI_USER_RESOURCES_MANIFEST
previous = _read_json_object(manifest_path)
if previous is None:
# Provenance is lost, so entries the user has since removed cannot be reconciled.
typer.echo(
f"Warning: couldn't parse {manifest_path}; Pi resources copied by an earlier "
"launch stay in this session even if you removed them since.",
err = True,
)
previous = {}
before = json.dumps(settings, sort_keys = True)
copied = {}
for key in _PI_USER_RESOURCE_SETTINGS:
entries = _pi_settings_entries(
key,
user_settings.get(key),
source,
user_home,
linked,
)
# Refresh copied entries while preserving settings added inside the session.
stale = previous.get(key) if isinstance(previous.get(key), list) else []
own = settings.get(key)
if own is not None and not isinstance(own, list):
# Pi types these as arrays; leave a shape we do not understand alone.
typer.echo(
f"Warning: {settings_path} has a non-list {key!r}; "
"leaving it as is, so your Pi entries for it won't load in this session.",
err = True,
)
continue
own = [item for item in own or [] if item not in stale and item not in entries]
if entries or own:
# Pi keeps the FIRST duplicate package, so session entries lead; patterns stay user-first.
settings[key] = own + entries if key == "packages" else entries + own
else:
settings.pop(key, None)
if entries:
copied[key] = entries
for key in _PI_USER_VERBATIM_SETTINGS:
# Pi runs every package lookup and install through npmCommand; inherit it along with the package list or npm cannot find them.
value = user_settings.get(key)
own = settings.get(key)
if own is not None and own != previous.get(key):
continue # changed inside the session, so the session owns it now
if isinstance(value, list) and value and all(isinstance(arg, str) for arg in value):
settings[key] = value
copied[key] = value
else:
settings.pop(key, None)
if json.dumps(settings, sort_keys = True) != before:
_write_private_json(settings_path, settings)
if copied != previous:
if copied:
_write_private_json(manifest_path, copied)
else:
manifest_path.unlink(missing_ok = True)
def write_pi_subagent_config(
base: str,
key: str,
model: dict,
path: Path,
approve: bool = False,
max_tokens: Optional[int] = None,
request_body: Optional[dict] = None,
vision: bool = False,
) -> None:
"""Write private bootstrap data for the bundled Pi extension."""
window = model.get("context_length") or model.get("max_context_length")
window = int(window) if window else 32768
_write_private_json(
path,
{
"baseUrl": f"{base}/v1",
"apiKey": key,
"model": model["id"],
"contextWindow": window,
"maxTokens": _agent_output_limit(window, max_tokens),
"approve": approve,
**({"samplingParams": request_body} if request_body else {}),
**({"vision": True} if vision else {}),
},
)
def write_dsh_patch(
base: str,
model: dict,
path: Path,
request_body: Optional[dict] = None,
vision: bool = False,
) -> None:
"""dsh 0.1.7 dropped settings.yaml, which only applies after a first boot still on the DeepSeek
default; the --patch overlay is read at boot and rewritten whole, as it is Unsloth's own."""
import yaml
model_entry = {"id": model["id"]}
if vision:
model_entry["input"] = ["text", "image"]
window = model.get("context_length") or model.get("max_context_length")
if window:
window = int(window)
model_entry["contextWindow"] = window
model_entry["maxTokens"] = opencode_output_limit(window)
compat = {"supportsDeveloperRole": False, "maxTokensField": "max_tokens"}
if request_body:
# dsh sends template kwargs only for a model that declares reasoning levels.
model_entry["reasoningEfforts"] = {
"off": None,
"low": "low",
"medium": "medium",
"high": "high",
}
compat["thinkingFormat"] = "chat-template"
compat["chatTemplateKwargs"] = request_body
entries = [
{
"id": "llm-pi-ai",
"name": "@deepseek-ai/dsh-llm-pi-ai",
"config": {
"providers": {
_DSH_PROVIDER: {
"displayName": "Unsloth Studio",
"api": "openai-completions",
"baseURL": f"{base}/v1",
"apiKeyEnv": _DSH_ENV_KEY,
# pi-ai reads an unknown base URL as OpenAI itself.
"compat": compat,
"models": [model_entry],
}
}
},
},
{
"id": "agent-default-model",
"name": "@deepseek-ai/dsh-agent-default-model",
"config": {"provider": _DSH_PROVIDER, "model": model["id"]},
},
]
text = yaml.safe_dump(entries, sort_keys = False)
if not path.exists() or path.read_text(encoding = "utf-8") != text:
path.parent.mkdir(parents = True, exist_ok = True)
path.write_text(text, encoding = "utf-8")
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],
*,
allow_json5: bool = False,
) -> Optional[dict]:
if text is None or not text.strip():
return {}
if allow_json5:
import json5
# Raw text: the JSONC stripper below misreads // inside single-quoted JSON5 strings.
# The json round trip joins surrogate pairs json5 leaves split (UTF-8 can't write them).
data = json.loads(json.dumps(json5.loads(text)))
elif 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:
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],
*,
allow_json5: bool = False,
) -> Optional[dict]:
try:
return _load_app_config(path, text, allow_json5 = allow_json5)
except Exception:
_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,
*,
allow_json5: bool = False,
) -> Optional[str]:
config = _parse_app_config(path, text, allow_json5 = allow_json5)
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:
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 allow_json5 or 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, allow_json5 = allow_json5) == config:
return candidate
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],
parse = _parse_app_config,
) -> 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)
if target.agent == "openclaw":
parse = functools.partial(_parse_app_config, allow_json5 = True)
parse(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),
allow_json5 = target.agent == "openclaw",
)
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. If this command is killed instead, the next `unsloth start codex` "
"switches the app back."
)
_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, _accepts_images(base, key, entry)
)
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, allow_json5 = True) 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']}"
provider = _openclaw_provider(base, key, entry, max_tokens, _accepts_images(base, key, entry))
changes = [(("models", "providers", "unsloth"), provider)]
# 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_config_file() -> Optional[str]:
executable = _which_with_install_dirs("openclaw")
if executable is None:
return None
try:
output = subprocess.check_output(
[executable, "config", "file"],
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 60,
stderr = subprocess.DEVNULL,
env = _probe_env(),
)
except Exception:
return None
lines = [line.strip() for line in output.splitlines() if line.strip()]
return lines[-1] if lines and os.path.isabs(lines[-1]) else None
def _openclaw_app_target(max_tokens: Optional[int] = None) -> _AppTarget:
home = Path.home()
def user_path(value: str) -> Path:
# Only a leading ~ expands (against OPENCLAW_HOME); abspath keeps symlinks for _read_app_file to refuse.
if value == "~":
value = str(home)
elif value.startswith(("~/", "~\\")):
value = os.path.join(str(home), value[2:])
return Path(os.path.abspath(value))
override = os.environ.get("OPENCLAW_HOME", "").strip()
if override and override not in ("null", "undefined"):
home = user_path(override)
if override := os.environ.get("OPENCLAW_CONFIG_PATH", "").strip():
path = user_path(override)
elif override := os.environ.get("OPENCLAW_STATE_DIR", "").strip():
path = user_path(override) / "openclaw.json"
else:
path = home / ".openclaw" / "openclaw.json"
profile = os.environ.get("OPENCLAW_PROFILE", "").strip()
# Whether a named profile alone moves the config depends on the build (openclaw#133252, after 2026.10.10-beta.3), so ask OpenClaw.
if _OPENCLAW_PROFILE_RE.fullmatch(profile) and profile.lower() != "default":
if (active := _openclaw_config_file()) is not None:
path = Path(active)
updates = functools.partial(_openclaw_app_updates, max_tokens = max_tokens)
return _AppTarget("openclaw", "OpenClaw app", path, updates)
def _hermes_user_home(configured: str = "") -> Path:
if configured:
home = Path(configured).expanduser()
if home.parent.name == "profiles":
return home
elif sys.platform == "win32":
# Hermes' Windows default home (hermes_constants._get_platform_default_hermes_home).
local = os.environ.get("LOCALAPPDATA", "").strip()
home = (Path(local) if local else Path.home() / "AppData" / "Local") / "hermes"
else:
home = Path.home() / ".hermes"
try:
profile = (home / "active_profile").read_text(encoding = "utf-8").strip()
except OSError:
profile = ""
if profile != "default" and re.fullmatch(r"[A-Za-z0-9_][A-Za-z0-9._-]*", profile):
return home / "profiles" / profile
return home
def _hermes_app_target(request_body: Optional[dict] = None) -> _AppTarget:
# Hermes Desktop follows the sticky active profile.
path = _hermes_user_home() / "config.yaml"
def updates(text, path, base, key, entry):
settings: dict = {}
_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}}
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)
_VSCODE_GROUP = "Unsloth"
_VSCODE_DEFAULT_CONTEXT = 32768
# Copilot's Agent prompt (instructions + tool schemas) does not fit in a smaller window.
_VSCODE_AGENT_MIN_CONTEXT = 32768
def _vscode_models_path() -> Path:
if sys.platform == "win32":
appdata = os.environ.get("APPDATA", "").strip()
root = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
elif sys.platform == "darwin":
root = Path.home() / "Library" / "Application Support"
else:
root = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
code = _wsl_windows_executable(["code"])
if code and not any((root / app / "User").is_dir() for app in ("Code", "Code - Insiders")):
# Under WSL, Windows VS Code reads its own user dir, not the distro's.
root = _wsl_windows_user_profile(code, "VS Code") / "AppData" / "Roaming"
app = "Code"
if not (root / "Code" / "User").is_dir() and (root / "Code - Insiders" / "User").is_dir():
app = "Code - Insiders"
return root / app / "User" / "chatLanguageModels.json"
def _vscode_groups(path: Path, text: Optional[str]) -> list:
if text is None or not text.strip():
return []
try:
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))
except ValueError:
data = None
if not isinstance(data, list):
_fail(f"Couldn't parse {path}, so it was left as is. Fix it and re-run.")
return data
def _is_unsloth_vscode_group(group: object) -> bool:
return (
isinstance(group, dict)
and group.get("vendor") == "customendpoint"
and group.get("name") == _VSCODE_GROUP
)
def _vscode_models_text(
text: Optional[str],
path: Path,
base: str,
key: str,
entry: dict,
max_tokens: Optional[int] = None,
tool_calling: bool = True,
vision: bool = False,
replaced: frozenset = frozenset(),
thinking: bool = False,
) -> Optional[str]:
groups = _vscode_groups(path, text)
window = int(
entry.get("context_length") or entry.get("max_context_length") or _VSCODE_DEFAULT_CONTEXT
)
output = _agent_output_limit(window, max_tokens)
model = {
"id": entry["id"],
"name": entry["id"],
"url": f"{base}/v1/chat/completions",
"apiType": "chat-completions",
# Agent mode lists only tool-calling models; Studio rejects tools for the rest.
"toolCalling": tool_calling,
"vision": vision,
# Without it VS Code drops reasoning_content when it replays an agent tool round.
"thinking": thinking,
"contextWindow": window,
"maxInputTokens": window - output,
"maxOutputTokens": output,
# A raw apiKey is read as a secret-storage reference and dropped, so the key rides here.
"requestHeaders": {"Authorization": f"Bearer {key}"},
}
index = next((i for i, g in enumerate(groups) if _is_unsloth_vscode_group(g)), None)
updated = list(groups)
if index is None:
updated.append({"name": _VSCODE_GROUP, "vendor": "customendpoint", "models": [model]})
else:
# Replace only the models this command wrote; the rest of the group is the user's.
group = dict(groups[index])
drop = replaced | {entry["id"]}
kept = [
m
for m in group.get("models") or []
if not (isinstance(m, dict) and m.get("id") in drop)
]
group["models"] = [*kept, model]
updated[index] = group
if updated == groups:
return text
return json.dumps(updated, indent = 2, ensure_ascii = False) + "\n"
def _vscode_capabilities(base: str, key: str, entry: dict) -> tuple:
# Scoped to the slot serving this model; an older server ignores the query and answers for the primary.
try:
query = urlencode({"model": entry["id"]})
status = _http_json("GET", f"{base}/api/inference/status?{query}", key)
except Exception:
status = {}
resident = any(
_model_id_matches(entry["id"], status_id, allow_casefold = is_loopback_url(base))
for status_id in (status.get("active_model"), status.get("model_identifier"))
if status_id
)
if not resident:
# Only a status about this model can vouch for it; an older server reports nothing.
return True, False, False
return (
status.get("supports_tools") is not False,
status.get("is_vision") is True,
status.get("supports_reasoning") is True,
)
def _accepts_images(base: str, key: str, entry: dict) -> bool:
return _vscode_capabilities(base, key, entry)[1]
def _container_engine() -> Optional[str]:
# `docker run unsloth/unsloth` sets none of the env vars below, only these markers.
if os.path.exists("/.dockerenv"):
return "docker"
if os.path.exists("/run/.containerenv"):
return "podman"
return None
_VSCODE_REMOTE_ENV = ("SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY", "REMOTE_CONTAINERS", "CODESPACES")
def _vscode_over_ssh(path: Path, unconfirmed: bool = False) -> bool:
if sys.platform in ("win32", "darwin"):
return False
if path.parent.is_dir():
# In a container, a dir holding only what an earlier release of this command wrote there
# (state without "written") is not VS Code's.
return (
unconfirmed
and _container_engine() is not None
and path.is_file()
and all(p.name.lstrip(".").startswith(path.name) for p in path.parent.iterdir())
)
return (
any(os.environ.get(name) for name in _VSCODE_REMOTE_ENV) or _container_engine() is not None
)
def _add_vscode_provider(
base: str,
explicit_key: Optional[str],
entry: dict,
max_tokens: Optional[int] = None,
tool_calling: bool = True,
vision: bool = False,
thinking: bool = False,
) -> None:
target = _AppTarget("vscode", "VS Code", _vscode_models_path())
state, key_id = {}, None
try:
state_path, state, text, key, key_id = _open_app_config(
target, base, explicit_key, _vscode_groups
)
remote = _vscode_over_ssh(target.path, bool(state) and not state.get("written"))
new_text = _vscode_models_text(
None if remote else text,
target.path,
base,
key,
entry,
max_tokens,
tool_calling,
vision,
frozenset(state.get("models") or ()),
thinking,
)
new_state = {
"path": str(target.path),
"base": base,
"key": key,
"key_id": key_id,
"models": [entry["id"]],
"written": not remote,
}
if remote:
# Keep the key in state so a re-run reuses it; a file here would never be read.
_save_app_config(target, state_path, state, new_state, None, None)
else:
_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
if remote:
url = urlparse(base)
port = url.port or (443 if url.scheme == "https" else 80)
managed = any(os.environ.get(name) for name in _VSCODE_REMOTE_ENV)
engine = _container_engine()
if not is_loopback_url(base):
reach = f"make sure your machine can reach {base}"
elif engine and not managed:
reach = (
f"publish port {port} to the same port on your machine (for example: "
f"{engine} run -p {port}:{port} ...)"
)
else:
reach = (
f"forward port {port} to the same port on your machine (for example: "
f"ssh -L {port}:127.0.0.1:{port} <this host>)"
)
typer.echo(
"This is a remote session (SSH or a container) with no VS Code user dir here, so "
"nothing was written. VS Code does not list these models in remote windows yet "
f"(microsoft/vscode#332085), so {reach}. Then, in a local VS Code window, run "
"Chat: Manage Language Models, open chatLanguageModels.json and add:"
)
typer.echo(json.dumps(json.loads(new_text)[0], indent = 2, ensure_ascii = False))
_app_server_notice(base)
return
typer.echo(
f"Added {entry['id']} from Unsloth at {base} to VS Code. In the Copilot Chat model "
f"picker, pick it under {_VSCODE_GROUP} (Manage Models if it is hidden; run "
"Developer: Reload Window if VS Code is open). Needs the GitHub Copilot Chat "
"extension; no Copilot plan is required."
)
if os.environ.get("WSL_DISTRO_NAME") and target.path.parts[:2] == ("/", "mnt"):
typer.echo(
"Use it from a local VS Code window: VS Code does not list these models in remote "
"(WSL, SSH, container) windows yet (microsoft/vscode#332085)."
)
if not tool_calling:
typer.echo(
f"{entry['id']} has no tool-calling chat template, so it is offered in Ask mode, "
"not Agent mode."
)
window = entry.get("context_length") or entry.get("max_context_length")
if tool_calling and window and int(window) < _VSCODE_AGENT_MIN_CONTEXT:
typer.echo(
f"Warning: {entry['id']} is loaded with {int(window):,} tokens of context, too few "
"for Copilot's Agent mode, which sends about 20,000 tokens of instructions before "
"your message. Load it with --context-length "
f"{_VSCODE_AGENT_MIN_CONTEXT} and re-run unsloth start vscode.",
err = True,
)
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("After loading another model, re-run: unsloth start vscode")
_app_server_notice(base)
@start_app.command("claude", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def claude(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
as_subagent: bool = _AS_SUBAGENT_OPTION,
auto_route: bool = _AUTO_ROUTE_OPTION,
):
"""Point Claude Code 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)
# The route gate is a hook the Windows claude cannot run from WSL, so its own tools would stay on.
if auto_route and _wsl_windows_executable(["claude"]):
_fail("--auto-route needs claude installed inside WSL, not the Windows claude.")
as_subagent = as_subagent or auto_route
install_hint = (
"irm https://claude.ai/install.ps1 | iex"
if os.name == "nt"
else "curl -fsSL https://claude.ai/install.sh | bash"
)
# 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(
_CLAUDE_GGUF_AGENT, model, serve = serve, launch = launch, gguf_variant = gguf_variant
)
# Only a bare or resumed interactive launch is refused: its prompt is the stock one and the TUI would hide a warning. Other forwarded args (-p, --tools, a --no-launch recipe a driver extends) can shrink the prompt, so they only warn.
# CLAUDE_CODE_SIMPLE is the env form of --bare: a minimal prompt that may fit, so it only warns too.
simple = os.environ.get("CLAUDE_CODE_SIMPLE", "").strip().lower() not in (
"",
"0",
"false",
"no",
"off",
)
refuse_small_context = launch and not simple and _only_resumes(ctx.args, _CLAUDE_RESUME_ARGS)
context_check = None
if max_seq_length > 0 and not as_subagent:
# Before the load, which would evict the resident model only for this to refuse.
context_check = _early_context_check(
model,
functools.partial(
_check_agent_context,
"claude",
"Claude Code",
{"id": model or "The loaded model", "context_length": max_seq_length},
_CLAUDE_PROMPT_TOKENS,
loaded = False,
model = model,
gguf_variant = gguf_variant,
ctx = ctx,
refuse = refuse_small_context,
),
)
_require_agent_for_launch("claude", install_hint, launch)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = _ALL_REQUEST_FIELDS,
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
preload_check = _before_load(
context_check, functools.partial(_attach_gguf_check, _CLAUDE_GGUF_AGENT)
),
server_options = server_options,
connections = True,
)
# Before the launch owns the server, so a rejection tears it down, not atexit.
try:
if not entry.get("connection"):
_require_gguf_for_agent(_CLAUDE_GGUF_AGENT, base, key, entry["id"])
if not as_subagent:
_check_agent_context(
"claude",
"Claude Code",
entry,
_CLAUDE_PROMPT_TOKENS,
refuse = refuse_small_context,
model = model,
gguf_variant = gguf_variant,
ctx = ctx,
)
except BaseException:
_shutdown_auto_served()
raise
model_id = entry["id"]
if as_subagent:
subagent_id = (
model_id
if entry.get("connection")
else _subagent_model_id(base, key, entry, model, gguf_variant)
)
subagent_model = {**entry, "id": subagent_id}
window = subagent_model.get("context_length") or subagent_model.get("max_context_length")
server_env = {
"UNSLOTH_CLAUDE_SUBAGENT_BASE_URL": base,
"UNSLOTH_CLAUDE_SUBAGENT_API_KEY": key,
"UNSLOTH_CLAUDE_SUBAGENT_MODEL": subagent_id,
"UNSLOTH_CLAUDE_SUBAGENT_BYPASS_PERMISSIONS": "1" if yolo else "0",
}
if window:
server_env["UNSLOTH_CLAUDE_SUBAGENT_CONTEXT_WINDOW"] = str(int(window))
if server_options.request_body():
server_env["CLAUDE_CODE_EXTRA_BODY"] = json.dumps(server_options.request_body())
if auto_route:
server_env[_CLAUDE_SUBAGENT_AUTO_ROUTE_ENV] = "1"
with _session_config("claude-subagent", launch, persist = persist) as config:
plugin = write_claude_subagent_plugin(config, server_env)
command = [
"claude",
"--plugin-dir",
_agent_config_path(plugin, ["claude"]),
# Before ctx.args: a forwarded `--` would turn later flags positional. The `=` form is used because --allowedTools is variadic, so a detached value swallows the first forwarded positional.
f"--allowedTools={_CLAUDE_SUBAGENT_TOOL},{_CLAUDE_SUBAGENT_PLAN_TOOL}",
*_yolo_command_flags("claude", yolo),
*ctx.args,
]
typer.echo(
"Unsloth is available as a local agent. "
+ (
"Claude hands routine work to it on its own."
if auto_route
else "Ask Claude to spawn an Unsloth or local agent."
)
)
_run(
base,
subagent_model,
{},
command,
launch = launch,
install_hint = install_hint,
)
return
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, user_settings)
command = _claude_local_command(
model_id,
_agent_config_path(settings, ["claude"]),
yolo,
args,
)
_run(
base,
entry,
env,
command,
launch = launch,
install_hint = install_hint,
unset_env = _CLAUDE_ENV_UNSET,
)
@start_app.command("codex", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def codex(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
as_subagent: bool = _AS_SUBAGENT_OPTION,
auto_route: bool = _AUTO_ROUTE_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)
as_subagent = as_subagent or auto_route
_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, gguf_variant = gguf_variant
)
executable = _require_agent_for_launch("codex", install_hint, launch and not app)
version = executable and _codex_executable_version(executable)
if version and version < _CODEX_PROFILE_FILE_MIN_VERSION:
needed = (
f"Codex {'.'.join(map(str, _CODEX_PROFILE_FILE_MIN_VERSION))} or newer is needed, "
f"but {executable} is {'.'.join(map(str, version))}."
)
update_hint = _codex_update_hint(executable)
updated = update_hint and _install_agent("codex", update_hint, update = True)
version = updated and _codex_executable_version(updated)
if not updated or (version and version < _CODEX_PROFILE_FILE_MIN_VERSION):
if update_hint:
_fail(f"{needed} Update it with `{update_hint}`.")
_fail(
f"{needed} Update it the way it was installed, or remove it so "
"`unsloth start codex` can install a current one."
)
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
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
# 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,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
preload_check = functools.partial(_attach_gguf_check, _CODEX_GGUF_AGENT),
server_options = server_options,
connections = True,
)
# This preflight runs after _connect may have auto-started a server but before _run takes over its lifecycle, so tear the server down here if it rejects the model (a transformers-backend model) rather than leaving it on the atexit backstop.
try:
if not entry.get("connection"):
_require_gguf_for_agent(_CODEX_GGUF_AGENT, base, key, entry["id"])
except BaseException:
_shutdown_auto_served()
raise
if app and entry.get("connection"):
_fail("The Codex app can't use a Connection model yet. Drop --app to run it in Codex.")
if app:
return _codex_app_session(base, api_key, entry)
if as_subagent:
subagent_id = (
entry["id"]
if entry.get("connection")
else _subagent_model_id(base, key, entry, model, gguf_variant)
)
subagent_model = {**entry, "id": subagent_id}
with _session_config("codex-subagent", launch, persist = persist) as home:
bridge_config = write_codex_subagent_bridge(
base,
key,
subagent_model,
home,
yolo = yolo,
reasoning_effort = codex_effort,
auto_route = auto_route,
)
parent_home = write_codex_parent_overlay(home / "parent", auto_route = auto_route)
command = [
"codex",
*_codex_subagent_flags(bridge_config),
*(_CODEX_AUTO_ROUTE_FLAGS if auto_route else []),
*_yolo_command_flags("codex", yolo),
*ctx.args,
]
typer.echo(
"Unsloth is available as a local agent. "
+ (
"Codex hands routine work to it on its own."
if auto_route
else "Ask Codex to spawn an Unsloth or local agent."
)
)
_run(
base,
subagent_model,
{"CODEX_HOME": str(parent_home)},
command,
launch = launch,
install_hint = install_hint,
)
return
command = [
"codex",
"--oss",
"--profile",
_CODEX_PROFILE,
*_yolo_command_flags("codex", yolo),
*ctx.args,
]
with _session_config("codex", launch, persist = persist) as home:
write_codex_config(base, entry, home, codex_effort, keep_mcp_servers = True)
env = {_CODEX_ENV_KEY: key, "CODEX_HOME": str(home)}
_run(
base,
entry,
env,
command,
launch = launch,
install_hint = install_hint,
unset_env = _CODEX_ENV_UNSET,
)
@start_app.command("openclaw", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def openclaw(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
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 and not app)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = frozenset() if app else _ALL_REQUEST_FIELDS,
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
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:
openclaw_args = ["tui", "--local"]
command = ["openclaw", *openclaw_args]
with _session_config("openclaw", launch, persist = persist) as cfg:
config_path = cfg / "openclaw.json"
# The key lives in the config, not the env; --yolo writes the exec policy here too. Resolve the project only when the recipe executes: a --no-launch command may be generated in one directory, saved, and intentionally run later from another.
write_openclaw_config(
base,
key,
entry,
config_path,
yolo = yolo,
workspace_path = "${OPENCLAW_WORKSPACE_DIR}",
embedding_model = _studio_embedding_model(base, key),
request_body = server_options.request_body(),
max_tokens = max_tokens,
vision = _accepts_images(base, key, entry),
)
# Scope config and state so OpenClaw never touches ~/.openclaw. Shell env off, else it re-imports keys.
env = {
"OPENCLAW_CONFIG_PATH": str(config_path),
"OPENCLAW_STATE_DIR": str(cfg),
"OPENCLAW_LOAD_SHELL_ENV": "0",
}
_run(
base,
entry,
env,
command,
launch = launch,
install_hint = install_hint,
unset_env = _OPENCLAW_ENV_UNSET,
cwd_env = ("OPENCLAW_WORKSPACE_DIR",),
)
@start_app.command("opencode", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def opencode(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
as_subagent: bool = _AS_SUBAGENT_OPTION,
auto_route: bool = _AUTO_ROUTE_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)
as_subagent = as_subagent or auto_route
_check_app_flags(app, ctx.args, as_subagent)
command_name, opencode_v2 = _opencode_command()
install_hint = _npm_install_hint("@opencode/cli" if opencode_v2 else "opencode-ai")
opencode_prompt_tokens = _OPENCODE_V2_PROMPT_TOKENS if opencode_v2 else _OPENCODE_PROMPT_TOKENS
refuse_small_context = launch and _only_resumes(ctx.args, _OPENCODE_RESUME_ARGS)
context_check = None
if max_seq_length > 0 and not as_subagent and not app:
context_check = _early_context_check(
model,
functools.partial(
_check_agent_context,
"opencode",
"OpenCode",
{"id": model or "The loaded model", "context_length": max_seq_length},
opencode_prompt_tokens,
max_tokens,
loaded = False,
model = model,
gguf_variant = gguf_variant,
ctx = ctx,
refuse = refuse_small_context,
),
)
_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,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = _ALL_REQUEST_FIELDS,
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
preload_check = _before_load(context_check),
server_options = server_options,
connections = True,
)
if app and entry.get("connection"):
_fail(
"The OpenCode app can't use a Connection model yet. Drop --app to run it in OpenCode."
)
if app:
target = _opencode_app_target(max_tokens, server_options.request_body())
return _add_app_provider(target, base, api_key, entry)
if not as_subagent:
try:
_check_agent_context(
"opencode",
"OpenCode",
entry,
opencode_prompt_tokens,
max_tokens,
refuse = refuse_small_context,
model = model,
gguf_variant = gguf_variant,
ctx = ctx,
)
except BaseException:
_shutdown_auto_served()
raise
if opencode_v2:
typer.echo(
f"OpenCode V2 provider policies must allow '{_OPENCODE_PROVIDER}'.",
err = True,
)
if as_subagent:
subagent_id = (
entry["id"]
if entry.get("connection")
else _subagent_model_id(base, key, entry, model, gguf_variant)
)
subagent_model = {**entry, "id": subagent_id}
# Stay append-safe for a bare no-launch recipe: a later `run <prompt>` would make `opencode --auto run ...` parse as the TUI, so keep yolo in the inline fallback.
route_native_auto = (
yolo
and (opencode_v2 or _opencode_supports_native_auto(command_name))
and (launch or bool(ctx.args))
)
opencode_args = list(ctx.args)
if opencode_v2:
opencode_args = _opencode_v2_standalone_args(opencode_args)
opencode_args, native_auto = _opencode_native_auto_args(
opencode_args, route_native_auto, v2 = opencode_v2
)
command = [command_name, *opencode_args]
with _session_config("opencode-subagent", launch, persist = persist) as cfg:
config_path = cfg / "opencode.json"
session_permission = write_opencode_config(
base,
key,
subagent_model,
config_path,
yolo = yolo and not native_auto,
as_subagent = True,
max_tokens = max_tokens,
request_body = server_options.request_body(),
vision = _accepts_images(base, key, entry),
)
env = {
"OPENCODE_CONFIG": str(config_path),
**_opencode_output_env(subagent_model, max_tokens),
}
inline_config = _opencode_subagent_inline_config(
config_path,
session_permission,
command = command_name,
v2 = opencode_v2,
auto_route = auto_route,
)
# A project opencode.json outranks the session file and could field-merge its own agent.unsloth over ours. Pin ours in the inline overlay so it wins.
agents = inline_config.setdefault("agent", {})
agents[_SUBAGENT_NAME] = {
"description": (
_OPENCODE_AUTO_ROUTE_DESCRIPTION if auto_route else _SUBAGENT_DESCRIPTION
),
"mode": "subagent",
"model": f"{_OPENCODE_PROVIDER}/{subagent_model['id']}",
"prompt": _SUBAGENT_INSTRUCTIONS,
}
if auto_route:
# A task subagent does not inherit the parent agent's rules, so both keep their tools.
agents[_OPENCODE_PLAN_SUBAGENT_NAME] = {
"description": _OPENCODE_AUTO_ROUTE_PLAN_DESCRIPTION,
"mode": "subagent",
"model": f"{_OPENCODE_PROVIDER}/{subagent_model['id']}",
"prompt": _SUBAGENT_PLAN_INSTRUCTIONS,
"permission": {"edit": "deny", "bash": "deny"},
}
env["OPENCODE_CONFIG_CONTENT"] = json.dumps(inline_config)
typer.echo(
"Unsloth is available as @unsloth and in /models."
+ (" OpenCode hands routine work to it on its own." if auto_route else "")
)
_run(
base,
subagent_model,
env,
command,
launch = launch,
install_hint = install_hint,
)
return
opencode_model = f"{_OPENCODE_PROVIDER}/{entry['id']}"
# The inline OPENCODE_CONFIG_CONTENT pin below selects the model, so no path passes --model: it misparses before a passthrough subcommand, lands before the `run <prompt>` drivers append to a --no-launch recipe, and OpenCode 2 rejects it on the root command, which a V2 build whose --version probe fails would get (#13747).
native_auto = False
route_native_auto = yolo and (opencode_v2 or _opencode_supports_native_auto(command_name))
if ctx.args:
opencode_args = list(ctx.args)
if opencode_v2:
opencode_args = _opencode_v2_standalone_args(opencode_args)
opencode_args, native_auto = _opencode_native_auto_args(
opencode_args, route_native_auto, v2 = opencode_v2
)
command = [command_name, *opencode_args]
elif launch:
opencode_args = _opencode_v2_standalone_args([]) if opencode_v2 else []
opencode_args, native_auto = _opencode_native_auto_args(
opencode_args,
route_native_auto,
v2 = opencode_v2,
)
command = [command_name, *opencode_args]
else:
# Append-safe base: `opencode --auto run ...` parses as the TUI with a project "run", not the run subcommand. The command is unknown here, so keep the config fallback.
opencode_args = _opencode_v2_standalone_args([]) if opencode_v2 else []
command = [command_name, *opencode_args]
# opencode keeps sessions in ~/.local/share/opencode (never relocated), so resume already survives exit; reopen the last one by passing `opencode --continue` through.
with _session_config("opencode", launch, persist = persist) as cfg:
config_path = cfg / "opencode.json"
# OPENCODE_CONFIG is an overlay, loaded between the user's global and project configs, so this adds the Unsloth provider/model for the session without changing the user's default model. The key lives in the config, not the env.
session_permission = write_opencode_config(
base,
key,
entry,
config_path,
yolo = yolo and not native_auto,
max_tokens = max_tokens,
request_body = server_options.request_body(),
vision = _accepts_images(base, key, entry),
)
# A project's own opencode.json outranks OPENCODE_CONFIG, so the session model pin would silently lose to a repo config; carry it in OPENCODE_CONFIG_CONTENT, which outranks project config, while the API key stays in the private file. Only the config fallback carries a permission: native --auto omits it (auto-approve asks, keep explicit denies) and a non-yolo session omits it too, honoring project rules. V1 filters are ordinary overlays, so scope that session to our provider; V2 turns filters into security policies where global/project rules intentionally win, so keep those policies intact and tell the user above that they must allow our provider. small_model is opencode's separate model for lightweight tasks; pin it to the session model too, or a user/project small_model on another (now filtered) provider would resolve a not-found error mid-session.
inline_config: dict = {
"model": opencode_model,
"small_model": opencode_model,
}
if not opencode_v2:
inline_config["enabled_providers"] = [_OPENCODE_PROVIDER]
inline_config["disabled_providers"] = []
if session_permission:
inline_config["permission"] = session_permission
env = {
"OPENCODE_CONFIG": str(config_path),
"OPENCODE_CONFIG_CONTENT": json.dumps(inline_config),
**_opencode_output_env(entry, max_tokens),
}
_run(base, entry, env, command, launch = launch, install_hint = install_hint)
@start_app.command("hermes", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def hermes(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
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 and not app)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = _ALL_REQUEST_FIELDS,
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
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(),
keep_mcp_servers = True,
)
env = {_HERMES_ENV_KEY: key, "HERMES_HOME": str(home)}
_run(base, entry, env, command, launch = launch, install_hint = install_hint)
@start_app.command("pi", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def pi(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
as_subagent: bool = _AS_SUBAGENT_OPTION,
):
"""Point Pi (coding agent) 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_auto_route("pi", ctx.args)
install_hint = _npm_install_hint(
"@earendil-works/pi-coding-agent",
ignore_scripts = True,
)
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,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = _ALL_REQUEST_FIELDS,
)
if server_options.request_body() and not _agent_version_at_least(
"pi", _PI_SAMPLING_PARAMS_MIN_VERSION
):
server_options = server_options._replace(carried = frozenset())
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
server_options = server_options,
)
if as_subagent:
subagent_id = _subagent_model_id(base, key, entry, model, gguf_variant)
subagent_model = {**entry, "id": subagent_id}
extension = _agent_config_path(_PI_SUBAGENT_EXTENSION, ["pi"])
with _session_config("pi-subagent", launch, persist = persist) as config:
config_path = config / "subagent.json"
write_pi_subagent_config(
base,
key,
subagent_model,
config_path,
approve = yolo,
max_tokens = max_tokens,
request_body = server_options.request_body(),
vision = _accepts_images(base, key, entry),
)
command = [
"pi",
"--extension",
extension,
*_yolo_command_flags("pi", yolo),
*ctx.args,
]
typer.echo(
"Unsloth is available as a local agent and in /model. "
"Ask Pi to spawn an Unsloth or local agent."
)
_run(
base,
subagent_model,
{"UNSLOTH_PI_SUBAGENT_CONFIG": str(config_path)},
command,
launch = launch,
install_hint = install_hint,
clear_screen = True,
)
return
# Pi defaults to the google provider, so pin our provider/model on the command line; the custom OpenAI-compatible endpoint itself is only configurable via ~/.pi/agent/models.json.
command = [
"pi",
"--provider",
_PI_PROVIDER,
"--model",
entry["id"],
*_yolo_command_flags("pi", yolo),
*ctx.args,
]
# --ignore-scripts matches Pi's documented install recipe (its README notes Pi needs no install scripts), so accepting the prompt skips dependency lifecycle scripts.
with _session_config("pi", launch, persist = persist) as home:
# getAgentDir() prefers PI_CODING_AGENT_DIR over $HOME/.pi/agent, so pin it here or an inherited value skips our provider/key. HOME stays the user's so Pi's shell commands keep git and gh.
pi_agent_dir = home / ".pi" / "agent"
write_pi_config(
base,
key,
entry,
pi_agent_dir / "models.json",
max_tokens = max_tokens,
request_body = server_options.request_body(),
vision = _accepts_images(base, key, entry),
)
write_pi_user_resources(pi_agent_dir)
env = {"PI_CODING_AGENT_DIR": str(pi_agent_dir)}
# Pi paints inline from the current cursor position (no alternate screen, no clear on first render), so give it the clean screen it assumes.
_run(
base,
entry,
env,
command,
launch = launch,
install_hint = install_hint,
clear_screen = True,
)
@start_app.command("dsh", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def dsh(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
):
"""Point DeepSeek Harness (dsh) at the running Unsloth server and start it."""
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
_reject_as_subagent("dsh", ctx.args)
install_hint = _npm_install_hint(_DSH_PACKAGE)
_require_agent_for_launch("dsh", install_hint, launch)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = _REASONING_FIELDS,
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
server_options = server_options,
)
window = entry.get("context_length") or entry.get("max_context_length")
if window and int(window) < _DSH_MIN_CONTEXT:
typer.echo(
f"Warning: {entry['id']} is loaded with {int(window):,} tokens of context, too few "
"for DeepSeek Harness: its instructions and tools take about 6,500 and it keeps "
"4,096 in reserve, so replies are cut short (at 8,192, after a single token). "
f"Load it with --max-seq-length {_DSH_MIN_CONTEXT} or more (a smaller quant if "
"that does not fit in memory) and re-run unsloth start dsh.",
err = True,
)
with _session_config("dsh", launch, persist = persist) as home:
patch = home / _DSH_PATCH_FILE
write_dsh_patch(
base, entry, patch, server_options.request_body(), _accepts_images(base, key, entry)
)
# A Windows dsh under WSL gets DSH_HOME translated through WSLENV, but not argv.
command = _dsh_command(ctx.args, _agent_config_path(patch, ["dsh"]))
env = {
_DSH_ENV_KEY: key,
"DSH_HOME": str(home),
# dsh uploads session records once a user records /feedback.
"DSH_TELEMETRY_DISABLED": "1",
"DSH_PERMISSION_MODE": (
_DSH_YOLO_PERMISSION_MODE if yolo else _DSH_SAFE_PERMISSION_MODE
),
}
_run(base, entry, env, command, launch = launch, install_hint = install_hint)
@start_app.command("vibe", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def vibe(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
serve: bool = _SERVE_OPTION,
yolo: bool = _YOLO_OPTION,
persist: bool = _PERSIST_OPTION,
):
"""Point Mistral Vibe at the running Unsloth server and start it."""
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
_reject_as_subagent("vibe", ctx.args)
install_hint = _vibe_install_hint()
_require_agent_for_launch("vibe", install_hint, launch)
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
carried = frozenset({"temperature"}),
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
server_options = server_options,
)
command = ["vibe", *_yolo_command_flags("vibe", yolo), *ctx.args]
# Vibe keeps its own home; the env layer pins provider and model above its config files.
request_body = server_options.request_body()
if "temperature" not in request_body:
# Vibe always sends a temperature that beats the model's recommendation; pass that on.
status = _inference_status(base, key, entry["id"])
recommended = (status.get("inference") or {}).get("temperature")
if recommended is not None and any(
_model_id_matches(entry["id"], status_id, allow_casefold = is_loopback_url(base))
for status_id in (status.get("active_model"), status.get("model_identifier"))
if status_id
):
request_body = {**request_body, "temperature": recommended}
env = {
_VIBE_ENV_KEY: key,
**_vibe_env(base, entry, request_body, _accepts_images(base, key, entry)),
}
_run(base, entry, env, command, launch = launch, install_hint = install_hint)
_VSCODE_LAUNCH_OPTION = typer.Option(True, "--launch/--no-launch", hidden = True)
@start_app.command("vscode", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def vscode(
ctx: typer.Context,
model: Optional[str] = _MODEL_OPTION,
api_key: Optional[str] = _KEY_OPTION,
launch: bool = _VSCODE_LAUNCH_OPTION,
gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
max_seq_length: int = _CONTEXT_OPTION,
load_in_4bit: bool = _LOAD_4BIT_OPTION,
tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
temperature: Optional[float] = _TEMPERATURE_OPTION,
top_p: Optional[float] = _TOP_P_OPTION,
top_k: Optional[int] = _TOP_K_OPTION,
min_p: Optional[float] = _MIN_P_OPTION,
repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
serve: bool = _SERVE_OPTION,
):
"""Add the model Unsloth is serving to VS Code's Copilot Chat model picker."""
model, ctx.args[:] = _consume_positional_model(model, ctx.args)
if ctx.args:
_fail("unsloth start vscode only edits VS Code's settings, so it takes no extra arguments.")
server_options = ServerOptions(
enable_tools = enable_tools,
tool_call_healing = tool_call_healing,
tool_call_nudging = tool_call_nudging,
reasoning = reasoning,
reasoning_effort = reasoning_effort,
temperature = temperature,
top_p = top_p,
top_k = top_k,
min_p = min_p,
repetition_penalty = repetition_penalty,
presence_penalty = presence_penalty,
)
base, key, entry = _connect(
api_key,
model,
_load_options(
ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
),
serve = serve,
launch = launch,
server_options = server_options,
)
tool_calling, vision, thinking = _vscode_capabilities(base, key, entry)
# Remote: the key _connect accepted. Local: never an explicit key it rejected for a fresh server.
explicit = key if not is_loopback_url(base) else api_key if key == api_key else None
_add_vscode_provider(base, explicit, entry, max_tokens, tool_calling, vision, thinking)