Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++

launch: settings, catalog (setup.py tables via strata_mcp, fitOn port), presets store, access, runner, flags, connect, harness drafts

Niko1221e61e90e5551a
diff --git a/strata_cli/cli.py b/strata_cli/cli.py
index 0ab1c1074..12c543a2f 100644
--- a/strata_cli/cli.py
+++ b/strata_cli/cli.py
@@ -449,6 +449,8 @@ def parser() -> argparse.ArgumentParser:
tune_commands.add_tune_auto(tune_sp)
tune_commands.add_presets(sp)
+ from strata_cli.launch import cmd as launch_cmd
+ launch_cmd.add_parsers(sp)
monitor_commands.add_status(sp)
monitor_commands.add_monitor(sp)
monitor_commands.add_logs(sp)
@@ -1847,6 +1849,9 @@ def _run(a: argparse.Namespace) -> int:
return _timeskip(a)
if a.command == "presets":
return tune_commands.presets_command(a)
+ if a.command in ("launch", "connect"):
+ from strata_cli.launch import cmd as launch_cmd
+ return launch_cmd.run_launch(a) if a.command == "launch" else launch_cmd.run_connect(a)
if a.command == "tune":
return _tune(a)
if a.command == "runtime":
@@ -1915,7 +1920,13 @@ def main(argv: list[str] | None = None) -> int:
except ImportError: # a thin bundle ships without strata_control
pass
ap = parser()
- a = ap.parse_args(argv)
+ a, extras = ap.parse_known_args(argv)
+ if extras:
+ if getattr(a, "command", None) in ("launch", "connect"):
+ from strata_cli.launch import cmd as launch_cmd
+ print("strata: " + launch_cmd.unknown_option_message(a.command, extras, ap), file=sys.stderr)
+ return 2
+ ap.error("unrecognized arguments: " + " ".join(extras))
if getattr(a, "json", False) and a.command not in ("status", "monitor", "logs", "connection", "config"):
if a.output == "jsonl":
return _serve_error(a, "--json is one-shot only; use --output jsonl for foreground events")
diff --git a/strata_cli/launch/__init__.py b/strata_cli/launch/__init__.py
new file mode 100644
index 000000000..75dcedf58
--- /dev/null
+++ b/strata_cli/launch/__init__.py
@@ -0,0 +1 @@
+"""`strata launch`: guided setup, serving and the monitor, in the terminal."""
diff --git a/strata_cli/launch/access.py b/strata_cli/launch/access.py
new file mode 100644
index 000000000..2832896b5
--- /dev/null
+++ b/strata_cli/launch/access.py
@@ -0,0 +1,301 @@
+"""Who can reach the server: this computer, the local network, a Cloudflare quick tunnel, Tailscale.
+
+Strata starts the server; this module only works out the addresses, checks that the helper programs exist (and says in plain
+words how to install them when they do not), and runs/stops the one helper Strata starts itself: the cloudflared quick tunnel.
+Nothing here changes a firewall, a router or a Tailscale setting. The cloudflared output is filtered: only the public address
+is ever kept or shown (a login or certificate line is dropped, never printed).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from strata_cli.launch.settings import ACCESS_KINDS, LaunchSettings
+
+TUNNEL_URL = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
+WINDOWS = os.name == "nt"
+
+
+def host_for(kind: str) -> str:
+ """The address the server listens on: loopback for this computer only, every address for the rest.
+
+ Cloudflare's tunnel connects from the same computer, so it too can stay on loopback."""
+ return "127.0.0.1" if kind in ("local", "cloudflare") else "0.0.0.0"
+
+
+def lan_ips() -> list[str]:
+ """This computer's private IPv4 addresses, the one used for the default route first."""
+ found: list[str] = []
+ try:
+ s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+ s.settimeout(0.2)
+ s.connect(("10.255.255.255", 1)) # no packet is sent; it picks the interface of the default route
+ found.append(s.getsockname()[0])
+ s.close()
+ except OSError:
+ pass
+ try:
+ import psutil
+ for infos in psutil.net_if_addrs().values():
+ for i in infos:
+ if i.family == socket.AF_INET:
+ found.append(i.address)
+ except Exception: # noqa: BLE001
+ pass
+ private = [a for a in dict.fromkeys(found) if _is_private(a) and not a.startswith("127.") and not a.startswith("169.254.")]
+ return private
+
+
+def _is_private(address: str) -> bool:
+ try:
+ a, b = (int(x) for x in address.split(".")[:2])
+ except ValueError:
+ return False
+ return a == 10 or (a == 172 and 16 <= b <= 31) or (a == 192 and b == 168) or (a == 100 and 64 <= b <= 127)
+
+
+def find_cloudflared() -> str | None:
+ found = shutil.which("cloudflared")
+ if found:
+ return found
+ for guess in ("/usr/local/bin/cloudflared", "/opt/homebrew/bin/cloudflared", r"C:\Program Files (x86)\cloudflared\cloudflared.exe",
+ r"C:\Program Files\cloudflared\cloudflared.exe"):
+ if Path(guess).is_file():
+ return guess
+ return None
+
+
+def find_tailscale() -> str | None:
+ found = shutil.which("tailscale")
+ if found:
+ return found
+ for guess in ("/usr/bin/tailscale", "/usr/local/bin/tailscale", "/Applications/Tailscale.app/Contents/MacOS/Tailscale",
+ r"C:\Program Files\Tailscale\tailscale.exe"):
+ if Path(guess).is_file():
+ return guess
+ return None
+
+
+def _run(argv: list[str], timeout: float = 8.0) -> str:
+ try:
+ r = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+ return r.stdout or ""
+ except (OSError, subprocess.SubprocessError):
+ return ""
+
+
+def tailscale_status() -> dict:
+ """{"installed", "running", "ip", "name"}: the tailnet address of this computer when Tailscale is up."""
+ exe = find_tailscale()
+ out = {"installed": bool(exe), "running": False, "ip": None, "name": None}
+ if not exe:
+ return out
+ ip = _run([exe, "ip", "-4"]).strip().splitlines()
+ if ip and re.fullmatch(r"\d+\.\d+\.\d+\.\d+", ip[0].strip()):
+ out["running"], out["ip"] = True, ip[0].strip()
+ try:
+ data = json.loads(_run([exe, "status", "--json"]) or "{}")
+ name = (data.get("Self") or {}).get("DNSName")
+ out["name"] = name.rstrip(".") if isinstance(name, str) and name else None
+ except ValueError:
+ pass
+ return out
+
+
+INSTALL_HELP = {
+ "cloudflared": {
+ "linux": "Install cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ "
+ "(on Debian/Ubuntu download the .deb and run: sudo dpkg -i cloudflared-linux-amd64.deb). No account is needed for a quick tunnel.",
+ "windows": "Install cloudflared: winget install --id Cloudflare.cloudflared (no account is needed for a quick tunnel).",
+ "darwin": "Install cloudflared: brew install cloudflared (no account is needed for a quick tunnel).",
+ },
+ "tailscale": {
+ "linux": "Install Tailscale: curl -fsSL https://tailscale.com/install.sh | sh, then run: sudo tailscale up",
+ "windows": "Install Tailscale from https://tailscale.com/download, sign in, and leave it running.",
+ "darwin": "Install Tailscale from https://tailscale.com/download, sign in, and leave it running.",
+ },
+}
+
+
+def install_help(tool: str) -> str:
+ plat = "windows" if WINDOWS else "darwin" if sys.platform == "darwin" else "linux"
+ return INSTALL_HELP[tool][plat]
+
+
+@dataclass
+class AccessOption:
+ kind: str
+ label: str
+ url: str
+ note: str
+ ready: bool # the helper it needs is there (or none is needed)
+ warn: bool = False
+
+
+def options(port: int, *, tunnel_url: str | None = None) -> list[AccessOption]:
+ """The four ways to share, with the address each would give and what is missing for it."""
+ ips = lan_ips()
+ lan = ips[0] if ips else None
+ cf = find_cloudflared()
+ ts = tailscale_status()
+ out = [AccessOption("local", "This computer only", f"http://127.0.0.1:{port}",
+ "for apps on this computer (OpenCode, Codex, Claude Code...)", True)]
+ out.append(AccessOption("lan", "My local network", f"http://{lan or '<network address>'}:{port}",
+ "other computers at home or in the office" if lan else
+ "other computers on your network; no network address was found on this computer", bool(lan), warn=not lan))
+ out.append(AccessOption("cloudflare", "Cloudflare tunnel", tunnel_url or "https://<random>.trycloudflare.com",
+ "from anywhere, no router setup · cloudflared found" if cf else "cloudflared is not installed",
+ bool(cf), warn=not cf))
+ if ts["running"]:
+ out.append(AccessOption("tailscale", "Tailscale", f"http://{ts['name'] or ts['ip']}:{port}",
+ f"your Tailscale devices · tailnet address {ts['ip']}", True))
+ else:
+ out.append(AccessOption("tailscale", "Tailscale", f"http://<tailnet address>:{port}",
+ "Tailscale is installed but not connected (run: tailscale up)" if ts["installed"] else
+ "Tailscale is not installed", False, warn=True))
+ return out
+
+
+def option_for(kind: str, port: int) -> AccessOption:
+ return next(o for o in options(port) if o.kind == kind)
+
+
+def missing_helper(kind: str) -> str | None:
+ """Plain words about what to install before this access kind works, or None when it is ready."""
+ if kind == "cloudflare" and not find_cloudflared():
+ return "cloudflared is not installed on this computer. " + install_help("cloudflared")
+ if kind == "tailscale":
+ ts = tailscale_status()
+ if not ts["installed"]:
+ return "Tailscale is not installed on this computer. " + install_help("tailscale")
+ if not ts["running"]:
+ return "Tailscale is installed but not connected. Run: tailscale up"
+ if kind == "lan" and not lan_ips():
+ return "No local network address was found on this computer. Check that it is connected to your network."
+ return None
+
+
+def urls_for(s: LaunchSettings, *, tunnel_url: str | None = None) -> list[str]:
+ """The addresses a client can use for these choices (the first is the main one)."""
+ base = [f"http://127.0.0.1:{s.port}"]
+ if s.access == "lan":
+ base += [f"http://{ip}:{s.port}" for ip in lan_ips()[:1]]
+ elif s.access == "cloudflare" and tunnel_url:
+ base = [tunnel_url] + base
+ elif s.access == "tailscale":
+ ts = tailscale_status()
+ if ts["running"]:
+ base += [f"http://{ts['name'] or ts['ip']}:{s.port}"] + ([f"http://{ts['ip']}:{s.port}"] if ts["name"] else [])
+ return base
+
+
+def new_key() -> str:
+ import secrets
+ return "sk-strata-" + secrets.token_urlsafe(24)
+
+
+def mask_key(key: str | None) -> str:
+ if not key:
+ return "off"
+ return key[:10] + "•" * 8 if len(key) > 12 else "•" * 8
+
+
+# ----------------------------------------------------------------------------------------------- the quick tunnel
+
+def _state_dir() -> Path:
+ from strata_control import paths
+ d = paths.state_base() / "launch"
+ d.mkdir(parents=True, exist_ok=True)
+ return d
+
+
+def _tunnel_state(name: str) -> Path:
+ from strata_cli.launch.settings import slug
+ return _state_dir() / f"{slug(name)}.tunnel.json"
+
+
+def start_tunnel(name: str, port: int, *, wait: float = 45.0) -> tuple[str | None, str]:
+ """Start `cloudflared tunnel --url` for the local server; returns (public url or None, plain message).
+
+ The process is detached (it keeps running after this terminal closes, like the server) and recorded with its start token so
+ `stop_tunnel` ends exactly this process and nothing else. Only the public address is read from its output."""
+ exe = find_cloudflared()
+ if not exe:
+ return None, missing_helper("cloudflare") or "cloudflared is not installed."
+ existing = tunnel_info(name)
+ if existing and existing.get("url") and existing.get("port") == port:
+ return existing["url"], "The tunnel was already running."
+ stop_tunnel(name)
+ log = _state_dir() / f"{Path(name).name}.tunnel.log"
+ argv = [exe, "tunnel", "--no-autoupdate", "--url", f"http://127.0.0.1:{port}"]
+ with open(log, "wb") as out:
+ kw = ({"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW} if WINDOWS
+ else {"start_new_session": True})
+ proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=out, stderr=subprocess.STDOUT, **kw)
+ from strata_control import procs
+ token = procs.start_token(proc.pid)
+ url = None
+ deadline = time.monotonic() + wait
+ while time.monotonic() < deadline and url is None and proc.poll() is None:
+ try:
+ m = TUNNEL_URL.search(log.read_text(encoding="utf-8", errors="replace"))
+ except OSError:
+ m = None
+ if m:
+ url = m.group(0)
+ break
+ time.sleep(0.4)
+ state = {"pid": proc.pid, "token": token, "cmd": list(procs.command_line(proc.pid) or argv), "url": url, "port": port}
+ _tunnel_state(name).write_text(json.dumps(state), encoding="utf-8")
+ try:
+ log.write_bytes(b"") # keep no log text: the address is all anyone needs from it
+ except OSError:
+ pass
+ if url is None:
+ stop_tunnel(name)
+ return None, ("The Cloudflare tunnel did not come up in time. Check your internet connection and try again; "
+ "the server itself is running and still works on this computer.")
+ return url, "The Cloudflare tunnel is up. Anyone with the address can reach the server, so keep the API key on."
+
+
+def tunnel_info(name: str) -> dict | None:
+ try:
+ state = json.loads(_tunnel_state(name).read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return None
+ from strata_control import procs
+ if isinstance(state, dict) and procs.is_same(int(state.get("pid", 0)), state.get("token") or "", state.get("cmd")):
+ return state
+ return None
+
+
+def stop_tunnel(name: str) -> bool:
+ """End this launch's tunnel, only if the recorded process is still exactly the one Strata started."""
+ state = tunnel_info(name)
+ ok = False
+ if state:
+ from strata_control import procs
+ outcome = procs.end_one({"pid": state["pid"], "token": state["token"], "cmd": state["cmd"]}, grace=5.0)
+ ok = outcome in ("ended", "gone")
+ try:
+ _tunnel_state(name).unlink()
+ except OSError:
+ pass
+ return ok
+
+
+def filter_line(line: str) -> str:
+ """For any helper output shown to a person: drop login/certificate/token lines, keep the rest."""
+ low = line.lower()
+ if any(w in low for w in ("token", "cert", "login", "secret", "authorize", "credential")):
+ return ""
+ return line
diff --git a/strata_cli/launch/catalog.py b/strata_cli/launch/catalog.py
new file mode 100644
index 000000000..a911a5652
--- /dev/null
+++ b/strata_cli/launch/catalog.py
@@ -0,0 +1,301 @@
+"""The model catalog, the computer's figures and the fit words for `strata launch`.
+
+There is ONE catalog: setup.py's MODELS / FAMILIES / CONTEXTS, which the desktop app reads through tools/strata_mcp.py
+(`Strata.model_table`, `Strata.hardware`, `Strata.recommend`; the app page's own fit arithmetic is
+apps/host/src/lib/native-fit.ts `fitOn`). This module loads that same file from the installer folder and ports `fitOn` line by
+line; it holds no table of its own. Without the installer files (a Terminal bundle made before launch existed) it says so in
+words instead of guessing.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from strata_cli.launch import settings as S
+
+
+class CatalogUnavailable(RuntimeError):
+ """The installer files (setup.py, tools/strata_mcp.py) are not there; the message is for the user."""
+
+
+# --- apps/host/src/lib/native-fit.ts, ported (same constants, same rules) ------------------------------------------------
+DENSE_GB = 5.0
+SYSTEM_ROOM_GB = 10.0
+DENSE_EXTRA_GB = 1.0
+
+
+def _round1(n: float) -> float:
+ return round(n * 10) / 10
+
+
+def memory_needed(v: dict) -> float:
+ if isinstance(v.get("memory_gb"), (int, float)):
+ return float(v["memory_gb"])
+ if v.get("mem_total") and isinstance(v.get("ram_needed_gb"), (int, float)):
+ return float(v["ram_needed_gb"])
+ return _round1(float(v.get("experts_gb") or v.get("ram_needed_gb") or 0) + DENSE_EXTRA_GB)
+
+
+def fit_on(v: dict, ram_gb: float | None, vram_gb: float | None) -> dict[str, Any]:
+ """native-fit.ts `fitOn`: where the weights go on this computer. Returns memoryGb, vramUseGb, ramUseGb, spillGb, known."""
+ memory = memory_needed(v)
+ vram = float(vram_gb or 0)
+ if not ram_gb or ram_gb <= 0:
+ return {"memoryGb": memory, "vramUseGb": 0.0, "ramUseGb": 0.0, "spillGb": 0.0, "known": False}
+ experts = max(0.0, memory - DENSE_EXTRA_GB)
+ on_gpu = max(0.0, min(experts, vram - DENSE_GB))
+ ram_room = max(0.0, float(ram_gb) - SYSTEM_ROOM_GB)
+ spill = max(0.0, experts - on_gpu - ram_room)
+ in_ram = max(0.0, experts - on_gpu - spill)
+ vram_use = min(vram, DENSE_GB + on_gpu) if vram > 0 else 0.0
+ return {"memoryGb": memory, "vramUseGb": _round1(vram_use),
+ "ramUseGb": _round1(in_ram + (DENSE_EXTRA_GB if vram <= 0 else 0)), "spillGb": _round1(spill), "known": True}
+
+
+# --- the verdict words ---------------------------------------------------------------------------------------------------
+FITS, TIGHT, NO = "fits", "tight", "no"
+
+
+def verdict(on_this_pc: str | None) -> tuple[str, str]:
+ """(category, plain words) from the catalog's own `on_this_pc` text (setup.py `--check`'s rules, through strata_mcp).
+
+ Never a block: `no` still lets the person try, and the screen says so."""
+ text = (on_this_pc or "").strip()
+ low = text.lower()
+ if not text:
+ return TIGHT, "not checked (this computer's memory could not be read)"
+ if low.startswith("does not fit"):
+ return NO, "does not fit (you can still try)"
+ if "low-ram mode" in low:
+ return FITS, "fits (slower: part of it stays in RAM or on the SSD)"
+ if "part of its experts" in low or "read from the ssd" in low:
+ base = "slow here" in low
+ return TIGHT, ("tight: part is read from the SSD, noticeably slower" if base else "fits, with part read from the SSD")
+ if low.startswith("tight"):
+ return TIGHT, "tight: close other programs"
+ if "fits" in low:
+ return FITS, "fits"
+ return TIGHT, text
+
+
+@dataclass
+class ModelRow:
+ family: str
+ family_title: str
+ model: str
+ id: str # the run config's tag (strata-<id>.json)
+ about: str
+ download_gb: float
+ need_vram_gb: float
+ need_ram_gb: float
+ spill_gb: float
+ verdict: str
+ words: str
+ experimental: bool
+ images: bool
+ installed: bool
+ recommended: bool = False
+ mem_total: bool = False
+ memory_gb: float = 0.0
+
+ @property
+ def title(self) -> str:
+ return f"{self.family_title} {self.model}"
+
+
+@dataclass
+class Computer:
+ ram_gb: float | None = None
+ gpus: list[dict] = field(default_factory=list)
+ disk_free_gb: float | None = None
+ os: str = ""
+ avx2: bool | None = None
+ raw: dict = field(default_factory=dict)
+
+ @property
+ def usable_gpus(self) -> list[dict]:
+ return [g for g in self.gpus if g.get("usable", True)]
+
+ @property
+ def main_vram_gb(self) -> float:
+ return max((float(g.get("vram_gb") or 0) for g in self.usable_gpus), default=0.0)
+
+ def line(self, data_dir: str | None = None) -> str:
+ g = self.usable_gpus
+ card = (f"{g[0].get('name', 'GPU').replace('NVIDIA GeForce ', '').replace('AMD Radeon ', '')} {g[0].get('vram_gb', 0):.0f} GB"
+ + (f" x{len(g)}" if len(g) > 1 else "")) if g else "no usable graphics card found"
+ ram = f"{self.ram_gb:.0f} GB RAM" if self.ram_gb else "RAM unknown"
+ disk = f"{self.disk_free_gb:,.0f} GB free" if self.disk_free_gb is not None else ""
+ return " · ".join(x for x in (card, ram, disk) if x)
+
+
+def installer_folder(explicit: str | os.PathLike | None = None) -> Path:
+ """Where setup.py and tools/ are: this Terminal's own folder (the bundle, or a source checkout)."""
+ if explicit:
+ return Path(explicit)
+ return Path(__file__).resolve().parents[2]
+
+
+def install_root(explicit: str | os.PathLike | None = None) -> Path:
+ """Where run configs of installed models live: STRATA_INSTALL_DIR, else beside the components folder (what the app uses)."""
+ if explicit:
+ return Path(explicit)
+ env = os.environ.get("STRATA_INSTALL_DIR")
+ if env:
+ return Path(env)
+ from strata_control import engine_component
+ return engine_component.components_dir().parent / "install"
+
+
+class Catalog:
+ """setup.py's tables through strata_mcp's `Strata` object (the app's own catalog code)."""
+
+ def __init__(self, src: str | os.PathLike | None = None, root: str | os.PathLike | None = None,
+ hardware: dict | None = None):
+ self.src = installer_folder(src)
+ self.root = install_root(root)
+ mcp = self.src / "tools" / "strata_mcp.py"
+ if not mcp.is_file() or not (self.src / "setup.py").is_file():
+ raise CatalogUnavailable(
+ "This Terminal does not carry the model list. Install it again with the one-line installer, "
+ "or run `strata launch` from a full Strata folder (the folder with setup.py).")
+ self.root.mkdir(parents=True, exist_ok=True)
+ name = "strata_mcp_for_launch"
+ mod = sys.modules.get(name)
+ if mod is None:
+ if str(self.src) not in sys.path:
+ sys.path.insert(0, str(self.src))
+ spec = importlib.util.spec_from_file_location(name, mcp)
+ mod = importlib.util.module_from_spec(spec)
+ sys.modules[name] = mod
+ real = sys.stdout
+ sys.stdout = sys.stderr # the module must not print into a screen
+ try:
+ spec.loader.exec_module(mod)
+ finally:
+ sys.stdout = real
+ self.mcp = mod
+ self.strata = mod.Strata(self.root, self.src)
+ self._hardware_override = hardware
+
+ # ---- the computer
+ def hardware(self, fresh: bool = False) -> dict:
+ if self._hardware_override is not None:
+ hw = dict(self._hardware_override)
+ hw.setdefault("disk_free_gb", self.strata.disk_free(self.strata.data_dir()))
+ return hw
+ return self.strata.hardware(fresh=fresh)
+
+ def computer(self, fresh: bool = False) -> Computer:
+ hw = self.hardware(fresh)
+ return Computer(ram_gb=hw.get("ram_gb"), gpus=list(hw.get("gpus") or []), disk_free_gb=hw.get("disk_free_gb"),
+ os=str(hw.get("os") or ""), avx2=(hw.get("cpu") or {}).get("avx2"), raw=hw)
+
+ # ---- the tables
+ def tables(self):
+ models, families, contexts, source = self.strata.tables()
+ return models, families, list(contexts), source
+
+ def contexts(self) -> list[int]:
+ return [int(c) for c in self.tables()[2]]
+
+ def recommendation(self, hw: dict | None = None) -> dict:
+ return self.strata.recommend(hw or self.hardware())
+
+ def rows(self, hw: dict | None = None) -> list[ModelRow]:
+ hw = hw or self.hardware()
+ comp = Computer(ram_gb=hw.get("ram_gb"), gpus=list(hw.get("gpus") or []))
+ vram = comp.main_vram_gb
+ rec = self.recommendation(hw)
+ out: list[ModelRow] = []
+ for fam in self.strata.model_table(hw):
+ for size in fam["sizes"]:
+ f = fit_on(size, hw.get("ram_gb"), vram)
+ cat, words = verdict(size.get("on_this_pc"))
+ out.append(ModelRow(
+ family=fam["family"], family_title=fam["title"], model=size["model"], id=size["id"],
+ about=size["about"], download_gb=float(size["download_gb"]), need_vram_gb=f["vramUseGb"],
+ need_ram_gb=f["ramUseGb"], spill_gb=f["spillGb"], verdict=cat, words=words,
+ experimental=bool(size.get("experimental") or fam.get("experimental")), images=bool(size.get("images")),
+ installed=bool(size.get("installed")), mem_total=bool(size.get("mem_total")),
+ memory_gb=float(size.get("memory_gb") or 0),
+ recommended=(rec.get("family") == fam["family"] and rec.get("model") == size["model"])))
+ return out
+
+ def resolve(self, model: str, family: str | None = None) -> tuple[str, str]:
+ """`iq3_xxs` or `IQ3_XXS` (and an optional family) -> (family, model); raises ValueError with the closest match."""
+ models, families, _ctx, _src = self.tables()
+ names = list(models)
+ match = next((n for n in names if n.lower() == model.lower()), None)
+ if match is None:
+ near = S.closest(model, names)
+ raise ValueError(f"There is no model called '{model}'." + (f" Did you mean '{near}'?" if near else "")
+ + " Models: " + ", ".join(names) + ".")
+ if family is not None and family not in families:
+ near = S.closest(family, list(families))
+ raise ValueError(f"There is no model family called '{family}'." + (f" Did you mean '{near}'?" if near else "")
+ + " Families: " + ", ".join(families) + ".")
+ offered = [f for f in families if match in self.strata.sizes_of(models, f)]
+ if family is not None:
+ if family not in offered:
+ raise ValueError(f"{families[family]['title']} has no size {match}. It offers: "
+ + ", ".join(self.strata.sizes_of(models, family)) + ".")
+ return family, match
+ if not offered:
+ raise ValueError(f"{match} is not offered by any model family here.")
+ return ("qwen" if "qwen" in offered else offered[0]), match
+
+ def tag_of(self, family: str, model: str) -> str:
+ _m, families, _c, _s = self.tables()
+ return (families[family].get("tag", "") + model).lower()
+
+ def kv_gb(self, tokens: int, kv: str = "int8") -> float:
+ """The conversation memory for this many tokens, in GB (setup.py's UD_FIT_KV_BYTES: 13 attention layers)."""
+ mod = self.strata.setup_module()
+ table = getattr(mod, "UD_FIT_KV_BYTES", None) or {"fp16": 2112, "int8": 1056, "q4_0": 576, "k8v4": 816}
+ return tokens * 13 * table.get(kv, 1056) / 1e9
+
+ def max_context(self, family: str, model: str, hw: dict | None = None) -> int | None:
+ """The recommended context for this computer and model (setup.py: VRAM rule, then the RAM rule)."""
+ hw = hw or self.hardware()
+ usable = [g for g in hw.get("gpus") or [] if g.get("usable", True)]
+ vram = max((float(g.get("vram_gb") or 0) for g in usable), default=12.0)
+ rec = 32768 if vram < 14 else 65536 if vram < 20 else 131072
+ mod = self.strata.setup_module()
+ models = self.tables()[0]
+ if mod is not None and models[model].get("budget"):
+ try:
+ if mod.unsloth_budget(model, hw.get("ram_gb") or 0.0):
+ rec = 8192 if vram < 14 else 32768
+ except Exception: # noqa: BLE001
+ pass
+ if mod is not None and hasattr(mod, "ram_ctx") and hw.get("ram_gb"):
+ try:
+ rec = min(rec, int(mod.ram_ctx(model, hw["ram_gb"], False)))
+ except Exception: # noqa: BLE001
+ pass
+ return rec
+
+ # ---- installed models
+ def installed_configs(self) -> list[dict]:
+ out = []
+ for path in self.strata.configs():
+ d = self.strata.describe_config(path)
+ d["path"] = str(path)
+ out.append(d)
+ return out
+
+ def installed_config(self, tag: str) -> Path | None:
+ p = self.root / f"strata-{tag.lower()}.json"
+ return p if p.is_file() else None
+
+ def data_dir(self) -> Path:
+ return self.strata.data_dir()
+
+ def disk_free(self, path: str | os.PathLike) -> float | None:
+ return self.strata.disk_free(Path(path))
diff --git a/strata_cli/launch/cmd.py b/strata_cli/launch/cmd.py
new file mode 100644
index 000000000..f6b70158e
--- /dev/null
+++ b/strata_cli/launch/cmd.py
@@ -0,0 +1,551 @@
+"""The `strata launch` and `strata connect` commands: the flags, the plain-text (no TUI) run, and the hand-over to the TUI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import threading
+from pathlib import Path
+from typing import Any
+
+from strata_cli.launch import settings as S
+
+EXAMPLES = """\
+examples:
+ strata launch open the guided screens (saved presets, then set up from the beginning)
+ strata launch --preset "IQ3_XXS 128K" start a saved preset (opens the monitor)
+ strata launch --model iq3_xxs --context 128k --parallel 4 --vision off --tune quick \\
+ --access lan --port 8080 --save-preset "Office" --no-tui
+ set everything on the command line, serve, print the address
+ strata launch --model-path /data/models/IQ3_XXS --no-tui
+ use model files you already have (a folder or one .gguf)
+ strata launch --preset Office --set prefill=65536 --set STRATA_PIN_BY_NEED=1 --no-tui
+ change one advanced setting for this start
+ strata launch --plan --model q2_0 show what would happen, change nothing
+ strata launch --list-presets | --delete-preset NAME | --status | --stop [--preset NAME]
+ strata connect list the apps Strata can be connected to
+ strata connect opencode --write write OpenCode's config for the running server (keeps a backup)
+"""
+
+
+def _choice(label: str, options: tuple[str, ...]):
+ def convert(value: str) -> str:
+ v = str(value).strip().lower()
+ if v in options:
+ return v
+ near = S.closest(v, list(options))
+ raise argparse.ArgumentTypeError(
+ f"'{value}' is not {label}." + (f" Did you mean '{near}'?" if near else "") + f" Choose one of: {', '.join(options)}.")
+ return convert
+
+
+def _context(value: str) -> int:
+ try:
+ return S.parse_context(value)
+ except ValueError as e:
+ raise argparse.ArgumentTypeError(str(e)) from None
+
+
+def _port(value: str) -> int:
+ try:
+ p = int(value)
+ except ValueError:
+ raise argparse.ArgumentTypeError(f"'{value}' is not a port number. Use a number from 1 to 65535, for example 8080.") from None
+ if not 1 <= p <= 65535:
+ raise argparse.ArgumentTypeError(f"port {p} does not exist. Use a number from 1 to 65535, for example 8080.")
+ return p
+
+
+def _parallel(value: str) -> int:
+ try:
+ p = int(value)
+ except ValueError:
+ raise argparse.ArgumentTypeError(f"'{value}' is not a number of requests. Use 1 to 8, or leave it out to fit your card.") from None
+ if not 1 <= p <= 8:
+ raise argparse.ArgumentTypeError(f"{p} requests at once is outside what the engine can do. Use 1 to 8.")
+ return p
+
+
+def add_parsers(sp: argparse._SubParsersAction) -> list[argparse.ArgumentParser]:
+ p = sp.add_parser(
+ "launch", help="guided setup, serve and monitor (the screens), or the same with flags", epilog=EXAMPLES,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ description="Set up a model, tune it, start serving and watch it, in one place. With no flags it opens the guided screens: "
+ "start from a saved preset or set up from the beginning, one decision per screen. With flags it does the same "
+ "without asking, and opens the monitor (or, with --no-tui, prints the address and returns). "
+ "Presets are shared with the Strata app's profiles and tuning presets.")
+ g = p.add_argument_group("what to run")
+ g.add_argument("--preset", metavar="NAME", help="start a saved preset (other flags change it for this start)")
+ g.add_argument("--model", metavar="NAME", help="the model size, e.g. iq3_xxs, q2_0, ud-q4_k_xl (any case)")
+ g.add_argument("--family", metavar="NAME", help="the model family when a size is offered by several (qwen, swift, coder, ...)")
+ g.add_argument("--model-path", metavar="PATH", help="use model files you already have: a folder of shards or one .gguf file")
+ g.add_argument("--data-dir", metavar="DIR", help="where downloaded model files are stored (default: Strata's data folder)")
+ g.add_argument("--context", type=_context, metavar="SIZE", help="how much text it remembers at once: 32k, 64k, 128k, 256k or a number of tokens")
+ g.add_argument("--kv", type=_choice("a memory format", S.KV_MODES), metavar="FORMAT", help="conversation memory format: int8 (default), q4_0 (half the memory), k8v4, fp16")
+ g.add_argument("--vision", type=_choice("a picture setting", S.VISION_MODES), metavar="off|on|gpu|cpu",
+ help="let the model read pictures (default off)")
+ g.add_argument("--parallel", type=_parallel, metavar="N", help="requests answered at the same time, 1 to 8 (default: fit to your graphics card)")
+ g.add_argument("--gpu", metavar="LIST", help="graphics card numbers to use, e.g. 0 or 0,1 (default: the engine's choice)")
+ g.add_argument("--tune", type=_choice("a tuning mode", S.TUNE_MODES), metavar="quick|thorough|skip", help="find the fastest settings first (default: skip)")
+ g.add_argument("--tune-allow-small", action="store_true", help="let the tuner also try settings that can change answers very slightly")
+ g.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+ help="an advanced engine setting or STRATA_* variable, e.g. prefill=65536 (repeat); unknown names get a warning, not a refusal")
+ a = p.add_argument_group("who can use it")
+ a.add_argument("--access", type=_choice("a way to share Strata", S.ACCESS_KINDS), metavar="local|lan|cloudflare|tailscale",
+ help="local: this computer only; lan: your network; cloudflare: a quick tunnel; tailscale: your tailnet")
+ a.add_argument("--port", type=_port, metavar="N", help=f"port (default {S.DEFAULT_PORT})")
+ a.add_argument("--api-key", metavar="KEY", help="the key clients must send (made for you when you share beyond this computer)")
+ a.add_argument("--api-key-env", metavar="NAME", help="read the key from this environment variable")
+ a.add_argument("--new-key", action="store_true", help="make a new API key")
+ o = p.add_argument_group("running")
+ o.add_argument("--save-preset", metavar="NAME", help="save these choices under this name")
+ o.add_argument("--no-tui", action="store_true", help="no screens: serve, print the address and return")
+ o.add_argument("--plan", action="store_true", help="show what would happen and exit; nothing is changed")
+ o.add_argument("--feed", metavar="URL|DIR", help="where the signed update feed (engine downloads) is; default: STRATA_UPDATE_FEED or the project's")
+ o.add_argument("--output", choices=("human", "json"), default="human")
+ m = p.add_argument_group("manage")
+ m.add_argument("--list-presets", action="store_true", help="list saved presets")
+ m.add_argument("--delete-preset", metavar="NAME", help="delete a saved preset")
+ m.add_argument("--status", action="store_true", help="show what this command is serving now")
+ m.add_argument("--stop", action="store_true", help="stop what this command started (with --preset NAME: that one)")
+ m.add_argument("--show-key", action="store_true", help="print the API key of --preset NAME (or of the running launch)")
+
+ c = sp.add_parser(
+ "connect", help="print (or write) the setup for an app that uses the running server", epilog=EXAMPLES,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ description="Shows the settings file and environment an app needs to talk to the Strata server that `strata launch` started. "
+ "Without a name it lists the apps. With --write it writes the file after asking, keeping a backup of any file it replaces.")
+ c.add_argument("harness", nargs="?", help="opencode, codex, claude-code, omp, pi, hermes, openclaw, deepseek-harness")
+ c.add_argument("--url", metavar="URL", help="the server address (default: the running launch, else http://127.0.0.1:8080)")
+ c.add_argument("--key", metavar="KEY", help="the API key (default: the running launch's)")
+ c.add_argument("--key-env", metavar="NAME", help="read the key from this environment variable")
+ c.add_argument("--model", metavar="NAME", help="the model name the server reports (default: the running launch's)")
+ c.add_argument("--preset", metavar="NAME", help="take the address, key and model from this saved preset")
+ c.add_argument("--write", action="store_true", help="write the file(s), after asking; a replaced file is backed up first")
+ c.add_argument("--yes", action="store_true", help="do not ask before --write")
+ c.add_argument("--show-key", action="store_true", help="print the real key instead of a masked one")
+ c.add_argument("--output", choices=("human", "json"), default="human")
+ return [p, c]
+
+
+def unknown_option_message(command: str, extras: list[str], parser: argparse.ArgumentParser) -> str:
+ """A plain sentence for flags the parser did not know, with the closest real one."""
+ sub = None
+ for action in parser._actions: # noqa: SLF001
+ if isinstance(action, argparse._SubParsersAction): # noqa: SLF001
+ sub = action.choices.get(command)
+ known = sorted({o for act in (sub._actions if sub else []) for o in act.option_strings if o.startswith("--")}) # noqa: SLF001
+ lines = []
+ for bad in extras:
+ if not bad.startswith("-"):
+ lines.append(f"'{bad}' was not expected here.")
+ continue
+ name = bad.split("=", 1)[0]
+ near = S.closest(name, known)
+ lines.append(f"'{name}' is not a strata {command} option." + (f" Did you mean '{near}'?" if near else ""))
+ return " ".join(lines) + f" See: strata {command} --help"
+
+
+# ------------------------------------------------------------------------------------------------ settings from flags
+
+def _gpus(text: str | None) -> list[int] | None:
+ if not text:
+ return None
+ try:
+ return [int(x) for x in str(text).replace(" ", "").split(",") if x != ""]
+ except ValueError:
+ raise ValueError(f"'{text}' is not a list of graphics card numbers. Use 0 or 0,1.") from None
+
+
+def settings_from_args(a: argparse.Namespace, catalog=None) -> tuple[S.LaunchSettings, list[str]]:
+ """The preset (if named) with the flags on top; model names resolved against the catalog. Returns (settings, warnings)."""
+ from strata_cli.launch import store
+ notices: list[str] = []
+ s = store.load(a.preset) if a.preset else S.LaunchSettings()
+ if a.preset:
+ s.name = s.name or a.preset
+ if a.model_path:
+ s.model_path = str(Path(a.model_path).expanduser())
+ if not a.model:
+ s.family = s.model = None
+ if a.model:
+ if catalog is None:
+ raise ValueError("The model list is not available in this Terminal; run it from the full Terminal install.")
+ s.family, s.model = catalog.resolve(a.model, a.family)
+ if not a.model_path:
+ s.model_path = None
+ elif a.family and s.model:
+ s.family = a.family
+ if a.data_dir:
+ s.data_dir = a.data_dir
+ if a.context:
+ s.context = a.context
+ if a.kv:
+ s.kv = a.kv
+ if a.vision:
+ s.vision = a.vision
+ if a.parallel:
+ s.parallel = a.parallel
+ if a.gpu:
+ s.gpus = _gpus(a.gpu)
+ if a.tune:
+ s.tune = a.tune
+ if a.tune_allow_small:
+ s.tune_allow_small = True
+ if a.access:
+ s.access = a.access
+ if a.port:
+ s.port = a.port
+ if a.api_key:
+ s.api_key = a.api_key
+ if a.api_key_env:
+ val = os.environ.get(a.api_key_env)
+ if not val:
+ raise ValueError(f"The environment variable {a.api_key_env} is empty or not set.")
+ s.api_key = val
+ if a.set:
+ s.extra = {**s.extra, **S.settings_from_pairs(a.set)}
+ if a.save_preset:
+ s.name = a.save_preset
+ return s, notices
+
+
+def apply_defaults(s: S.LaunchSettings, catalog) -> tuple[S.LaunchSettings, list[S.Notice]]:
+ """Fill what was left open with the recommendation for this computer, and collect warnings (never errors for a bad fit)."""
+ notices: list[S.Notice] = []
+ comp = catalog.computer()
+ hw = comp.raw
+ if not (s.family and s.model) and not s.model_path:
+ rec = catalog.recommendation(hw)
+ if rec.get("model"):
+ s.family, s.model = rec["family"], rec["model"]
+ notices.append(S.Notice("warn", f"No model was named, so Strata picked {rec['title']} for this computer ({rec['why']}).", ""))
+ else:
+ notices.append(S.Notice("error", "No model fits this computer by Strata's rules, and none was chosen.",
+ "Name one with --model (strata launch --help lists them); a bigger one will run slowly."))
+ if s.family and s.model:
+ if s.context is None:
+ s.context = catalog.max_context(s.family, s.model, hw)
+ rows = [r for r in catalog.rows(hw) if r.family == s.family and r.model == s.model]
+ if rows:
+ r = rows[0]
+ if r.verdict == "no":
+ notices.append(S.Notice("warn", f"{r.title} does not fit this computer ({r.words}).", "It can still start; expect it to be slow or to run out of memory."))
+ elif r.verdict == "tight":
+ notices.append(S.Notice("warn", f"{r.title} is a tight fit: {r.words}.", "Close other programs before you start."))
+ if s.vision != "off" and not r.images:
+ notices.append(S.Notice("warn", f"{r.title} cannot read pictures yet, so pictures are off.", ""))
+ s.vision = "off"
+ notices += S.check_context(s, max_fit_tokens=None)
+ if s.access != "local" and not s.api_key:
+ from strata_cli.launch import access
+ s.api_key = access.new_key()
+ notices.append(S.Notice("warn", "A new API key was made, because the server is shared beyond this computer.",
+ "It is saved with the preset; show it with: strata launch --show-key"))
+ notices += S.check_access(s)
+ vram = comp.main_vram_gb or None
+ notices += S.check_parallel(s, vram_gb=vram)
+ return s, notices
+
+
+# ------------------------------------------------------------------------------------------------ plain-text run
+
+def _say(line: str = "") -> None:
+ sys.stdout.write(line + "\n")
+ sys.stdout.flush()
+
+
+def _printer(quiet: bool = False):
+ """An emit callback that prints readable lines: new text once, progress in steps of 10% when not on a terminal."""
+ state = {"last": None, "pct": -10, "stage": None}
+ isatty = sys.stdout.isatty()
+
+ def emit(ev) -> None:
+ if quiet:
+ return
+ text = ev.text
+ if ev.pct is not None and ev.stage in ("model", "engine", "tune"):
+ if isatty:
+ sys.stdout.write(f"\r {text} {ev.pct:.0f}% " + ("\n" if ev.pct >= 100 else ""))
+ sys.stdout.flush()
+ return
+ if ev.pct < 100 and ev.pct < state["pct"] + 10 and state["stage"] == ev.stage:
+ return
+ state["pct"] = ev.pct
+ if ev.stage != state["stage"] or text != state["last"]:
+ marker = {"warn": "[!] ", "error": "[X] "}.get(ev.level, " ")
+ _say(f"{marker}{text}")
+ state["last"], state["stage"] = text, ev.stage
+ return emit
+
+
+def _stop_all(name: str | None) -> int:
+ from strata_cli.launch import access, store
+ from strata_control import profiles, runtime
+ targets = [name] if name else [p["id"] for p in profiles.list_profiles() if p["id"].startswith("launch-")]
+ stopped = 0
+ for prof in targets:
+ prof = prof if prof.startswith("launch-") else "launch-" + S.slug(prof)
+ st = runtime.status(prof)
+ if st.get("state") in ("ready", "starting", "failed", "stale"):
+ r = runtime.stop(prof, timeout=180)
+ _say(f"Stopped {prof[7:]}." if r.get("ok") else f"Could not stop {prof[7:]}: {r.get('error') or r.get('state')}.")
+ stopped += 1 if r.get("ok") else 0
+ access.stop_tunnel(prof)
+ if not stopped and not targets:
+ _say("Nothing from `strata launch` is running.")
+ elif not stopped:
+ _say("Nothing from `strata launch` is running.")
+ return 0
+
+
+def running_launches() -> list[dict]:
+ """Launch profiles whose server is up now: [{name, profile, url, state}]."""
+ from strata_control import profiles, runtime
+ out = []
+ try:
+ listing = profiles.list_profiles()
+ except Exception: # noqa: BLE001
+ return out
+ for p in listing:
+ if not p["id"].startswith("launch-"):
+ continue
+ try:
+ st = runtime.status(p["id"])
+ except Exception: # noqa: BLE001
+ continue
+ if st.get("state") not in ("ready", "starting"):
+ continue
+ try:
+ prof, _rev = profiles.load(p["id"])
+ ov = prof.get("overrides") or {}
+ except Exception: # noqa: BLE001
+ ov = {}
+ port = ov.get("port", S.DEFAULT_PORT)
+ out.append({"name": p["id"][7:], "profile": p["id"], "state": st.get("state"), "port": port,
+ "url": f"http://127.0.0.1:{port}", "host": ov.get("host", "127.0.0.1"), "config": prof.get("source_config")})
+ return out
+
+
+def launch_info(name: str | None = None) -> dict | None:
+ """Address, key and model name of a launch that is running (or the named preset), for `connect` and the monitor's Connect view."""
+ from strata_cli.launch import store
+ running = running_launches()
+ pick = None
+ if name:
+ pick = next((r for r in running if r["name"] == S.slug(name)), None)
+ elif running:
+ pick = running[0]
+ cfg = {}
+ cfg_path = (pick or {}).get("config")
+ if cfg_path:
+ try:
+ cfg = json.loads(Path(cfg_path).read_text(encoding="utf-8-sig"))
+ except (OSError, ValueError):
+ cfg = {}
+ preset = store.load(name, missing_ok=True) if name else None
+ if pick is None and preset is None:
+ return None
+ port = (pick or {}).get("port") or (preset.port if preset else S.DEFAULT_PORT)
+ return {"url": (pick or {}).get("url") or f"http://127.0.0.1:{port}", "key": cfg.get("api_key") or (preset.api_key if preset else None),
+ "model": cfg.get("model_name") or "strata", "running": bool(pick), "name": (pick or {}).get("name") or (preset.name if preset else None),
+ "port": port, "access": preset.access if preset else None}
+
+
+def run_launch(a: argparse.Namespace) -> int:
+ from strata_cli.launch import store
+ from strata_cli.launch.catalog import Catalog, CatalogUnavailable
+ from strata_cli.launch.runner import LaunchError, Runner
+ machine = a.output == "json"
+
+ def fail(text: str, code: int = 2) -> int:
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": False, "error": {"code": code, "message": text}}))
+ else:
+ print(f"strata: {text}", file=sys.stderr)
+ return code
+
+ try:
+ if a.list_presets:
+ items = store.list_presets()
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, "presets": [i.to_dict(with_key=False) for i in items]}))
+ elif not items:
+ _say("No saved presets yet. Save one with: strata launch --model ... --save-preset NAME")
+ else:
+ for i in items:
+ sm = store.summary(i)
+ _say(f"{i.name:<28} {sm['model']:<14} {S.context_label(i.context):<6} "
+ f"{(str(i.parallel) + ' request' + ('s' if i.parallel != 1 else '')) if i.parallel else 'fit to card':<14} "
+ f"{('tuned ' + (i.tuned_at or '')) if i.tuned_preset else 'not tuned':<16} {i.last_used or ''}")
+ return 0
+ if a.delete_preset:
+ store.delete(a.delete_preset)
+ _say(f"Deleted the preset '{a.delete_preset}'. Models and tuning results were not touched.")
+ return 0
+ if a.stop:
+ return _stop_all("launch-" + S.slug(a.preset) if a.preset else None)
+ if a.status:
+ rows = running_launches()
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, "running": rows}))
+ elif not rows:
+ _say("Nothing from `strata launch` is running.")
+ for r in rows:
+ _say(f"{r['name']}: {r['state']} at {r['url']}")
+ return 0
+ if a.show_key:
+ info = launch_info(a.preset)
+ if not info or not info.get("key"):
+ return fail("There is no API key for that launch." + ("" if a.preset else " Name a preset with --preset NAME."), 5)
+ _say(info["key"])
+ return 0
+
+ try:
+ catalog = Catalog()
+ except CatalogUnavailable as e:
+ catalog = None
+ if a.model or a.model_path:
+ return fail(str(e), 5)
+ s, notices = settings_from_args(a, catalog)
+ have_choices = bool(a.preset or a.model or a.model_path or a.context or a.vision or a.parallel or a.access or a.tune)
+ interactive = sys.stdin.isatty() and sys.stdout.isatty() and not a.no_tui and not machine and not a.plan
+ if interactive and not have_choices:
+ from strata_cli.launch import app
+ return app.run_tui(None, catalog=catalog, feed=a.feed)
+ if catalog is None:
+ return fail("This Terminal does not carry the model list. Install it again with the one-line installer.", 5)
+ s, notes = apply_defaults(s, catalog)
+ errors = [n for n in notes if n.level == "error"]
+ if errors:
+ return fail(errors[0].line(), 2)
+ if a.new_key:
+ from strata_cli.launch import access
+ s.api_key = access.new_key()
+ if not s.name:
+ s.name = f"{s.model or 'model'} {S.context_label(s.context)}"
+ runner = Runner(s, catalog=catalog, emit=_printer(machine), feed=a.feed)
+ if a.plan:
+ plan = runner.plan()
+ plan["warnings"] = [n.line() for n in notes]
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, "plan": plan}))
+ else:
+ _say(f"Plan for '{s.name}':")
+ _say(f" model {s.family} {s.model}" if s.model else f" model your files at {s.model_path}")
+ _say(f" context {S.context_label(s.context)} pictures {s.vision} parallel {s.parallel or 'fit to your card'}")
+ _say(f" tuning {s.tune} access {S.ACCESS_WORDS[s.access]}, port {s.port}"
+ + (" API key on" if s.api_key else ""))
+ for n in notes:
+ _say(f" [!] {n.line()}")
+ _say(f" same as {S.flags_text(s)}")
+ _say("Nothing was changed.")
+ return 0
+ for n in notes:
+ if not machine:
+ _say(f"[!] {n.line()}")
+ if interactive and have_choices:
+ from strata_cli.launch import app
+ return app.run_tui(s, catalog=catalog, feed=a.feed, auto_run=True, save=bool(a.save_preset))
+ try:
+ result = runner.run()
+ except LaunchError as e:
+ return fail(f"{e.text}" + (f" {e.next}" if e.next else ""), e.code)
+ if a.save_preset or a.preset:
+ saved = store.save(s, s.name)
+ store.touch_used(saved.name)
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, "name": s.name, "profile": result.profile, "urls": result.urls,
+ "api_key": "set" if result.key else None, "tuned": result.tune_word,
+ "notices": result.notices + [n.line() for n in notes]}))
+ return 0
+ _say("")
+ _say("Strata is serving.")
+ for i, u in enumerate(result.urls):
+ _say(f" {'This computer' if i == 0 and '127.0.0.1' in u else 'Address':<14} {u}/v1")
+ if result.key:
+ from strata_cli.launch import access
+ _say(f" {'API key':<14} {access.mask_key(result.key)} (show it: strata launch --show-key --preset \"{s.name}\")")
+ for n in result.notices:
+ _say(f"[!] {n}")
+ _say(f" Watch it: strata monitor --url {result.urls[0] if result.urls else ''}")
+ _say(f" Connect an app: strata connect opencode Stop: strata launch --stop --preset \"{s.name}\"")
+ return 0
+ except store.PresetError as e:
+ return fail(str(e), 2)
+ except ValueError as e:
+ return fail(str(e), 2)
+ except KeyboardInterrupt:
+ return fail("Stopped.", 130)
+
+
+# ------------------------------------------------------------------------------------------------ connect
+
+def run_connect(a: argparse.Namespace) -> int:
+ from strata_cli.launch import access, harness
+ machine = a.output == "json"
+ if not a.harness:
+ rows = [{"id": h.id, "title": h.title, "speaks": h.speaks, "status": h.status} for h in harness.HARNESSES]
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, "harnesses": rows}))
+ else:
+ _say(f"{'App':<20}{'Works with':<22}Status")
+ for r in rows:
+ _say(f"{r['id']:<20}{r['speaks']:<22}{r['status']}")
+ _say("")
+ _say("Show one: strata connect opencode Write it for you: strata connect opencode --write")
+ return 0
+ h = harness.find(a.harness)
+ if h is None:
+ near = harness.closest_name(a.harness)
+ msg = f"There is no app called '{a.harness}'." + (f" Did you mean '{near}'?" if near else "") + \
+ " Apps: " + ", ".join(x.id for x in harness.HARNESSES) + "."
+ print(f"strata: {msg}", file=sys.stderr)
+ return 2
+ info = launch_info(a.preset) or {}
+ url = a.url or info.get("url") or f"http://127.0.0.1:{S.DEFAULT_PORT}"
+ key = a.key or (os.environ.get(a.key_env) if a.key_env else None) or info.get("key") or ""
+ model = a.model or info.get("model") or "strata"
+ out = harness.render(h, url=url, key=key or "<your API key>", model=model)
+ shown_key = key if a.show_key else None
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, **{k: (harness.mask(json.dumps(v), key) if False else v) for k, v in out.items()}}))
+ return 0
+ _say(f"{h.title} ({h.speaks}; {h.status})")
+ if not info.get("running") and not a.url:
+ _say("[!] No running Strata server was found, so this uses the default address. Start one with: strata launch")
+ if not h.built_in and not h.tested:
+ _say("[!] This setup has not been tested with this app yet; treat it as a starting point.")
+ for n in h.notes:
+ _say(f" {n}")
+ for f in out["files"]:
+ _say("")
+ _say(f"File: {f['path']}" + (" (merged into an existing file)" if f["merge"] else ""))
+ for line in (f["text"] if shown_key else harness.mask(f["text"], key)).splitlines():
+ _say(" " + line)
+ if out["env"]:
+ _say("")
+ _say("Environment:" if True else "")
+ for k, v in out["env"].items():
+ _say(f" {k}={v if shown_key else harness.mask(v, key)}" if os.name != "nt" else f" set {k}={v if shown_key else harness.mask(v, key)}")
+ if h.install:
+ _say("")
+ _say(f"Install the app (if you have not): {h.install}")
+ if a.write:
+ if not out["files"]:
+ _say("Nothing to write for this app.")
+ return 0
+ if not a.yes:
+ if not sys.stdin.isatty():
+ print("strata: --write asks first; run it in a terminal or add --yes.", file=sys.stderr)
+ return 2
+ ans = input("\nWrite these files now? A file that exists is copied to a backup first. [y/N] ").strip().lower()
+ if ans not in ("y", "yes"):
+ _say("Nothing was written.")
+ return 0
+ for f in out["files"]:
+ r = harness.write_file(f)
+ _say(f"{r['action'].capitalize()} {r['path']}" + (f" (backup: {r['backup']})" if r["backup"] else ""))
+ return 0
diff --git a/strata_cli/launch/harness.py b/strata_cli/launch/harness.py
new file mode 100644
index 000000000..2966b7d69
--- /dev/null
+++ b/strata_cli/launch/harness.py
@@ -0,0 +1,207 @@
+"""`strata connect <harness>`: the setup text for an app that talks to a running Strata server.
+
+Each harness is one entry of `HARNESSES` below: what it speaks, where its config file lives, the text to put there, the
+environment variables, and whether that config has been **tested** (phaseA-tests/split/harness-configs/<harness>.md, section 4 of
+TUI-LAUNCH-SPEC.md: one prompt with the answer checked and one tool call with its arguments checked, at 32K).
+
+TODO table (an entry says `tested=False` until its tested config replaces the draft below; the draft comes from the app's public
+documentation and is labelled "not tested yet" on screen):
+
+ opencode codex claude-code omp pi hermes openclaw -> tested configs from the section-4 worker
+ deepseek-harness -> built into the Strata app, nothing to write
+
+Placeholders in the templates: {url} (server root, no /v1), {key}, {model}, {port}.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class FileSpec:
+ path: str # may start with ~ ; {home} {appdata} are not needed, ~ is expanded
+ kind: str # json | toml | yaml | text | env
+ content: str # template
+ merge: bool = False # json only: merge into an existing file instead of replacing it
+
+
+@dataclass
+class Harness:
+ id: str
+ title: str
+ speaks: str # "chat + tools", "responses + tools", ...
+ files: list[FileSpec] = field(default_factory=list)
+ env: dict[str, str] = field(default_factory=dict)
+ notes: list[str] = field(default_factory=list)
+ tested: bool = False
+ built_in: bool = False
+ aliases: tuple[str, ...] = ()
+ install: str = ""
+
+ @property
+ def status(self) -> str:
+ return "built into the Strata app" if self.built_in else ("tested" if self.tested else "not tested yet")
+
+
+def _j(obj) -> str:
+ return json.dumps(obj, indent=2)
+
+
+# --- drafts: replaced by the tested files of harness-configs/ (see the TODO table above) --------------------------------------
+HARNESSES: list[Harness] = [
+ Harness("opencode", "OpenCode", "chat + tools",
+ files=[FileSpec("~/.config/opencode/opencode.json", "json", _j({
+ "$schema": "https://opencode.ai/config.json",
+ "provider": {"strata": {"npm": "@ai-sdk/openai-compatible", "name": "Strata",
+ "options": {"baseURL": "{url}/v1", "apiKey": "{key}"},
+ "models": {"{model}": {"name": "Strata ({model})"}}}},
+ "model": "strata/{model}"}), merge=True)],
+ install="npm i -g opencode-ai"),
+ Harness("codex", "Codex CLI", "responses + tools",
+ files=[FileSpec("~/.codex/config.toml", "toml",
+ 'model = "{model}"\nmodel_provider = "strata"\n\n[model_providers.strata]\nname = "Strata"\n'
+ 'base_url = "{url}/v1"\nenv_key = "STRATA_API_KEY"\nwire_api = "responses"\n')],
+ env={"STRATA_API_KEY": "{key}"}, install="npm i -g @openai/codex"),
+ Harness("claude-code", "Claude Code", "messages + tools",
+ files=[FileSpec("~/.claude/settings.json", "json", _j({"env": {
+ "ANTHROPIC_BASE_URL": "{url}", "ANTHROPIC_AUTH_TOKEN": "{key}", "ANTHROPIC_MODEL": "{model}",
+ "ANTHROPIC_SMALL_FAST_MODEL": "{model}", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"}}), merge=True)],
+ env={"ANTHROPIC_BASE_URL": "{url}", "ANTHROPIC_AUTH_TOKEN": "{key}", "ANTHROPIC_MODEL": "{model}"},
+ notes=["No Anthropic login is needed: the server answers with your local model."],
+ aliases=("claude",), install="npm i -g @anthropic-ai/claude-code"),
+ Harness("omp", "oh-my-pi (omp)", "chat + tools",
+ files=[FileSpec("~/.omp/agent/models.yml", "yaml",
+ "providers:\n strata:\n baseUrl: {url}/v1\n apiKey: {key}\n api: openai-completions\n"
+ " models:\n - id: {model}\n name: Strata ({model})\n")],
+ aliases=("oh-my-pi",)),
+ Harness("pi", "pi (pi.dev)", "chat + tools",
+ files=[FileSpec("~/.pi/agent/models.json", "json", _j({"providers": {"strata": {
+ "baseUrl": "{url}/v1", "api": "openai-completions", "apiKey": "{key}",
+ "models": [{"id": "{model}"}]}}}), merge=True)]),
+ Harness("hermes", "Hermes Agent", "chat + tools",
+ files=[FileSpec("~/.hermes/config.yaml", "yaml",
+ "model:\n provider: custom\n base_url: {url}/v1\n api_key: {key}\n default: {model}\n")],
+ aliases=("hermes-agent",)),
+ Harness("openclaw", "OpenClaw", "chat + tools",
+ files=[FileSpec("~/.openclaw/openclaw.json", "json", _j({"models": {"mode": "merge", "providers": {"strata": {
+ "baseUrl": "{url}/v1", "apiKey": "{key}", "api": "openai-completions",
+ "models": [{"id": "{model}", "name": "Strata ({model})"}]}}},
+ "agents": {"defaults": {"model": {"primary": "strata/{model}"}}}}), merge=True)]),
+ Harness("deepseek-harness", "DeepSeek Harness", "the Strata app", built_in=True,
+ notes=["Strata's own coding harness lives in the Strata app: open the app, choose Code, and it uses this server."],
+ aliases=("deepseek",)),
+]
+
+# The tested configs, when they exist, override the drafts: harness-configs/<id>.json beside this file (made from the .md files).
+OVERRIDE_DIR = Path(__file__).with_name("harness_configs")
+
+
+def load_overrides() -> None:
+ if not OVERRIDE_DIR.is_dir():
+ return
+ by_id = {h.id: h for h in HARNESSES}
+ for path in sorted(OVERRIDE_DIR.glob("*.json")):
+ try:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ h = by_id.get(data["id"]) or Harness(data["id"], data.get("title", data["id"]), data.get("speaks", ""))
+ h.title = data.get("title", h.title)
+ h.speaks = data.get("speaks", h.speaks)
+ h.files = [FileSpec(**f) for f in data.get("files", [])]
+ h.env = dict(data.get("env", {}))
+ h.notes = list(data.get("notes", []))
+ h.tested = bool(data.get("tested", True))
+ h.install = data.get("install", h.install)
+ if h.id not in by_id:
+ HARNESSES.append(h)
+ except (OSError, ValueError, KeyError, TypeError):
+ continue
+
+
+load_overrides()
+
+
+def find(name: str) -> Harness | None:
+ key = name.strip().lower()
+ for h in HARNESSES:
+ if key == h.id or key in h.aliases or key == h.title.lower():
+ return h
+ return None
+
+
+def closest_name(name: str) -> str | None:
+ from strata_cli.launch.settings import closest
+ return closest(name, [h.id for h in HARNESSES])
+
+
+# ------------------------------------------------------------------------------------------------ rendering
+
+def fill(text: str, *, url: str, key: str, model: str, port: int) -> str:
+ """Replace the placeholders; the key goes in only where the caller passed a real one."""
+ out = text
+ for k, v in (("{url}", url.rstrip("/")), ("{key}", key), ("{model}", model), ("{port}", str(port))):
+ out = out.replace(k, v)
+ return out
+
+
+def render(h: Harness, *, url: str, key: str, model: str) -> dict:
+ """What to show or write for this harness: files with their text, and environment lines."""
+ m = re.search(r":(\d+)(?:/|$)", url)
+ port = int(m.group(1)) if m else (443 if url.startswith("https") else 80)
+ files = []
+ for f in h.files:
+ files.append({"path": f.path, "kind": f.kind, "merge": f.merge,
+ "text": fill(f.content, url=url, key=key, model=model, port=port)})
+ env = {k: fill(v, url=url, key=key, model=model, port=port) for k, v in h.env.items()}
+ return {"harness": h.id, "title": h.title, "speaks": h.speaks, "status": h.status, "files": files, "env": env,
+ "notes": list(h.notes), "install": h.install}
+
+
+def expand(path: str) -> Path:
+ return Path(os.path.expanduser(path))
+
+
+def write_file(spec: dict, *, backup: bool = True) -> dict:
+ """Write one rendered file. An existing file is copied to `<name>.strata-bak-<time>` first; a JSON file with `merge` keeps the
+ keys it already had (the new ones win on the same key). Returns {path, backup, action}."""
+ path = expand(spec["path"])
+ path.parent.mkdir(parents=True, exist_ok=True)
+ existed = path.is_file()
+ bak = None
+ text = spec["text"]
+ if existed and backup:
+ bak = path.with_name(path.name + ".strata-bak-" + time.strftime("%Y%m%d-%H%M%S"))
+ shutil.copy2(path, bak)
+ if existed and spec.get("merge") and spec["kind"] == "json":
+ try:
+ old = json.loads(path.read_text(encoding="utf-8-sig"))
+ new = json.loads(text)
+ text = json.dumps(_merge(old, new), indent=2)
+ except ValueError:
+ pass # an old file that is not JSON is replaced (a backup was made)
+ path.write_text(text if text.endswith("\n") else text + "\n", encoding="utf-8")
+ try:
+ os.chmod(path, 0o600) # it can hold the API key
+ except OSError:
+ pass
+ return {"path": str(path), "backup": str(bak) if bak else None, "action": "merged" if existed and spec.get("merge") else
+ ("replaced" if existed else "created")}
+
+
+def _merge(old, new):
+ if isinstance(old, dict) and isinstance(new, dict):
+ out = dict(old)
+ for k, v in new.items():
+ out[k] = _merge(old[k], v) if k in old else v
+ return out
+ return new
+
+
+def mask(text: str, key: str) -> str:
+ return text.replace(key, key[:10] + "•" * 8) if key else text
diff --git a/strata_cli/launch/params.py b/strata_cli/launch/params.py
new file mode 100644
index 000000000..2624b75c1
--- /dev/null
+++ b/strata_cli/launch/params.py
@@ -0,0 +1,183 @@
+"""The Advanced table: every engine setting with its default, the tuned value and the person's own value.
+
+The list comes from the engine itself (its `--help`, the same read `strata tune` uses), plus the environment variables the tuner
+knows (strata_control/tune_knobs.py). Nothing is invented here: a setting the engine does not list is shown as unknown, with a
+warning and never a refusal, because newer engines have flags this one has not heard of.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+_ENTRY = re.compile(r"^ (--[A-Za-z0-9][A-Za-z0-9-]*)( +)?(.*)$")
+_EXPERIMENTAL = re.compile(r"experimental|diagnostic|A/B arm|fault injection|oracle", re.I)
+_DEFAULT = re.compile(r"\(\s*default[: ]\s*([^)]*)\)", re.I)
+_PARENS = re.compile(r"\([^)]*\)")
+
+
+@dataclass
+class Param:
+ name: str # --flag or ENV_NAME
+ kind: str # "flag" | "env"
+ metavar: str = ""
+ description: str = ""
+ help_default: str | None = None
+ experimental: bool = False
+ values: list[str] = field(default_factory=list)
+
+ @property
+ def short(self) -> str:
+ """One line: the first sentence, cut at 70 characters."""
+ text = re.sub(r"\s+", " ", re.sub(r"\([^)]*\)", "", self.description)).strip()
+ cut = re.split(r"(?<=[.;:])\s", text, maxsplit=1)[0] if text else ""
+ cut = cut.rstrip(".;:")
+ return cut if len(cut) <= 70 else cut[:67].rstrip() + "..."
+
+
+def parse_help(text: str) -> list[Param]:
+ """The engine's usage text -> parameters, one per flag (a flag listed twice, like --kv, keeps all of its descriptions)."""
+ params: dict[str, Param] = {}
+ current: Param | None = None
+ for line in text.splitlines():
+ m = _ENTRY.match(line)
+ if m and not line.startswith(" "):
+ name, gap, rest = m.group(1), m.group(2) or "", m.group(3) or ""
+ meta, desc = "", rest
+ if len(gap) == 1: # "--pack DIR the pack": one space, a value name, a gap
+ parts = re.split(r" {2,}", rest, maxsplit=1)
+ meta, desc = (parts[0], parts[1]) if len(parts) == 2 else (parts[0], "")
+ p = params.get(name)
+ if p is None:
+ p = params[name] = Param(name=name, kind="flag", metavar=meta, description=desc.strip())
+ else:
+ p.description = (p.description + " " + desc.strip()).strip()
+ p.metavar = p.metavar or meta
+ if meta and "|" in meta:
+ p.values = sorted(set(p.values + meta.split("|")))
+ current = p
+ elif current is not None and line.startswith(" ") and line.strip():
+ current.description += " " + line.strip()
+ elif not line.strip():
+ current = None
+ for p in params.values():
+ p.description = re.sub(r"\s+", " ", p.description).strip()
+ p.experimental = bool(_EXPERIMENTAL.search(p.description))
+ d = _DEFAULT.search(p.description)
+ if d:
+ p.help_default = (d.group(1) or "").strip().rstrip(".,;") or None
+ return list(params.values())
+
+
+def env_params() -> list[Param]:
+ """The environment settings the tuner knows (from tune_knobs.ARMS), with the tuner's own plain label."""
+ try:
+ from strata_control import tune_knobs
+ except ImportError:
+ return []
+ out: dict[str, Param] = {}
+ for arm in tune_knobs.ARMS:
+ for key in arm.env:
+ if key not in out:
+ out[key] = Param(name=key, kind="env", description=arm.label, experimental=arm.answer != "exact")
+ return list(out.values())
+
+
+def argv_to_dict(argv: list[Any]) -> dict[str, str]:
+ """`["--kv", "int8", "--kv-grow"]` -> {"--kv": "int8", "--kv-grow": ""}."""
+ out: dict[str, str] = {}
+ items = [str(x) for x in argv]
+ i = 0
+ while i < len(items):
+ tok = items[i]
+ if tok.startswith("--"):
+ if i + 1 < len(items) and not items[i + 1].startswith("--"):
+ out[tok] = items[i + 1]
+ i += 2
+ continue
+ out[tok] = ""
+ i += 1
+ return out
+
+
+@dataclass
+class Row:
+ name: str
+ default: str
+ tuned: str
+ yours: str
+ description: str
+ experimental: bool
+ known: bool = True
+
+ def cells(self) -> tuple[str, str, str, str]:
+ return (self.name, self.default or "-", self.tuned or "-", self.yours or "-")
+
+
+def build_rows(engine_help: str | None, base_args: list[Any], tuned_args: list[Any] | None, base_env: dict | None,
+ tuned_env: dict | None, extra: dict[str, str]) -> list[Row]:
+ """The table. Settings the run config or the tuner use come first (what this launch really runs), then the rest."""
+ base, tuned = argv_to_dict(base_args), argv_to_dict(tuned_args if tuned_args is not None else base_args)
+ params = {p.name: p for p in (parse_help(engine_help) if engine_help else [])}
+ for p in env_params():
+ params.setdefault(p.name, p)
+ names = list(dict.fromkeys([*base, *tuned, *(base_env or {}), *(tuned_env or {}), *extra, *params]))
+ rows: list[Row] = []
+ for name in names:
+ p = params.get(name)
+ is_env = not name.startswith("--")
+ d = (base_env or {}).get(name) if is_env else base.get(name)
+ t = (tuned_env or {}).get(name) if is_env else tuned.get(name)
+ if d is None:
+ d = (p.help_default if p and p.help_default else ("off" if is_env else ""))
+ if is_env:
+ t = t if t is not None else d
+ else:
+ t = t if t is not None else ""
+ shown = lambda v: "on" if v == "" and not is_env and name in (base if v is d else tuned) else v # noqa: E731
+ y = extra.get(name, "")
+ rows.append(Row(name=name, default=str(d) if d else "", tuned=str(t) if t else "", yours=str(y),
+ description=(p.short if p else "(not in this engine's list: newer flag or a typing mistake)"),
+ experimental=bool(p and p.experimental), known=bool(p) or not params))
+ in_use = lambda r: (r.name in base or r.name in tuned or r.name in extra or r.name in (base_env or {}) or r.name in (tuned_env or {})) # noqa: E731
+ rows.sort(key=lambda r: (not in_use(r), r.name))
+ return rows
+
+
+def check_name(name: str, engine_flags: list[str] | None) -> str | None:
+ """A warning (never a refusal) for a flag the engine's list does not have."""
+ if not name.startswith("--") or not engine_flags:
+ return None
+ if name in engine_flags:
+ return None
+ from strata_cli.launch.settings import closest
+ near = closest(name, engine_flags)
+ return (f"This engine does not list {name}. " + (f"Did you mean {near}? " if near else "")
+ + "It is kept as you typed it; a newer engine may know it, and this one may refuse to start with it.")
+
+
+def flag_list(engine: str | Path | None) -> list[str] | None:
+ """The engine's flags (the tuner's own read), or None when no engine can be run here."""
+ if not engine:
+ return None
+ try:
+ from strata_control import tuning
+ return tuning.engine_flag_inventory(Path(engine))
+ except Exception: # noqa: BLE001
+ return None
+
+
+def engine_help_text(engine: str | Path | None) -> str | None:
+ if not engine:
+ return None
+ import subprocess
+ try:
+ from strata_control import tuning
+ proc = subprocess.run([*tuning.engine_command(Path(engine)), "--help"], capture_output=True, text=True, timeout=20,
+ env=tuning.engine_env(Path(engine)))
+ except Exception: # noqa: BLE001
+ return None
+ text = f"{proc.stdout or ''}\n{proc.stderr or ''}"
+ return text if "--" in text else None
diff --git a/strata_cli/launch/runner.py b/strata_cli/launch/runner.py
new file mode 100644
index 000000000..d3b9ed3f0
--- /dev/null
+++ b/strata_cli/launch/runner.py
@@ -0,0 +1,631 @@
+"""What `strata launch` does after the choices are made: get the engine and the model, write the run config, tune, start, open access.
+
+Every step reports plain-word events through one callback (`emit`), so the TUI (progress screen), `--no-tui` (printed lines) and the
+tests see the same thing. Nothing here prints or reads the keyboard. The steps reuse what is already in the Terminal:
+
+* the engine comes from the signed feed (`strata update`, the one explicit step that downloads);
+* the model comes from setup.py in the app's own installer mode (STRATA_CONTROL_INSTALL), the same job the desktop app runs;
+* the run config the engine uses is a private copy of the installed one with this launch's choices applied; the profile
+ `launch-<name>` (the shared profiles store) points at it, and carries host, port and parallel;
+* tuning is `strata tune auto`, its result lives in the shared presets store and is applied at every start;
+* start and stop are `strata runtime start|stop` (a background service: it keeps serving after this terminal closes).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from strata_cli.launch import access as acc
+from strata_cli.launch import settings as S
+from strata_cli.launch.catalog import Catalog, CatalogUnavailable
+
+ROOT = Path(__file__).resolve().parents[2]
+WINDOWS = os.name == "nt"
+
+
+class LaunchError(RuntimeError):
+ """A step could not be done. `text` says what it means; `next` says what to do."""
+
+ def __init__(self, text: str, next: str = "", code: int = 6):
+ super().__init__((text + " " + next).strip())
+ self.text, self.next, self.code = text, next, code
+
+
+class Cancelled(LaunchError):
+ def __init__(self):
+ super().__init__("Stopped. Nothing was changed on your computer beyond files already downloaded.", "", 130)
+
+
+@dataclass
+class Event:
+ stage: str # engine | model | config | tune | start | access | done
+ text: str
+ pct: float | None = None
+ level: str = "info" # info | warn | error
+ data: dict = field(default_factory=dict)
+
+
+@dataclass
+class Result:
+ profile: str
+ urls: list[str]
+ key: str | None
+ tune_word: str | None
+ notices: list[str]
+ config: str
+ tunnel: str | None = None
+
+
+STAGES = ("engine", "model", "config", "tune", "start", "access")
+
+
+def tune_words(result: dict | None, code: int | None = None) -> tuple[str, str]:
+ """(short word, plain sentence) for a tuner result: faster / already fastest / busy PC / failed / stopped."""
+ if not result:
+ return "failed", "The tuner did not finish, so the standard settings run. Nothing was changed."
+ out = result.get("outcome")
+ if out == "improved":
+ gain = result.get("gain_pct")
+ return "faster", (f"Done: answers are about {gain:.0f}% faster with the tuned settings." if isinstance(gain, (int, float))
+ else "Done: the tuned settings are faster.")
+ if out == "default_confirmed":
+ return "already fastest", "Your computer already runs at its best with the standard settings. Nothing needed changing."
+ if out == "inconclusive":
+ return "busy PC", ("The computer was too busy to tell a real gain from noise, so the standard settings run. "
+ "Close other programs and tune again later (strata tune auto).")
+ if out == "cancelled":
+ return "stopped", "Tuning was stopped. Your settings were not changed."
+ return "failed", (result.get("message") or "Tuning could not run here.") + " The standard settings run."
+
+
+# ----------------------------------------------------------------------------------------------- run config
+
+def read_config(path: Path) -> dict:
+ return json.loads(Path(path).read_text(encoding="utf-8-sig"))
+
+
+def desc_matches(desc: dict, s: S.LaunchSettings) -> bool:
+ """Does the installed model's config already carry the context, memory format and picture choice of these settings?"""
+ if s.context and desc.get("context") != s.context:
+ return False
+ want_kv = s.kv or ("int8" if (s.context or 32768) > 8192 else "fp16")
+ if desc.get("kv") not in (None, want_kv) and (s.context or 32768) > 8192:
+ return False
+ images = desc.get("images") or "off"
+ if (s.vision == "off") != (images == "off"):
+ return False
+ if s.vision in ("gpu", "cpu") and images != s.vision:
+ return False
+ return True
+
+
+def files_present(cfg: dict) -> list[str]:
+ """The model files a run config names that are missing (empty list: all there)."""
+ missing = []
+ for tok in cfg.get("args") or []:
+ if isinstance(tok, str) and tok.lower().endswith(".gguf") and not Path(tok).exists():
+ missing.append(tok)
+ for flag in ("--pack", "--mtp"):
+ args = [str(a) for a in cfg.get("args") or []]
+ if flag in args and args.index(flag) + 1 < len(args) and not Path(args[args.index(flag) + 1]).exists():
+ missing.append(args[args.index(flag) + 1])
+ return missing
+
+
+def derive_config(base: dict, s: S.LaunchSettings, *, bool_flags: frozenset[str], log: str | None = None) -> dict:
+ """The private run config of this launch: the installed one plus the choices that are not setup's (host, port, key, advanced)."""
+ from strata_control import tune_knobs
+ cfg = json.loads(json.dumps(base))
+ cfg["host"] = acc.host_for(s.access)
+ cfg["port"] = int(s.port)
+ if s.api_key:
+ cfg["api_key"] = s.api_key
+ else:
+ cfg.pop("api_key", None)
+ cfg.setdefault("exe", "component:strata-engine")
+ if log:
+ cfg["log"] = log
+ if s.extra:
+ a_changes, e_changes = S.as_argv_changes(s.extra, bool_flags)
+ cfg["args"] = tune_knobs.apply_to_argv([str(x) for x in cfg.get("args") or []], a_changes)
+ if e_changes:
+ cfg["env"] = tune_knobs.apply_to_env(dict(cfg.get("env") or {}), e_changes)
+ return cfg
+
+
+def write_private(path: Path, data: dict) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ fd, tmp = tempfile.mkstemp(prefix=".launch-cfg-", suffix=".tmp", dir=path.parent)
+ try:
+ with os.fdopen(fd, "wb") as fh:
+ fh.write((json.dumps(data, indent=1, ensure_ascii=False) + "\n").encode("utf-8"))
+ try:
+ os.chmod(tmp, 0o600)
+ except OSError:
+ pass
+ os.replace(tmp, path)
+ finally:
+ if os.path.exists(tmp):
+ os.unlink(tmp)
+ if WINDOWS:
+ try:
+ from strata_control import private_files
+ private_files.restrict_to_current_user(path, directory=False)
+ except Exception: # noqa: BLE001
+ pass
+
+
+def launch_dir() -> Path:
+ from strata_control import paths
+ d = paths.state_base() / "launch"
+ d.mkdir(parents=True, exist_ok=True)
+ return d
+
+
+# ----------------------------------------------------------------------------------------------- the runner
+
+class Runner:
+ def __init__(self, s: S.LaunchSettings, *, catalog: Catalog | None = None, emit: Callable[[Event], None] | None = None,
+ cancel: threading.Event | None = None, feed: str | None = None, python: str | None = None,
+ components_dir: str | None = None, hardware: dict | None = None):
+ self.s = s
+ self._catalog = catalog
+ self.emit_cb = emit or (lambda e: None)
+ self.cancel = cancel or threading.Event()
+ self.feed = feed
+ self.python = python or sys.executable
+ self.components_dir = components_dir
+ self.hardware_override = hardware
+ self.children: list[subprocess.Popen] = []
+ self.notices: list[str] = []
+ self.tune_result: dict | None = None
+ self.config_path: Path | None = None
+
+ # ---- small helpers
+ def emit(self, stage: str, text: str, pct: float | None = None, level: str = "info", **data: Any) -> None:
+ self.emit_cb(Event(stage, text, pct, level, data))
+
+ def check_cancel(self) -> None:
+ if self.cancel.is_set():
+ raise Cancelled()
+
+ @property
+ def catalog(self) -> Catalog:
+ if self._catalog is None:
+ try:
+ self._catalog = Catalog(hardware=self.hardware_override)
+ except CatalogUnavailable as e:
+ raise LaunchError(str(e), "", 5) from None
+ return self._catalog
+
+ @property
+ def name(self) -> str:
+ return S.slug(self.s.name or (self.s.model or "model") + "-" + S.context_label(self.s.context).lower())
+
+ @property
+ def profile(self) -> str:
+ return "launch-" + self.name
+
+ def _env(self) -> dict[str, str]:
+ env = dict(os.environ, PYTHONUNBUFFERED="1", PYTHONIOENCODING="utf-8")
+ env.pop("STRATA_NO_ACQUIRE", None) # launch is the explicit step that may download
+ if self.components_dir:
+ env["STRATA_COMPONENTS_DIR"] = self.components_dir
+ return env
+
+ def _spawn(self, argv: list[str], *, env: dict | None = None, cwd: str | None = None) -> subprocess.Popen:
+ kw = {"creationflags": subprocess.CREATE_NO_WINDOW} if WINDOWS else {}
+ p = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+ encoding="utf-8", errors="replace", env=env or self._env(), cwd=cwd, bufsize=1, **kw)
+ self.children.append(p)
+ return p
+
+ def _stop_children(self) -> None:
+ """End only the processes this runner started (by the handles it holds)."""
+ for p in self.children:
+ if p.poll() is None:
+ try:
+ p.terminate()
+ p.wait(timeout=15)
+ except Exception: # noqa: BLE001
+ try:
+ p.kill()
+ except Exception: # noqa: BLE001
+ pass
+
+ def _cli(self, *args: str) -> list[str]:
+ return [self.python, str(ROOT / "strata.py"), *args]
+
+ # ---- 1. the engine
+ def ensure_engine(self) -> None:
+ self.emit("engine", "Checking the engine for this computer…")
+ from strata_control import engine_component as ec
+ root = Path(self.components_dir) if self.components_dir else None
+ report = ec.status(root)
+ if report.get("usable"):
+ eng = report["engine"]
+ self.emit("engine", f"Engine {eng['version']} ({eng['backend']}) is installed.", 100)
+ return
+ feed = self.feed or os.environ.get("STRATA_UPDATE_FEED")
+ self.emit("engine", "No engine is installed yet. Getting the one for your graphics card…", 0)
+ argv = self._cli("update", "--no-control", "--output", "jsonl")
+ if feed:
+ argv += ["--feed", feed]
+ if self.components_dir:
+ argv += ["--components-dir", self.components_dir]
+ p = self._spawn(argv)
+ last = None
+ tail: list[str] = []
+ for line in p.stdout: # type: ignore[union-attr]
+ self.check_cancel()
+ line = line.strip()
+ if not line:
+ continue
+ try:
+ ev = json.loads(line)
+ except ValueError:
+ tail.append(line)
+ continue
+ if ev.get("event") == "progress":
+ self.emit("engine", f"Downloading the engine… {ev.get('percent', 0)}%", float(ev.get("percent", 0)))
+ elif ev.get("event") in ("phase", "waiting"):
+ self.emit("engine", str(ev.get("message") or ""))
+ last = ev
+ code = p.wait()
+ if code != 0:
+ why = ""
+ if isinstance(last, dict):
+ why = str((last.get("error") or {}).get("message") or last.get("message") or "")
+ why = why or (tail[-1] if tail else "")
+ raise LaunchError("The engine could not be installed." + (f" {why}" if why else ""),
+ "Check your internet connection, or point Strata at an update source with --feed, then try again.", 6)
+ self.emit("engine", "The engine is installed.", 100)
+
+ # ---- 2. the model
+ def setup_args(self) -> list[str]:
+ cat, s = self.catalog, self.s
+ fam, model = s.family, s.model
+ args = ["--yes", "--no-start", "--family", str(fam), "--model", str(model)]
+ ctx = s.context
+ if ctx:
+ args += ["--context", str(ctx)]
+ args += ["--vision", {"off": "no", "on": "yes"}.get(s.vision, s.vision)]
+ if s.kv:
+ args += ["--kv", s.kv]
+ if fam in ("qwen", "coder"):
+ args += ["--experimental-speed-projection", "off"]
+ data = s.data_dir
+ if data:
+ args += ["--data-dir", str(data)]
+ if s.model_path:
+ p = Path(s.model_path)
+ args += ["--gguf-dir", str(p if p.is_dir() else p.parent)]
+ if s.gpus:
+ args += ["--gpus", ",".join(str(g) for g in s.gpus)] if len(s.gpus) > 1 else ["--gpu", str(s.gpus[0])]
+ return args
+
+ def installed_state(self) -> tuple[Path | None, dict | None]:
+ tag = self.catalog.tag_of(self.s.family, self.s.model)
+ path = self.catalog.installed_config(tag)
+ if path is None:
+ return None, None
+ desc = self.catalog.strata.describe_config(path)
+ return path, desc
+
+ def ensure_model(self) -> Path:
+ s, cat = self.s, self.catalog
+ if s.model_path and not (s.family and s.model):
+ self.resolve_own_files()
+ if not (s.family and s.model):
+ raise LaunchError("No model was chosen.", "Choose a model, or use --model NAME (strata launch --help lists them).", 2)
+ path, desc = self.installed_state()
+ if path is not None and desc is not None and desc_matches(desc, s) and not files_present(read_config(path)):
+ self.emit("model", f"{s.family} {s.model} is already installed with these choices.", 100)
+ return path
+ title = f"{s.family} {s.model}"
+ self.emit("model", f"Getting {title} ready (a download may be large; it continues where it stopped if interrupted)…", 0)
+ argv = [self.python, str(cat.src / "setup.py"), *self.setup_args()]
+ env = self._env()
+ env.update(STRATA_CONTROL_INSTALL="1", STRATA_INSTALL_DIR=str(cat.root), PYTHONNOUSERSITE="1")
+ for k in ("PYTHONHOME", "PYTHONPATH", "VIRTUAL_ENV"):
+ env.pop(k, None)
+ env["PYTHONPATH"] = str(cat.src)
+ p = self._spawn(argv, env=env, cwd=str(cat.src))
+ lines: list[str] = []
+ folder = str(cat.data_dir() / "models" / cat.tag_of(s.family, s.model))
+ total = float(next((r.download_gb for r in cat.rows() if r.family == s.family and r.model == s.model), 0) or 0)
+ for line in p.stdout: # type: ignore[union-attr]
+ if self.cancel.is_set():
+ self._stop_children()
+ raise Cancelled()
+ line = line.rstrip()
+ if not line:
+ continue
+ lines.append(line)
+ lines[:] = lines[-400:]
+ prog = cat.mcp.install_progress(lines)
+ prog = cat.mcp.combined_progress(prog, {"folder": folder, "total_gb": total})
+ dl = prog.get("download")
+ if dl and not s.model_path:
+ self.emit("model", f"Downloading {dl['done_gb']:.1f} of {dl['total_gb']:.1f} GB", float(dl["percent"]), step=prog.get("step"))
+ elif prog.get("step"):
+ self.emit("model", f"Setup step {prog['step']}", None, step=prog.get("step"))
+ code = p.wait()
+ if code != 0:
+ err = ""
+ for line in reversed(lines):
+ if line.strip().startswith("[X]"):
+ err = line.strip()[3:].strip()
+ break
+ hint = ""
+ if err:
+ for i, line in enumerate(lines):
+ if err in line and i + 1 < len(lines) and lines[i + 1].startswith(" "):
+ hint = lines[i + 1].strip()
+ raise LaunchError("The model could not be installed." + (f" {err}." if err else ""),
+ hint or "Run it again: finished steps are skipped and a download continues where it stopped.", 6)
+ path, _desc = self.installed_state()
+ if path is None:
+ raise LaunchError("Setup finished but no run config was written for this model.",
+ "Run `strata launch` again; if it repeats, the setup output above says why.", 6)
+ self.emit("model", f"{title} is ready.", 100)
+ return path
+
+ def resolve_own_files(self) -> None:
+ """"Use model files I already have": the fingerprint table says which catalog model the files are."""
+ from strata_control import models
+ s = self.s
+ try:
+ plan = models.plan_import(str(Path(s.model_path).expanduser().resolve()))
+ except Exception as e: # noqa: BLE001
+ raise LaunchError(f"These model files cannot be used: {e}.", "Pick the folder with every shard of one model, or a .gguf file of it.", 5) from None
+ sel = plan.get("candidate_selection") or {}
+ fam, model = sel.get("family"), sel.get("model")
+ if not (fam and model) or plan.get("issues"):
+ issues = "; ".join(plain_issue(str(x)) for x in (plan.get("issues") or [])[:3]) or "they are not a model Strata knows"
+ raise LaunchError(f"These files cannot be used as they are ({issues}).",
+ "Choose the matching model in the list, or check that every shard is in the folder.", 5)
+ s.family, s.model = fam, model
+ self.emit("model", f"These files are {fam} {model}.", None)
+
+ # ---- 3. config and profile
+ def build_config(self, base_path: Path) -> Path:
+ from strata_control import tune_knobs
+ base = read_config(base_path)
+ cfg = derive_config(base, self.s, bool_flags=tune_knobs.BOOL_FLAGS,
+ log=str(launch_dir() / f"{self.name}.engine.log"))
+ out = launch_dir() / f"{self.name}.json"
+ write_private(out, cfg)
+ self.config_path = out
+ return out
+
+ def ensure_profile(self, config: Path) -> None:
+ from strata_control import profiles
+ name = self.profile
+ parallel = self.s.parallel if self.s.parallel else self.catalog_parallel()
+ sets = [f"host={acc.host_for(self.s.access)}", f"port={int(self.s.port)}"] + ([f"parallel={parallel}"] if parallel else [])
+ try:
+ current, _rev = profiles.load(name)
+ except profiles.ProfileError:
+ profiles.create(name, str(config))
+ else:
+ if current.get("source_config") != str(config.resolve()):
+ proposed, rev = profiles.propose_source(name, str(config))
+ profiles.save(name, proposed, expected_revision=rev)
+ # the overrides are replaced as a set: a launch's host/port/parallel are exactly these
+ cur, rev = profiles.load(name)
+ want = {k: v for k, v in (profiles.parse_assignment(x) for x in sets)}
+ if cur.get("overrides") != want:
+ profiles.save(name, {**cur, "overrides": want}, expected_revision=rev)
+
+ def catalog_parallel(self) -> int | None:
+ try:
+ comp = self.catalog.computer()
+ return S.fit_parallel(comp.main_vram_gb) if comp.usable_gpus else None
+ except Exception: # noqa: BLE001
+ return None
+
+ # ---- 4. tuning
+ def tune(self) -> None:
+ s = self.s
+ if s.tune == "skip":
+ return
+ from strata_control import presets
+ if s.tuned_preset:
+ try:
+ presets.find(s.tuned_preset)
+ self.emit("tune", "This preset is already tuned for this computer.", 100)
+ return
+ except presets.PresetError:
+ pass
+ mode = "thorough" if s.tune == "thorough" else "quick"
+ status_file = launch_dir() / f"{self.name}.tune.json"
+ try:
+ status_file.unlink()
+ except OSError:
+ pass
+ argv = self._cli("tune", "auto", self.profile, "--mode", mode, "--output", "json", "--status-file", str(status_file),
+ "--name", (s.name or self.name))
+ if s.tune_allow_small:
+ argv.append("--allow-small-differences")
+ self.emit("tune", "Tuning for the best speed. Close other heavy programs while it measures.", 0)
+ p = self._spawn(argv)
+ out_lines: list[str] = []
+ reader = threading.Thread(target=lambda: out_lines.extend(p.stdout.readlines()), daemon=True) # type: ignore[union-attr]
+ reader.start()
+ while p.poll() is None:
+ if self.cancel.is_set():
+ self._stop_children()
+ raise Cancelled()
+ st = _read_json(status_file)
+ if st:
+ done, planned = st.get("runs_done") or 0, st.get("runs_planned") or 0
+ pct = (100.0 * done / planned) if planned else None
+ left = st.get("minutes_left")
+ self.emit("tune", st.get("message") or "Measuring…", pct, speeds=st.get("speeds") or [],
+ round=(done, planned), minutes_left=left)
+ time.sleep(1.0)
+ reader.join(timeout=3)
+ result = None
+ for line in reversed(out_lines):
+ try:
+ result = json.loads(line).get("result")
+ break
+ except (ValueError, AttributeError):
+ continue
+ self.tune_result = result
+ word, sentence = tune_words(result, p.returncode)
+ self.tune_word = word
+ preset = (result or {}).get("preset") or {}
+ if preset.get("id"):
+ s.tuned_preset, s.tuned_at = preset["id"], time.strftime("%Y-%m-%d")
+ elif result and result.get("outcome") == "default_confirmed":
+ s.tuned_at = time.strftime("%Y-%m-%d")
+ self.emit("tune", sentence, 100, level="info" if word in ("faster", "already fastest") else "warn", word=word)
+
+ tune_word: str | None = None
+
+ # ---- 5. start
+ def start(self) -> None:
+ from strata_control import runtime
+ from strata_control.profiles import ProfileError
+ name = self.profile
+ st = runtime.status(name)
+ if st.get("state") in ("ready", "starting"):
+ self.emit("start", "A server for this preset is already running; restarting it with these choices…")
+ try:
+ runtime.stop(name, timeout=120)
+ except ProfileError as e:
+ raise LaunchError(f"The running server could not be stopped: {e}.", "Run `strata launch --stop` first.", 6) from None
+ self.emit("start", "Starting the engine and loading the model. The first start can take a few minutes.", None)
+ done = threading.Event()
+ box: dict[str, Any] = {}
+
+ def go() -> None:
+ try:
+ box["r"] = runtime.start(name, wait=600)
+ except Exception as e: # noqa: BLE001
+ box["e"] = e
+ finally:
+ done.set()
+
+ threading.Thread(target=go, daemon=True).start()
+ t0 = time.monotonic()
+ while not done.wait(1.0):
+ if self.cancel.is_set():
+ try:
+ runtime.stop(name, timeout=60)
+ except Exception: # noqa: BLE001
+ pass
+ raise Cancelled()
+ self.emit("start", f"Loading the model… {int(time.monotonic() - t0)} s", None)
+ if "e" in box:
+ raise LaunchError(f"The server could not start: {box['e']}", _log_hint(self.config_path), 6)
+ r = box["r"]
+ if not r.get("ok"):
+ raise LaunchError(f"The server did not become ready ({r.get('state')}: {r.get('error') or r.get('message') or 'see the engine log'}).",
+ _log_hint(self.config_path), 6)
+ self.emit("start", "The model is loaded and answering.", 100)
+
+ # ---- 6. access
+ def open_access(self) -> str | None:
+ s = self.s
+ missing = acc.missing_helper(s.access)
+ tunnel = None
+ if s.access == "cloudflare":
+ if missing:
+ self.notices.append(missing + " The server is running on this computer meanwhile.")
+ self.emit("access", missing, level="warn")
+ else:
+ self.emit("access", "Opening a Cloudflare quick tunnel…")
+ tunnel, msg = acc.start_tunnel(self.profile, int(s.port))
+ if tunnel is None:
+ self.notices.append(msg)
+ self.emit("access", msg, level="info" if tunnel else "warn", url=tunnel)
+ elif missing:
+ self.notices.append(missing)
+ self.emit("access", missing, level="warn")
+ else:
+ self.emit("access", "Ready: " + ", ".join(acc.urls_for(s)), 100)
+ return tunnel
+
+ # ---- all of it
+ def plan(self) -> dict:
+ s = self.s
+ warns = [n.line() for n in (*S.check_access(s),)]
+ return {"profile": self.profile, "settings": s.to_dict(with_key=False), "warnings": warns,
+ "flags": S.flags_text(s), "steps": list(STAGES)}
+
+ def run(self, *, start: bool = True) -> Result:
+ try:
+ self.ensure_engine()
+ self.check_cancel()
+ base = self.ensure_model()
+ self.check_cancel()
+ self.emit("config", "Writing this launch's settings…")
+ cfg = self.build_config(base)
+ self.ensure_profile(cfg)
+ self.emit("config", "Settings are saved.", 100)
+ self.tune()
+ self.check_cancel()
+ if not start:
+ return Result(self.profile, [], self.s.api_key, self.tune_word, self.notices, str(cfg))
+ self.start()
+ tunnel = self.open_access()
+ urls = acc.urls_for(self.s, tunnel_url=tunnel)
+ res = Result(self.profile, urls, self.s.api_key, self.tune_word, self.notices, str(cfg), tunnel)
+ self.emit("done", "Strata is serving.", 100, urls=urls)
+ return res
+ except Cancelled:
+ self._stop_children()
+ raise
+ except LaunchError:
+ self._stop_children()
+ raise
+
+ def stop(self) -> dict:
+ from strata_control import runtime
+ out = runtime.stop(self.profile, timeout=180)
+ acc.stop_tunnel(self.profile)
+ return out
+
+
+ISSUE_WORDS = {
+ "multiple_model_groups": "the folder holds more than one model",
+ "incomplete_or_invalid_shard_set": "some shards are missing",
+ "unrecognized_or_unsupported_model_variant": "this is not a model size Strata knows",
+ "unsupported_or_missing_architecture": "this is not a model Strata can run",
+ "unsupported_or_incomplete_tokenizer_metadata": "the file has no usable tokenizer",
+ "missing_or_unexpected_expert_quantization": "its quantization is not one Strata knows",
+}
+
+
+def plain_issue(code: str) -> str:
+ return ISSUE_WORDS.get(code, code.replace("_", " "))
+
+
+def _read_json(path: Path) -> dict | None:
+ try:
+ return json.loads(Path(path).read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return None
+
+
+def _log_hint(config: Path | None) -> str:
+ log = None
+ if config:
+ try:
+ log = read_config(config).get("log")
+ except (OSError, ValueError):
+ log = None
+ return f"The engine's log has the reason: {log}" if log else "The engine's log has the reason (strata logs, or the log named in the run config)."
diff --git a/strata_cli/launch/settings.py b/strata_cli/launch/settings.py
new file mode 100644
index 000000000..b15faf9ba
--- /dev/null
+++ b/strata_cli/launch/settings.py
@@ -0,0 +1,282 @@
+"""What a launch is made of, as plain data: the choices of the setup screens, the rules that turn them into warnings, and the
+flags that say the same thing without the TUI.
+
+No Textual, no network, standard library only: the screens, the flags and the saved presets all use this one description,
+so `strata launch --preset X` and clicking through the screens cannot drift apart.
+
+Rules of this file: recommend, never force. A choice that does not fit this computer is a warning with the reason; only
+a value that cannot be run at all (a port that is not a number, an unknown access kind) is an error.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from dataclasses import asdict, dataclass, field, fields
+from typing import Any
+
+SCHEMA = "strata.launch/1"
+
+#: setup.py's CONTEXTS (kept here only as the fallback when the installer files are not next to this terminal).
+FALLBACK_CONTEXTS = (8192, 32768, 65536, 131072, 204800, 262144, 393216, 524288)
+
+ACCESS_KINDS = ("local", "lan", "cloudflare", "tailscale")
+ACCESS_WORDS = {"local": "This computer only", "lan": "My local network", "cloudflare": "Cloudflare tunnel",
+ "tailscale": "Tailscale"}
+TUNE_MODES = ("quick", "thorough", "skip")
+VISION_MODES = ("off", "on", "gpu", "cpu")
+KV_MODES = ("int8", "q4_0", "k8v4", "fp16")
+DEFAULT_PORT = 8080
+
+#: How many requests the card can answer at once (the spec's "fit to card" default): by graphics memory.
+PARALLEL_BY_VRAM = ((32.0, 4), (24.0, 3), (20.0, 2), (0.0, 1))
+
+
+def fit_parallel(vram_gb: float | None) -> int:
+ """12 GB -> 1, 20 -> 2, 24 -> 3, 32 and more -> 4 (each step starts at the listed size)."""
+ gb = float(vram_gb or 0.0)
+ for floor, n in PARALLEL_BY_VRAM:
+ if gb >= floor - 0.5:
+ return n
+ return 1
+
+
+def parse_context(text: Any) -> int:
+ """`128k`, `128K`, `131072` or `64 K` -> tokens. 1K is 1024 tokens (the engine's and setup's unit)."""
+ raw = str(text).strip().lower().replace(" ", "").replace("_", "").replace(",", "")
+ m = re.fullmatch(r"(\d+(?:\.\d+)?)(k|m)?", raw)
+ if not m:
+ raise ValueError(f"'{text}' is not a context size. Use a number of tokens or a size such as 32k, 64k, 128k, 256k.")
+ value = float(m.group(1)) * {"k": 1024, "m": 1024 * 1024, None: 1}[m.group(2)]
+ n = int(round(value))
+ if n < 1024:
+ raise ValueError(f"A context of {n} tokens is too small to be useful; the smallest size offered is 8k.")
+ return n
+
+
+def context_label(tokens: int | None) -> str:
+ if not tokens:
+ return "default"
+ if tokens % 1024 == 0:
+ return f"{tokens // 1024}K"
+ if tokens >= 1000:
+ return f"{tokens / 1000:g}K"
+ return str(tokens)
+
+
+def words_for(tokens: int) -> str:
+ """About how many English words fit (0.75 words per token, rounded to two figures)."""
+ words = tokens * 0.75
+ mag = 10 ** max(0, len(str(int(words))) - 2)
+ return f"about {int(round(words / mag) * mag):,} words"
+
+
+@dataclass
+class LaunchSettings:
+ """Every choice of `strata launch`. `None` means "the recommendation for this computer"."""
+
+ name: str | None = None # the saved preset's name
+ family: str | None = None # catalog family id (qwen, swift, coder, unsloth, gyro, nvfp4...)
+ model: str | None = None # catalog size (IQ3_XXS ...)
+ model_path: str | None = None # "Use model files I already have": a .gguf file or a folder
+ data_dir: str | None = None # where model files are stored (None: the Strata default)
+ gpus: list[int] | None = None # None = the engine's choice (all usable cards)
+ context: int | None = None
+ kv: str | None = None # None = int8 above 8K, as setup
+ vision: str = "off" # off | on | gpu | cpu
+ parallel: int | None = None # None = fit to the card
+ tune: str = "skip" # quick | thorough | skip
+ tune_allow_small: bool = False # the "answer-changing" tick, off by default, as in the app
+ access: str = "local"
+ port: int = DEFAULT_PORT
+ api_key: str | None = None # never shown whole; stored only in the private preset file
+ extra: dict[str, str] = field(default_factory=dict) # Advanced: --set key=value (flags and STRATA_* variables)
+ # filled in by the run, kept in the preset
+ tuned_preset: str | None = None # id of the tuning preset the tuner saved
+ tuned_at: str | None = None
+ last_used: str | None = None
+ created: str | None = None
+
+ def to_dict(self, *, with_key: bool = True) -> dict[str, Any]:
+ d = {"schema": SCHEMA, **asdict(self)}
+ if not with_key:
+ d["api_key"] = "set" if self.api_key else None
+ return d
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> "LaunchSettings":
+ known = {f.name for f in fields(cls)}
+ clean = {k: v for k, v in (data or {}).items() if k in known}
+ if isinstance(clean.get("extra"), dict):
+ clean["extra"] = {str(k): str(v) for k, v in clean["extra"].items()}
+ else:
+ clean.pop("extra", None)
+ return cls(**clean)
+
+ def copy(self, **changes: Any) -> "LaunchSettings":
+ d = asdict(self)
+ d.update(changes)
+ return LaunchSettings.from_dict(d)
+
+
+# ----------------------------------------------------------------------------------------------------- checks
+
+@dataclass
+class Notice:
+ level: str # "warn" | "error"
+ text: str # plain words: what it means
+ next: str = "" # plain words: what to do
+
+ def line(self) -> str:
+ return self.text + (f" {self.next}" if self.next else "")
+
+
+def closest(word: str, options: list[str]) -> str | None:
+ hit = difflib.get_close_matches(word.lower(), [o.lower() for o in options], n=1, cutoff=0.5)
+ if not hit:
+ return None
+ return next(o for o in options if o.lower() == hit[0])
+
+
+def check_port(port: Any) -> Notice | None:
+ try:
+ p = int(port)
+ except (TypeError, ValueError):
+ return Notice("error", f"'{port}' is not a port number.", "Use a number from 1 to 65535, for example 8080.")
+ if not 1 <= p <= 65535:
+ return Notice("error", f"Port {p} does not exist.", "Use a number from 1 to 65535, for example 8080.")
+ if p < 1024:
+ return Notice("warn", f"Port {p} is below 1024; on many computers only an administrator can use it.",
+ "8080 works without special rights.")
+ return None
+
+
+def check_access(s: LaunchSettings) -> list[Notice]:
+ out: list[Notice] = []
+ if s.access not in ACCESS_KINDS:
+ near = closest(s.access, list(ACCESS_KINDS))
+ out.append(Notice("error", f"'{s.access}' is not a way to share Strata.",
+ f"Choose one of: {', '.join(ACCESS_KINDS)}." + (f" Did you mean '{near}'?" if near else "")))
+ return out
+ port = check_port(s.port)
+ if port:
+ out.append(port)
+ if s.access != "local" and not s.api_key:
+ out.append(Notice("warn", f"{ACCESS_WORDS[s.access]} without an API key lets anyone who can reach it use your computer's model.",
+ "Add an API key (Strata makes one for you in the Access step)."))
+ return out
+
+
+def check_parallel(s: LaunchSettings, *, vram_gb: float | None, fitted: int | None = None) -> list[Notice]:
+ out: list[Notice] = []
+ if s.parallel is None:
+ return out
+ if not 1 <= int(s.parallel) <= 8:
+ out.append(Notice("error", f"{s.parallel} requests at once is outside what the engine can do (1 to 8).",
+ "Pick a number from 1 to 8."))
+ return out
+ fitted = fit_parallel(vram_gb) if fitted is None else fitted
+ if vram_gb and s.parallel > fitted:
+ out.append(Notice("warn", f"{s.parallel} requests at once is more than a {vram_gb:.0f} GB card usually holds "
+ f"(it fits {fitted}).",
+ "It can still start; the engine keeps less of the model in graphics memory, so each answer is slower."))
+ return out
+
+
+def check_context(s: LaunchSettings, *, max_fit_tokens: int | None = None) -> list[Notice]:
+ out: list[Notice] = []
+ if s.context is not None and s.context > 262144:
+ out.append(Notice("warn", f"{context_label(s.context)} is more than the model was trained on (256K).",
+ "Setup adds rope scaling for it (experimental); answers may get less reliable."))
+ if max_fit_tokens and s.context and s.context > max_fit_tokens:
+ out.append(Notice("warn", f"{context_label(s.context)} is bigger than this computer's memory comfortably holds.",
+ f"{context_label(max_fit_tokens)} is the recommended size."))
+ return out
+
+
+# ----------------------------------------------------------------------------------------------------- advanced settings
+
+_ENV_NAME = re.compile(r"^[A-Z][A-Z0-9_]*$")
+_FLAG_NAME = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def split_setting(text: str) -> tuple[str, str]:
+ """`prefill=65536`, `--prefill=65536`, `STRATA_PIN_BY_NEED=1` -> (key, value); the key is a `--flag` or an ENV name."""
+ key, sep, value = text.partition("=")
+ key = key.strip()
+ if not key:
+ raise ValueError("an empty setting name")
+ if _ENV_NAME.match(key):
+ return key, value.strip()
+ flag = key[2:] if key.startswith("--") else key
+ flag = flag.replace("_", "-")
+ if not _FLAG_NAME.match(flag):
+ raise ValueError(f"'{text}' is not a setting name. Write it like prefill=65536 or STRATA_PIN_BY_NEED=1.")
+ return "--" + flag, value.strip()
+
+
+def settings_from_pairs(pairs: list[str]) -> dict[str, str]:
+ out: dict[str, str] = {}
+ for p in pairs or []:
+ k, v = split_setting(p)
+ out[k] = v
+ return out
+
+
+def as_argv_changes(extra: dict[str, str], bool_flags: frozenset[str]) -> tuple[dict[str, Any], dict[str, str | None]]:
+ """Turn the Advanced table's values into `tune_knobs.apply_to_argv` changes and environment changes.
+
+ A flag without a value (or on/true/yes) is "present"; off/false/no/none removes it; anything else is a value."""
+ args: dict[str, Any] = {}
+ env: dict[str, str | None] = {}
+ for key, value in extra.items():
+ if key.startswith("--"):
+ low = value.lower()
+ if key in bool_flags or low in ("on", "true", "yes", ""):
+ args[key] = None if low in ("off", "false", "no", "none") else True
+ elif low in ("off", "false", "no", "none"):
+ args[key] = None
+ else:
+ args[key] = value
+ else:
+ env[key] = None if value.lower() in ("off", "unset", "none") else value
+ return args, env
+
+
+def flags_text(s: LaunchSettings, *, preset: str | None = None) -> str:
+ """The `strata launch ...` line that says the same as these choices (copyable)."""
+ parts = ["strata launch"]
+ if preset:
+ parts.append(f'--preset "{preset}"')
+ else:
+ if s.model_path:
+ parts.append(f'--model-path "{s.model_path}"')
+ elif s.model:
+ parts.append(f"--model {s.model.lower()}" + (f" --family {s.family}" if s.family and s.family != "qwen" else ""))
+ if s.data_dir:
+ parts.append(f'--data-dir "{s.data_dir}"')
+ if s.context:
+ parts.append(f"--context {context_label(s.context).lower()}")
+ if s.kv:
+ parts.append(f"--kv {s.kv}")
+ parts.append(f"--vision {s.vision}")
+ if s.parallel:
+ parts.append(f"--parallel {s.parallel}")
+ parts.append(f"--tune {s.tune}")
+ if s.tune_allow_small:
+ parts.append("--tune-allow-small")
+ parts.append(f"--access {s.access}")
+ parts.append(f"--port {s.port}")
+ if s.gpus:
+ parts.append("--gpu " + ",".join(str(g) for g in s.gpus))
+ for k, v in sorted(s.extra.items()):
+ parts.append(f"--set {k[2:] if k.startswith('--') else k}={v}" if v else f"--set {k[2:] if k.startswith('--') else k}")
+ return " ".join(parts)
+
+
+def slug(name: str) -> str:
+ """A name safe for profile ids and file names: lowercase letters, digits, - and _, starting with a letter."""
+ text = re.sub(r"[^a-z0-9_-]+", "-", name.lower()).strip("-_") or "launch"
+ if not text[0].isalpha():
+ text = "l" + text
+ return text[:48]
diff --git a/strata_cli/launch/store.py b/strata_cli/launch/store.py
new file mode 100644
index 000000000..4ce704557
--- /dev/null
+++ b/strata_cli/launch/store.py
@@ -0,0 +1,141 @@
+"""Saved launch presets: the whole answer set of the setup screens under a name.
+
+One small JSON file per preset in `launch-presets/` beside the profiles folder (so it is found wherever the profiles are, and
+`STRATA_LAUNCH_PRESET_DIR` moves it for tests). The files are private to the user (they can hold the API key). The tuned
+settings themselves are NOT copied here: a preset points at the tuning preset the tuner saved (`strata presets`, the store the
+desktop app also uses), so a re-tune in either place is seen in both. The profile the run uses (`strata profile`) is the shared
+one too (named `launch-<slug>`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from strata_cli.launch.settings import LaunchSettings, slug
+
+
+class PresetError(ValueError):
+ """A saved launch preset is missing or damaged; the message is for the user."""
+
+
+def preset_dir() -> Path:
+ explicit = os.environ.get("STRATA_LAUNCH_PRESET_DIR")
+ if explicit:
+ return Path(explicit).expanduser()
+ from strata_control import profiles
+ return profiles.profile_dir().parent / "launch-presets"
+
+
+def _path(name: str) -> Path:
+ return preset_dir() / f"{slug(name)}.json"
+
+
+def _private_write(path: Path, payload: bytes) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ fd, tmp = tempfile.mkstemp(prefix=".launch-", suffix=".tmp", dir=path.parent)
+ try:
+ with os.fdopen(fd, "wb") as fh:
+ fh.write(payload)
+ fh.flush()
+ os.fsync(fh.fileno())
+ try:
+ os.chmod(tmp, 0o600)
+ except OSError:
+ pass
+ os.replace(tmp, path)
+ finally:
+ if os.path.exists(tmp):
+ os.unlink(tmp)
+ if os.name == "nt":
+ try:
+ from strata_control import private_files
+ private_files.restrict_to_current_user(path, directory=False)
+ except Exception: # noqa: BLE001 - a file the user can read is still theirs
+ pass
+
+
+def now_text() -> str:
+ return time.strftime("%Y-%m-%d %H:%M")
+
+
+def save(settings: LaunchSettings, name: str | None = None) -> LaunchSettings:
+ """Write (or replace) the preset called `name` (default: the settings' own name)."""
+ name = (name or settings.name or "").strip()
+ if not name:
+ raise PresetError("A preset needs a name.")
+ path = _path(name)
+ previous = load(name, missing_ok=True)
+ s = settings.copy(name=name)
+ s.created = (previous.created if previous else None) or s.created or now_text()
+ _private_write(path, (json.dumps(s.to_dict(), indent=2, ensure_ascii=False, sort_keys=True) + "\n").encode("utf-8"))
+ return s
+
+
+def load(name: str, *, missing_ok: bool = False) -> LaunchSettings | None:
+ path = _path(name)
+ try:
+ data = json.loads(path.read_text(encoding="utf-8-sig"))
+ except FileNotFoundError:
+ if missing_ok:
+ return None
+ raise PresetError(f"There is no saved preset called '{name}'." + _near(name)) from None
+ except (OSError, ValueError):
+ raise PresetError(f"The saved preset '{name}' cannot be read. Delete it (strata launch --delete-preset \"{name}\") "
+ "and save it again.") from None
+ if not isinstance(data, dict):
+ raise PresetError(f"The saved preset '{name}' is damaged.")
+ s = LaunchSettings.from_dict(data)
+ s.name = s.name or name
+ return s
+
+
+def _near(name: str) -> str:
+ from strata_cli.launch.settings import closest
+ names = [p.name for p in list_presets() if p.name]
+ near = closest(name, names) if names else None
+ if near:
+ return f" Did you mean '{near}'?"
+ return (" Saved presets: " + ", ".join(names) + ".") if names else " No presets are saved yet."
+
+
+def list_presets() -> list[LaunchSettings]:
+ folder = preset_dir()
+ out: list[LaunchSettings] = []
+ if not folder.is_dir():
+ return out
+ for path in sorted(folder.glob("*.json")):
+ try:
+ data = json.loads(path.read_text(encoding="utf-8-sig"))
+ s = LaunchSettings.from_dict(data)
+ s.name = s.name or path.stem
+ out.append(s)
+ except (OSError, ValueError):
+ continue
+ out.sort(key=lambda s: s.last_used or s.created or "", reverse=True)
+ return out
+
+
+def delete(name: str) -> None:
+ path = _path(name)
+ if not path.is_file():
+ raise PresetError(f"There is no saved preset called '{name}'." + _near(name))
+ path.unlink()
+
+
+def touch_used(name: str) -> None:
+ s = load(name, missing_ok=True)
+ if s is not None:
+ s.last_used = now_text()
+ save(s, name)
+
+
+def summary(s: LaunchSettings) -> dict[str, Any]:
+ """The columns of the start screen."""
+ return {"name": s.name, "model": s.model or ("own files" if s.model_path else "-"),
+ "context": s.context, "parallel": s.parallel, "tuned": bool(s.tuned_preset), "tuned_at": s.tuned_at,
+ "last_used": s.last_used, "access": s.access}
diff --git a/strata_cli/launch/widgets.py b/strata_cli/launch/widgets.py
new file mode 100644
index 000000000..28cc190d2
--- /dev/null
+++ b/strata_cli/launch/widgets.py
@@ -0,0 +1,202 @@
+"""The look of the launch screens: the monitor's colours, rules and key hints, and the one list widget they share.
+
+Colours are the monitor's own (strata_cli/monitor.py: background #0e1113, panel #161a1d, text #eef1f3, muted #8e979f, accent
+#34d399, warning yellow); the launch mock-up adds a selection tint (#1f2a27), a warning amber and a soft red. Everything is plain
+text in a column of lines, as the monitor's text views are: a heading in the accent colour, a dim rule, the content, a dim
+explanation line and a dim line of key hints.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Any
+
+from rich.text import Text
+from textual.widgets import Static
+
+BG, PANEL, FG, MUTE = "#0e1113", "#161a1d", "#eef1f3", "#8e979f"
+ACCENT, WARN, BAD, SEL, RULE = "#34d399", "#f5c56b", "#f28b82", "#1f2a27", "#3a4146"
+
+
+def unicode_ok() -> bool:
+ if os.environ.get("TERM") == "dumb":
+ return False
+ enc = getattr(sys.stdout, "encoding", None) or "utf-8"
+ try:
+ "›─↑↓•█░".encode(enc)
+ return True
+ except (LookupError, UnicodeEncodeError):
+ return False
+
+
+class Glyphs:
+ def __init__(self, unicode: bool | None = None):
+ u = unicode_ok() if unicode is None else unicode
+ self.unicode = u
+ self.cursor = "›" if u else ">"
+ self.rule = "─" if u else "-"
+ self.updown = "↑↓" if u else "Up/Down"
+ self.dot = "·" if u else "-"
+ self.full = "█" if u else "#"
+ self.empty = "░" if u else "."
+ self.tick = "✓" if u else "ok"
+ self.mask = "•" if u else "*"
+ self.arrow = "→" if u else "->"
+
+
+CSS = f"""
+Screen {{ background: {BG}; color: {FG}; }}
+#shell {{ width: 100%; height: 100%; background: {PANEL}; padding: 0 1; }}
+#head {{ height: 1; }}
+#rule1, #rule2 {{ height: 1; color: {RULE}; }}
+#body {{ height: 1fr; }}
+#explain {{ height: auto; max-height: 4; color: {MUTE}; }}
+#hints {{ height: 1; color: {MUTE}; }}
+#message {{ height: 1; color: {MUTE}; }}
+Menu {{ height: auto; max-height: 100%; }}
+.field {{ height: 3; border: solid {ACCENT}; display: none; }}
+.field.open {{ display: block; }}
+Input {{ background: {PANEL}; color: {FG}; }}
+"""
+
+
+@dataclass
+class Cell:
+ text: str
+ style: str = ""
+
+
+@dataclass
+class Item:
+ cells: list[Cell | str]
+ key: Any = None
+ enabled: bool = True
+ style: str = "" # whole-row style when not selected
+
+
+def cell(c: Cell | str) -> Cell:
+ return c if isinstance(c, Cell) else Cell(str(c))
+
+
+class Menu(Static):
+ """A column list with a cursor: `items` is a list of `Item`, `columns` a list of (title, width) (width 0 = the rest)."""
+
+ DEFAULT_CSS = "Menu { height: auto; }"
+
+ def __init__(self, columns: list[tuple[str, int]] | None = None, *, glyphs: Glyphs | None = None, id: str | None = None,
+ window: int = 0) -> None:
+ super().__init__("", id=id, markup=False)
+ self.columns = columns or []
+ self.items: list[Item] = []
+ self.index = 0
+ self.top = 0
+ self.window = window # 0 = show all rows
+ self.g = glyphs or Glyphs()
+ self.show_header = bool(self.columns and any(t for t, _ in self.columns))
+
+ def set_items(self, items: list[Item], index: int | None = None) -> None:
+ self.items = items
+ if index is not None:
+ self.index = index
+ self.index = max(0, min(self.index, len(items) - 1)) if items else 0
+ self._refresh()
+
+ @property
+ def current(self) -> Item | None:
+ return self.items[self.index] if self.items else None
+
+ def move(self, step: int) -> None:
+ if not self.items:
+ return
+ n = len(self.items)
+ i = self.index
+ for _ in range(n):
+ i = (i + step) % n
+ if self.items[i].enabled or not any(it.enabled for it in self.items):
+ break
+ self.index = i
+ self._refresh()
+
+ def select(self, key: Any) -> None:
+ for i, it in enumerate(self.items):
+ if it.key == key:
+ self.index = i
+ self._refresh()
+
+ def page(self, step: int) -> None:
+ self.index = max(0, min(len(self.items) - 1, self.index + step * max(1, (self.window or 8) - 1)))
+ self._refresh()
+
+ def _refresh(self) -> None:
+ win = self.window or len(self.items)
+ if self.index < self.top:
+ self.top = self.index
+ if self.index >= self.top + win:
+ self.top = self.index - win + 1
+ self.top = max(0, min(self.top, max(0, len(self.items) - win)))
+ self.update(self.build())
+
+ def build(self) -> Text:
+ out = Text(no_wrap=True, overflow="crop")
+ pad = " "
+ widths = [w for _t, w in self.columns]
+ if self.show_header:
+ out.append(pad)
+ for (title, w) in self.columns:
+ out.append(title.ljust(w) if w else title, style="bold")
+ out.append("\n")
+ win = self.window or len(self.items)
+ rows = self.items[self.top:self.top + win]
+ for n, it in enumerate(rows):
+ selected = (self.top + n) == self.index
+ line = Text(no_wrap=True, overflow="crop")
+ line.append((self.g.cursor + " ") if selected else pad, style=f"bold {ACCENT}" if selected else "")
+ for k, c in enumerate(it.cells):
+ c = cell(c)
+ w = widths[k] if k < len(widths) else 0
+ txt = c.text.ljust(w) if w else c.text
+ style = c.style if not selected else (c.style if c.style and not selected else "")
+ if selected:
+ style = f"bold {ACCENT}" if c.style in ("", None) else c.style
+ elif not c.style and it.style:
+ style = it.style
+ if not it.enabled and not selected:
+ style = MUTE
+ line.append(txt, style=style)
+ if selected:
+ line.stylize(f"on {SEL}")
+ line.pad_right(max(0, (self.size.width or 100) - len(line.plain)))
+ line.stylize(f"on {SEL}")
+ out.append_text(line)
+ if n < len(rows) - 1:
+ out.append("\n")
+ if self.window and len(self.items) > win:
+ out.append(f"\n {self.top + 1}-{min(len(self.items), self.top + win)} of {len(self.items)}", style=MUTE)
+ return out
+
+ def on_resize(self, _event) -> None:
+ self._refresh()
+
+
+def heading(text: str) -> Text:
+ return Text(text, style=f"bold {ACCENT}")
+
+
+def muted(text: str) -> Text:
+ return Text(text, style=MUTE)
+
+
+def warn(text: str) -> Text:
+ return Text(text, style=WARN)
+
+
+def bad(text: str) -> Text:
+ return Text(text, style=BAD)
+
+
+def bar(fraction: float, width: int, g: Glyphs) -> str:
+ fraction = max(0.0, min(1.0, fraction))
+ full = int(round(fraction * width))
+ return g.full * full + g.empty * (width - full)