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: docs (TERMINAL_LAUNCH.md), installer tests, plain GGUF issue words

Niko1221dc1aa5030a07
diff --git a/docs/TERMINAL.md b/docs/TERMINAL.md
index f7c1bc634..de0c1b8ad 100644
--- a/docs/TERMINAL.md
+++ b/docs/TERMINAL.md
@@ -1,5 +1,7 @@
# Strata terminal commands (implementation in progress)
+`strata launch` (guided setup, serve and monitor) and `strata connect` (setup for your coding apps): see [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md).
+
For the shortest path through the source-checkout commands, use the [terminal quick start](TERMINAL_QUICKSTART.md).
This checkout adds a source-run terminal entry point beside the existing server:
diff --git a/docs/TERMINAL_LAUNCH.md b/docs/TERMINAL_LAUNCH.md
new file mode 100644
index 000000000..9c048a1bc
--- /dev/null
+++ b/docs/TERMINAL_LAUNCH.md
@@ -0,0 +1,81 @@
+# `strata launch`: set up, serve and watch, in the terminal
+
+One command for the whole path: choose a model, tune it, start serving, and watch it. It is the same questions as the one-click setup (`START-HERE.bat` / `setup.sh`),
+in the Terminal's look, with presets, an Advanced table, an access choice and a Connect view for your coding apps. Text previews of every screen are in
+[docs/terminal-previews/](terminal-previews/) (`launch-*.txt`).
+
+## Install (one line)
+
+```sh
+curl -fsSL <release-folder>/install.sh | sh # Linux, macOS
+irm <release-folder>/install.ps1 | iex # Windows PowerShell
+```
+
+It finds out which computer this is, downloads the Terminal archive named in the release folder's `install-manifest.txt`, checks its SHA-256, unpacks it into your
+home (`~/.local/share/strata/terminal`, `%LOCALAPPDATA%\Strata\terminal`; no administrator rights), checks the release's signed feed with the Terminal it just unpacked
+(`strata update --check`; if that fails it removes what it unpacked), puts `strata` on your PATH and prints `Installed. Run: strata launch`. The engine (the part that talks
+to your graphics card) comes with the first model: `strata launch` fetches the one for your card from the same release folder, signed, and test-starts it before using it.
+`<release-folder>` is where the release is hosted (not decided yet: set `STRATA_FEED` to try a local one; `packaging/make_local_feed.py` builds a test-signed one).
+
+## The screens (`strata launch`)
+
+1. **Start**: saved presets (name, model, context, parallel requests, tuned or not, last used) or "Set up from the beginning" or "Use model files I already have".
+2. **Model**: the catalog of the app and `setup.py` (one source), with download size, what it needs (graphics memory + RAM) and "fits / tight / does not fit this computer".
+ A warning, never a block. The n-gram table stays on your SSD and is not counted. `o` = your own files (a folder or a .gguf; checked with the fingerprint table).
+ *(Cards: only with two or more usable graphics cards.)*
+3. **Folder**: where model files are stored, free space shown.
+4. **Context** (8K to 512K, with the extra memory each costs) and the memory format (`m`: 8-bit or 4-bit).
+5. **Pictures**: only for models that can read them; says what it adds.
+6. **Parallel requests**: "fit to your card" (12 GB: 1, 20: 2, 24: 3, 32+: 4) or 1 to 4; a warning if it will not fit.
+7. **Tuning**: quick (about 20 minutes) / thorough (up to 2 hours) / skip (`strata tune auto`; the "answers may change very slightly" tick is off).
+8. **Advanced** (optional): every engine setting with default, tuned value and your value; edit, reset, add a setting by name (checked against the engine's own list; a warning, not a refusal);
+ the exact command and the matching `strata launch` flags.
+9. **Access**: this computer only (127.0.0.1), your network (LAN address, key), Cloudflare quick tunnel (needs `cloudflared`), Tailscale (needs it installed and connected); port; API key
+ (made for you beyond this computer: the server will not start on a network without one).
+10. **Save as preset** and launch. Then downloads (with progress), engine start, and the monitor.
+
+Keys: arrows choose, Enter goes on, Esc goes back, `?` explains the screen, `q` leaves. Every screen says in plain words what it means and what to do next.
+
+## After the start: the monitor
+
+The Strata Monitor with the new **Overview** (key 1: model state bar, speed, GPU load, VRAM, temperature, power, PCIe, CPU, disk, context fill, experts in VRAM, system RAM, recent requests; read from the
+server's `/metrics`, the same data as the browser Monitor), the other five views as before, and **7 Connect**: the address, the key (hidden until `k`), and the setup for each app
+(`c` copy, `w` write it for you after a backup, `h` check it: one prompt and one tool call sent the way that app sends them). `q` asks: keep serving in the background, or stop
+(stopping unloads the model and frees the graphics memory).
+
+In the classic Windows console (Consolas) the monitor draws ASCII sparklines and square corners instead of block glyphs the font does not have (`STRATA_GLYPHS=unicode|ascii` forces either).
+
+## Without the screens (flags)
+
+```sh
+strata launch --preset "IQ3_XXS 128K" # 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 # serve and print the address
+strata launch --model-path /data/models/IQ3_XXS --no-tui # files you already have
+strata launch --preset Office --set prefill=65536 --set STRATA_PIN_BY_NEED=1 --no-tui
+strata launch --plan --model q2_0 # what would happen; nothing changes
+strata launch --list-presets | --delete-preset NAME | --status | --stop [--preset NAME] | --show-key
+```
+
+`strata launch --help` lists everything with examples. An unknown model or flag gets a plain message with the closest match. Presets are small files in `launch-presets/` beside the profiles
+folder; the run uses the shared profile `launch-<name>` and the shared tuning presets (`strata presets`), so the app sees them too. Flags next to `--preset` change that start only
+(add `--save-preset` to keep them).
+
+## Connect your apps: `strata connect`
+
+`strata connect` lists OpenCode, Codex CLI, Claude Code, oh-my-pi (omp), pi, Hermes Agent, OpenClaw and the DeepSeek Harness (built into the app). `strata connect opencode` prints the file and
+environment for the running server (address, key, model name and context filled in); `--write` writes it after asking and keeps a backup of anything it replaces; `--check` sends one prompt and one tool call
+the way that app does and says whether each worked. Each configuration was tested for real against a Strata server at 32K context (the app versions are on screen); the known limits are printed in plain
+words (for example: Claude Code needs `CLAUDE_CODE_MAX_CONTEXT_TOKENS`; OpenCode needs `limit.input`; Hermes refuses windows under 64K unless set up as the config does; OpenClaw needs Node 24.16+).
+
+## Boxes the installer cannot set up
+
+`setup.py` sets up NVIDIA (CUDA) and AMD (HIP) cards. For an Intel Arc card its Linux path is a container build that the Terminal does not run: if the model's files and their prepared pack are
+already on the disk, `strata launch` writes the run settings itself and says so; otherwise it says which file is missing. Nothing is downloaded or compiled in that case.
+
+## Limits
+
+* The model download uses `setup.py` in its control mode (no pip, no engine fetch, no compiler), as the desktop app does; it needs internet and room for the files.
+* `strata update`'s test start of an engine runs `<engine> --version`; the SYCL (Intel) package's engine does not answer that flag (exit 2), so on an Intel box the engine package has to be copied into the
+ components folder until that is fixed.
+* The Windows console has no way for the test scripts to drive the screens; they were checked by pilot tests and by hand.
diff --git a/docs/TERMINAL_QUICKSTART.md b/docs/TERMINAL_QUICKSTART.md
index 3ddd23d19..12fdf2f86 100644
--- a/docs/TERMINAL_QUICKSTART.md
+++ b/docs/TERMINAL_QUICKSTART.md
@@ -1,5 +1,7 @@
# Terminal quick start (source checkout)
+New here? `strata launch` sets up a model, serves it and opens the monitor in one guided flow: [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md).
+
These commands describe the current `Strata-TUI-CLI` development branch. Run them from the repository root with the Python environment used for Strata. Substitute `python3` on systems without a `python` command. They do not install a model or change the existing one-click setup path. The complete options, permissions and limits are in [TERMINAL.md](TERMINAL.md).
## Read a running server
diff --git a/packaging/package_terminal.py b/packaging/package_terminal.py
index 10b1ec331..98842291a 100644
--- a/packaging/package_terminal.py
+++ b/packaging/package_terminal.py
@@ -451,11 +451,14 @@ Install
What it does NOT include
------------------------
The **engine** is a separate, independently versioned component and is not bundled: the right engine package
-depends on your OS, CPU and GPU. Install one with SETUP / `strata install` from a full Strata folder, or point
-Strata at one with STRATA_ENGINE. Model weights are likewise not included.
+depends on your OS, CPU and GPU. `strata launch` (or `strata update`) fetches the one for your card from the signed
+release feed; or point Strata at one with STRATA_ENGINE. Model weights are likewise not included: `strata launch`
+downloads the one you choose (the installer files setup.py and tools/ are in this archive for that).
Useful commands
---------------
+ strata launch choose a model, tune it, serve it and watch it (guided screens; docs/TERMINAL_LAUNCH.md)
+ strata connect opencode the setup for a coding app on the running server (also codex, claude-code, omp, pi, hermes, openclaw)
strata --version the version and the interpreter it runs on
strata doctor read-only component inventory
strata profile list saved serving profiles
diff --git a/strata_cli/launch/runner.py b/strata_cli/launch/runner.py
index d57906e89..ea106453f 100644
--- a/strata_cli/launch/runner.py
+++ b/strata_cli/launch/runner.py
@@ -656,7 +656,19 @@ ISSUE_WORDS = {
def plain_issue(code: str) -> str:
- return ISSUE_WORDS.get(code, code.replace("_", " "))
+ """One problem from the GGUF preview, in words (it may be `file.gguf: GGUF shard is not a nonempty regular file` and the like)."""
+ if code in ISSUE_WORDS:
+ return ISSUE_WORDS[code]
+ low = code.lower()
+ if "not a nonempty regular file" in low or "unreadable" in low:
+ return "a file is empty, unreadable or not a regular file"
+ if "does not begin with a gguf header" in low or "header version" in low:
+ return "a file is not a GGUF model file"
+ if "unsupported_architecture" in low:
+ return "this is not a model Strata can run"
+ if "symlink" in low:
+ return "a file is a shortcut (symbolic link); point at the real file"
+ return code.replace("_", " ")
def _read_json(path: Path) -> dict | None:
diff --git a/tests/terminal/test_launch_install.py b/tests/terminal/test_launch_install.py
new file mode 100644
index 000000000..3a638d3e7
--- /dev/null
+++ b/tests/terminal/test_launch_install.py
@@ -0,0 +1,133 @@
+"""The one-line installers and the local test feed: syntax, the placeholder guard, the feed builder, and (POSIX) a real install.sh run against a feed."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import threading
+import unittest
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "packaging"))
+
+
+class Scripts(unittest.TestCase):
+ def test_install_sh_syntax_and_guard(self):
+ sh = shutil.which("sh") or shutil.which("bash")
+ if not sh:
+ self.skipTest("no sh")
+ r = subprocess.run([sh, "-n", str(ROOT / "packaging" / "install.sh")], capture_output=True, text=True)
+ self.assertEqual(r.returncode, 0, r.stderr)
+ text = (ROOT / "packaging" / "install.sh").read_text(encoding="utf-8")
+ self.assertEqual(text.count("__FEED__"), 1) # the baked address replaces only the default; the guard survives
+ self.assertIn("Installed. Run: ", text)
+ self.assertNotIn("\r", text)
+
+ def test_install_ps1_parses_and_guard(self):
+ text = (ROOT / "packaging" / "install.ps1").read_text(encoding="utf-8")
+ self.assertEqual(text.count("__FEED__"), 1)
+ self.assertIn("Installed. Run: strata launch", text)
+ ps = shutil.which("powershell") or shutil.which("pwsh")
+ if not ps:
+ self.skipTest("no PowerShell")
+ cmd = ("$e=$null; $t=$null; [System.Management.Automation.Language.Parser]::ParseFile('%s',[ref]$t,[ref]$e) | Out-Null; "
+ "if ($e.Count) { $e | ForEach-Object { $_.Message }; exit 1 } else { 'ok' }" % str(ROOT / "packaging" / "install.ps1").replace("'", "''"))
+ r = subprocess.run([ps, "-NoProfile", "-Command", cmd], capture_output=True, text=True)
+ self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+
+ def test_a_script_without_an_address_says_what_to_do(self):
+ sh = shutil.which("sh") or shutil.which("bash")
+ if not sh or os.name == "nt":
+ self.skipTest("POSIX sh only")
+ env = {k: v for k, v in os.environ.items() if k != "STRATA_FEED"}
+ r = subprocess.run([sh, str(ROOT / "packaging" / "install.sh")], capture_output=True, text=True, env=env)
+ self.assertNotEqual(r.returncode, 0)
+ self.assertIn("Set STRATA_FEED", r.stderr)
+
+
+class Feed(unittest.TestCase):
+ def make_bundle(self, work: Path) -> Path:
+ """A tiny terminal archive that is a working `strata` (the repo's own source with the system Python)."""
+ top = work / "bundle" / "strata-terminal-9.9.9-linux-x86_64"
+ top.mkdir(parents=True)
+ for name in ("strata.py", "strata_cli", "strata_control", "serve"):
+ src = ROOT / name
+ (shutil.copytree(src, top / name, ignore=shutil.ignore_patterns("__pycache__", "*.pyc")) if src.is_dir() else shutil.copy2(src, top / name))
+ (top / "bin").mkdir(parents=True, exist_ok=True)
+ shutil.copy2(ROOT / "bin" / "strata", top / "bin" / "strata")
+ (top / "bin" / "strata").chmod(0o755)
+ (top / "VERSION").write_text("9.9.9\n", encoding="utf-8")
+ archive = work / "strata-terminal-9.9.9-linux-x86_64.tar.gz"
+ with tarfile.open(archive, "w:gz") as tf:
+ tf.add(top, arcname=top.name)
+ return archive
+
+ def test_make_local_feed_and_a_real_install(self):
+ import make_local_feed
+ with tempfile.TemporaryDirectory() as tmp:
+ work = Path(tmp)
+ archive = self.make_bundle(work)
+ feed = work / "feed"
+ rc = make_local_feed.main(["--out", str(feed), "--terminal", str(archive), "--keys", str(work / "keys"), "--url", "http://127.0.0.1:1"])
+ self.assertEqual(rc, 0)
+ for name in ("strata-feed.json", "strata-feed.json.sig", "install-manifest.txt", "install.sh", "install.ps1", "test-trust.json"):
+ self.assertTrue((feed / name).is_file(), name)
+ line = (feed / "install-manifest.txt").read_text().split()
+ self.assertEqual(line[0], "linux-x86_64")
+ self.assertEqual(line[1], "9.9.9")
+ control = feed / line[2]
+ self.assertEqual(hashlib.sha256(control.read_bytes()).hexdigest(), line[3])
+ self.assertEqual(control.stat().st_size, int(line[4]))
+ sh_text = (feed / "install.sh").read_text()
+ self.assertIn("http://127.0.0.1:1", sh_text)
+ self.assertIn('"__FE""ED__"', sh_text) # the guard was not rewritten
+ self.assertIn("Installed. Run:", (feed / "install.ps1").read_text())
+ doc = json.loads((feed / "strata-feed.json").read_text())
+ self.assertEqual(doc["control"]["packages"][0]["sha256"], line[3])
+ self.assertNotIn("seed", (feed / "test-trust.json").read_text()) # only the public key is published
+ if os.name == "nt" or not (shutil.which("sh") and shutil.which("curl") and shutil.which("tar")):
+ self.skipTest("the real install.sh run needs POSIX sh, curl and tar")
+ handler = partial(SimpleHTTPRequestHandler, directory=str(feed))
+ handler.log_message = lambda *a, **k: None # type: ignore[attr-defined]
+ server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+ try:
+ url = f"http://127.0.0.1:{server.server_address[1]}"
+ home = work / "home"
+ home.mkdir()
+ env = {**os.environ, "HOME": str(home), "STRATA_FEED": url, "STRATA_INSTALL_TEST_TRUST": "1", "STRATA_PYTHON": sys.executable,
+ "PATH": os.environ["PATH"], "STRATA_NO_ACQUIRE": ""}
+ for k in ("XDG_DATA_HOME", "STRATA_UPDATE_TRUSTED_KEYS"):
+ env.pop(k, None)
+ r = subprocess.run(["sh", str(feed / "install.sh")], capture_output=True, text=True, env=env, timeout=240)
+ self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+ self.assertIn("Checksum ok", r.stdout)
+ self.assertIn("Signature ok", r.stdout)
+ self.assertIn("Installed. Run:", r.stdout)
+ self.assertTrue((home / ".local" / "bin" / "strata").exists())
+ v = subprocess.run([str(home / ".local" / "bin" / "strata"), "--version"], capture_output=True, text=True, env=env, timeout=60)
+ self.assertEqual(v.returncode, 0, v.stderr)
+ # a damaged download is refused and nothing is installed
+ data = (feed / line[2]).read_bytes()
+ (feed / line[2]).write_bytes(data[:-10] + b"x" * 10)
+ home2 = work / "home2"
+ home2.mkdir()
+ r = subprocess.run(["sh", str(feed / "install.sh")], capture_output=True, text=True, env={**env, "HOME": str(home2)}, timeout=240)
+ self.assertNotEqual(r.returncode, 0)
+ self.assertIn("does not match the release's checksum", r.stderr)
+ self.assertFalse((home2 / ".local" / "share" / "strata" / "terminal" / "9.9.9").exists())
+ finally:
+ server.shutdown()
+
+
+if __name__ == "__main__":
+ unittest.main()