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++

0.2.0 text, group 3: Terminal docs (installed command, seven views, release address, connect --check json), Docker, packaging, SECURITY, issue and PR templates, test requests, historical Terminal pages

Niko122114ec155ec779
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 38aca0588..53dd1bb52 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -5,33 +5,81 @@ labels: ["bug"]
body:
- type: markdown
value: |
- Thanks for the report.
+ Thanks for the report. Please read [CONTRIBUTING.md](https://github.com/Niko1221/Strata/blob/main/CONTRIBUTING.md) first.
- Please search the [open issues](https://github.com/Niko1221/Strata/issues?q=is%3Aissue+state%3Aopen) first — this may already be tracked.
+ Search the [open and closed issues](https://github.com/Niko1221/Strata/issues?q=is%3Aissue) first: this may already be tracked, and new evidence belongs in that thread.
+
+ Write only what you saw. Do not guess at steps, errors, hardware or severity.
+ - type: dropdown
+ id: how
+ attributes:
+ label: Desktop app, Terminal or source?
+ options:
+ - Desktop app (Windows, Linux or Mac)
+ - Terminal (the `strata` command)
+ - Source (START-HERE.bat, setup.sh or a build)
+ - Docker
+ - Other
+ validations:
+ required: true
- type: textarea
id: what
attributes:
label: What happened
- description: What you did, what you got, and what you expected instead. Paste the exact error text if there is one. If there's a set of steps or commands that reproduces it, put them here too.
+ description: What you did, what you got, and what you expected instead. Paste the exact error text if there is one.
+ validations:
+ required: true
+ - type: textarea
+ id: reproduce
+ attributes:
+ label: Smallest steps or command that reproduce it
+ description: The shortest list of steps that shows the problem. If you cannot make it happen again, say so here.
+ validations:
+ required: false
+ - type: dropdown
+ id: reproduction-status
+ attributes:
+ label: Reproduction status
+ options:
+ - Reproduced locally
+ - Unconfirmed static analysis (I read code or ran a scanner; I did not see it fail)
+ validations:
+ required: true
+ - type: input
+ id: version
+ attributes:
+ label: Strata version
+ description: "In the app: Settings > About. In the Terminal: `strata --version`. From source: the About tab of the web page, or `engine` in `GET /v1/status`, or the git commit."
+ placeholder: "Strata 0.2.0-beta · engine 0.1.45.3"
validations:
required: true
- type: input
id: hardware
attributes:
- label: Strata version, GPU, OS
- description: The engine version is on the About tab, or in `GET /v1/status` under `engine`.
- placeholder: "0.1.31 · RTX 5070 12GB · Windows 11"
+ label: Graphics card, memory and system
+ description: The card and its VRAM, the RAM of the PC, and the operating system.
+ placeholder: "RTX 5070 12 GB · 64 GB RAM · Windows 11"
validations:
required: true
+ - type: input
+ id: model
+ attributes:
+ label: Model, size and settings
+ description: The model and size you started, the context, and whether pictures were on. Write what is relevant.
+ placeholder: "Qwen3.8-Flash-Next IQ2_XS · 128K context · pictures on"
+ validations:
+ required: false
- type: textarea
id: log
attributes:
- label: Engine log
- description: Drag in `strata-<model>.log` from your Strata folder. Drag and drop works directly into this box.
+ label: Logs
+ description: |
+ The app: Settings > Engine > Diagnostics > View logs > Save logs, then drag the file in. The Terminal: paste the output of `strata doctor`. From source: drag in `strata-<model>.log` from your Strata folder.
+ Remove API keys, passwords and private text first.
validations:
required: false
- type: markdown
value: |
A couple of extras that help a lot:
- - Check the [troubleshooting table](https://github.com/Niko1221/Strata/blob/main/docs/DETAILS.md#troubleshooting) first, many reports are already solved there.
\ No newline at end of file
+ - Check the [troubleshooting page](https://github.com/Niko1221/Strata/blob/main/docs/TROUBLESHOOTING.md) first, many reports are already solved there.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 4c763b2ac..be9cdf2e9 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,5 +1,5 @@
blank_issues_enabled: true
contact_links:
- name: Troubleshooting and known issues
- url: https://github.com/Niko1221/Strata/blob/main/docs/DETAILS.md#troubleshooting
+ url: https://github.com/Niko1221/Strata/blob/main/docs/TROUBLESHOOTING.md
about: Symptom-to-fix table for crashes, out of memory, hangs, and port problems.
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 2754274d9..445a3cd65 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -5,14 +5,21 @@ labels: ["enhancement"]
body:
- type: markdown
value: |
- Explain what you want in plain language.
+ Explain what you want in plain language. For a large feature, a change to a default or a refactor, please agree the scope here first. Read [CONTRIBUTING.md](https://github.com/Niko1221/Strata/blob/main/CONTRIBUTING.md).
- type: textarea
id: idea
attributes:
label: What do you want to do?
- description: Describe the goal rather than the implementation. If there's a workaround you use today, mention it.
+ description: Describe the goal rather than the implementation. Say who needs it and why.
validations:
required: true
+ - type: textarea
+ id: workaround
+ attributes:
+ label: What do you do today instead?
+ description: The workaround you use now, if there is one.
+ validations:
+ required: false
- type: markdown
value: |
- All of this counts: model and architecture support, the server and API, the web app, multi-GPU and layer split, images and vision, MCP servers, setup and installation, and performance.
\ No newline at end of file
+ All of this counts: model and architecture support, the server and API, the app and the Terminal, multi-GPU and layer split, images and vision, MCP servers, setup and installation, and performance.
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
index de8ef8683..0e5279b5b 100644
--- a/.github/ISSUE_TEMPLATE/question.yml
+++ b/.github/ISSUE_TEMPLATE/question.yml
@@ -5,7 +5,7 @@ labels: ["question"]
body:
- type: markdown
value: |
- Not sure how to do something, or want to share numbers from your machine? Ask here.
+ Not sure how to do something, or want to share numbers from your machine? Ask here. To share a full benchmark, see [CONTRIBUTING.md](https://github.com/Niko1221/Strata/blob/main/CONTRIBUTING.md#share-a-benchmark).
- type: textarea
id: question
attributes:
@@ -13,10 +13,17 @@ body:
description: What you're trying to do. Include your version, GPU, and OS if it affects the answer.
validations:
required: true
+ - type: textarea
+ id: tried
+ attributes:
+ label: What you tried
+ description: What you already did and where you got stuck.
+ validations:
+ required: false
- type: textarea
id: numbers
attributes:
label: Results (optional)
description: Only if you ran a benchmark or measured speed. Model, quant, context, and the tok/s you get.
validations:
- required: false
\ No newline at end of file
+ required: false
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index b8bef3fb4..04219a98d 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,12 +1,28 @@
-## Title
-<!-- If Applicable, reference the GitHub issue -->
-Issue: Resolves #
+<!--
+Read CONTRIBUTING.md first. Lead with the problem and the result, not a file-by-file list.
+Placeholders below are not test results: replace them with what you observed, or write "none".
+-->
-## Summary
-<!-- Quick Summary of changes -->
+## Problem and result
+<!-- What triggered this change. How it behaves before and after. -->
-## What changed
-<!-- Specifics on files changed, and what changes were made there -->
+## Related discussion
+<!-- The issue URL and the maintainer's agreement on scope, when the change needs one (features, refactors, defaults). Write "none" if not applicable. -->
-## Extra Notes
-<!-- Any extra notes, delete if there are none -->
+## Approach
+<!-- Why this fix. Compatibility effects. Keep unrelated cleanup out of the PR. -->
+
+## Validation
+<!-- Exact commands, the revision and the environment tested, what you saw. Keep the three lists apart. -->
+
+**Passed:**
+<!-- command, revision/environment, observed result, log -->
+
+**Failed:**
+<!-- command and failure, or "none observed" -->
+
+**Not run:**
+<!-- check, why, and what stays unverified (for example CUDA, HIP, SYCL or Metal builds you could not do) -->
+
+## Limits
+<!-- Known limitations or remaining work. -->
diff --git a/SECURITY.md b/SECURITY.md
index 476dab975..b279eeebc 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -43,4 +43,52 @@ this PC only. The details and every setting are in [docs/DETAILS.md](docs/DETAIL
last few prompts, whatever `"api_monitor"` says, to encode the next turn faster; no endpoint shows them, and they
are gone when the server stops.
+## The desktop app and the Terminal
+
+Strata comes in three parts that share one engine: the **desktop app**, the **Terminal** (`strata`) and the **engine** that runs
+the model. The section above is about the engine's HTTP server. This is what the other two add.
+
+- **The app's host listens on this PC only.** The app serves its page from a local host process on `127.0.0.1` (port 8791 unless
+ changed). A request to its `/api/` endpoints that carries a browser `Origin` from any other site gets 403. The app shell holds a
+ random secret (32 characters or more, compared in constant time) that is needed to quit the host or tell it which window is open,
+ and the host gives its own helper processes a second random secret. By default the models the app starts are served on this PC only.
+- **Sharing is a separate, key-protected listener.** "Share with other devices" (and the Cloudflare tunnel) will not start until an
+ API key is set. It opens a different listener that answers only `/v1/models`, `/v1/chat/completions` and `/v1/messages`, never the
+ app's page or its host endpoints.
+- **App and Terminal talk through an owner channel.** One owner process per installation starts and ends the engine, and a second
+ client (the Terminal) attaches to it. On macOS and Linux that is a private Unix socket in a folder only you can open. On Windows it
+ is a TCP listener on `127.0.0.1` that answers only requests carrying a 256-bit token kept in an owner-only folder. That is a weaker
+ guarantee than a socket other users cannot open: on Windows the token is what protects it, as with any loopback service that has a
+ token (`strata_control/owner_transport.py`). The bridge between the app shell and the host (used for the app update) is also loopback and protected by a token.
+- **Starting a model and serving never download anything.** Downloads and updates are one explicit step: `strata update`, or "Update
+ engine" and "Update Strata" in the app's Settings. Models and saved tuning are never replaced by an update.
+- **Updates come from a signed feed.** The release publishes `strata-feed.json` and `strata-feed.json.sig` (Ed25519). An installed
+ Strata checks the signature against the public key it carries (`strata_control/update_keys.json`), refuses a feed older than the last
+ one it accepted (a replayed old feed) or expired, and checks every engine package against its SHA-256, its signed manifest and the
+ card in your PC before it test-starts it and switches to it. Any failure keeps the engine you had. The app installer itself is signed
+ with a separate key (Tauri's minisign key) that the app and the Terminal both check. The private keys are kept offline by the owner.
+ See [packaging/UPDATES.md](packaging/UPDATES.md).
+
+### How far to trust `curl | sh` and `irm | iex`
+
+The Terminal installs with one line:
+
+```sh
+curl -fsSL https://github.com/Niko1221/Strata/releases/latest/download/install.sh | sh
+irm https://github.com/Niko1221/Strata/releases/latest/download/install.ps1 | iex
+```
+
+Piping a script into a shell runs whatever the server sends, so it deserves the same care as running any downloaded program.
+What the script does is short and written at its top: it fetches the Terminal archive named in the release's `install-manifest.txt`,
+checks its SHA-256, unpacks it into your home folder (no administrator rights, nothing outside your home), checks the release's signed feed
+with the Terminal it just unpacked and removes it again if that fails, and puts `strata` on your PATH.
+
+Know the limit of those checks. The checksum comes from the same release as the archive, and the public key that checks the feed arrives inside
+that archive, so for the **first** install all trust rests on HTTPS and on the `Niko1221/Strata` GitHub release itself. The checks catch a
+damaged or half-finished download and a feed that was not signed by the release key; they do not protect you if the release has been replaced
+by someone who controls it. Later updates are checked against the key already on your PC, which is a stronger position.
+
+If that is not enough for you: save the script (`curl -fsSLO https://github.com/Niko1221/Strata/releases/latest/download/install.sh`), read it, and
+run it from the file; or install the desktop app or build from source instead and check the code you build.
+
Strata has not had an outside security audit yet.
diff --git a/docs/COMMUNITY_BENCHMARKS.md b/docs/COMMUNITY_BENCHMARKS.md
index 4c88ca287..60f35190a 100644
--- a/docs/COMMUNITY_BENCHMARKS.md
+++ b/docs/COMMUNITY_BENCHMARKS.md
@@ -5,6 +5,8 @@ might run on a similar machine. This guide suggests a report format and a pull
request workflow; a single model, GPU, or context length is enough to contribute.
The quickest way is the built-in benchmark: [`BENCH.bat` / `./bench.sh`](#run-the-benchmark) writes a report in this format.
+A standard benchmark protocol for future submissions exists only as a **draft**: [BENCHMARK_PROTOCOL.md](BENCHMARK_PROTOCOL.md). The tools described on this page do not implement it, and the reports below are not standard results; keep using this guide for now.
+
Existing [benchmark reports](../bench/results/) provide examples. The
[engine 0.1.26 speed report](../bench/results/2026-09-29-speed-0126/README.md)
includes hardware, settings, and per-run JSON. The
@@ -71,7 +73,8 @@ and their limits. Report what you actually measured and label estimates separate
The simplest report is one command after setup. Windows: double-click `BENCH.bat`. Linux: `./bench.sh`. Or
`python tools/strata_bench.py` from the Strata folder. Setup also offers it at the end of an interactive install
-(default no).
+(default no). The Terminal's `strata bench run` ([TERMINAL.md](TERMINAL.md)) is a different tool: it measures serving suites and
+writes JSON evidence for your own comparisons, but not the `README.md` report in this format and not the draft standard protocol.
It starts the model with the settings you already have (the newest `strata-*.json`; `--config FILE` picks another one),
or uses a Strata server that is already running on that port (`--url http://127.0.0.1:8080` for another address). It then
diff --git a/docs/DEVELOPER_INTEGRATION_HANDOFF.md b/docs/DEVELOPER_INTEGRATION_HANDOFF.md
index c226ea4a5..9914b30c1 100644
--- a/docs/DEVELOPER_INTEGRATION_HANDOFF.md
+++ b/docs/DEVELOPER_INTEGRATION_HANDOFF.md
@@ -1,5 +1,7 @@
# Strata developer integration handoff
+> **Historical record (11 October 2026).** This page was written while the Terminal was being built, before Strata 0.2.0. It is kept for the record and is not kept up to date: it describes six views, source-run commands and checks that had not yet been run on target hardware. For what the Terminal does now, see [TERMINAL.md](TERMINAL.md), [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md) and [TERMINAL_QUICKSTART.md](TERMINAL_QUICKSTART.md).
+
11 October 2026 - execution brief for joining the current Strata engine, Desktop UI, serving CLI, monitor TUI and coding harness.
**Purpose.** The developer should use the current UI handover zip, the owner's forthcoming DeepSeek harness repository and TUI zip, and the current GitHub repository to deliver one working product. This document adds the missing operator workflow: editable ways to restart a model, calibrate the engine, verify components and repeat a serving setup. Read it with `strata-development-work-plan.md`, `strata-architecture-plan.md` and `strata-terminal-implementation-plan.md`. Their release, security, model support and hardware gates still apply.
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index cabfa06f5..fbe0d2843 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -24,16 +24,15 @@ Docker on a **Mac** has no access to the Mac's graphics chip (no Metal): use the
| AMD **RX 7000** series (RDNA 3, gfx1100 / gfx1101 / gfx1102) | `0.2.0-rocm-gfx110x` | the `amdgpu` kernel driver |
| Intel **Arc** A-series and B-series (including Arc Pro B70) | `0.2.0-sycl` | the `i915` or `xe` kernel driver; **prepared model files** (see [Intel](#intel-arc)) |
-Size of the images (0.1.45 packages as measured; the 0.2.0 ones will differ a little): `cuda13` 640 MB download / 2.0 GB on disk, `cuda12`
+Size of the images (0.1.45 packages as measured; 0.2.0 ones may differ a little): `cuda13` 640 MB download / 2.0 GB on disk, `cuda12`
845 MB / 2.6 GB, `rocm-gfx120x` 505 MB / 2.2 GB, `rocm-gfx110x` 330 MB / 1.6 GB, `sycl` 450 MB / 1.9 GB. The model comes on top, on the first start.
Not sure which NVIDIA image? Take `cuda13` when `nvidia-smi` shows driver 580 or newer and the card is an RTX; otherwise `cuda12`.
A wrong pick does no harm: the container starts, says in plain words that the engine does not fit this card, and stops.
-TODO(owner): where the images are published (registry and names). The plan, to decide at the 0.2.0 release:
-`ghcr.io/niko1221/strata:0.2.0-cuda13`, `:0.2.0-cuda12`, `:0.2.0-rocm-gfx120x`, `:0.2.0-rocm-gfx110x`, `:0.2.0-sycl`, plus a
-moving `:cuda13` / `:cuda12` / `:rocm-gfx120x` / `:rocm-gfx110x` / `:sycl` per card for "the newest". Until then,
-[build them yourself](#build-it-yourself); the examples below use the plan's names.
+**Ready-made images are not available yet.** No image has been published, so [build one yourself](#build-it-yourself) (one command
+per card, from the engine package). The examples below name the images `ghcr.io/niko1221/strata:0.2.0-cuda13` and so on, after the
+tags in the table; if you built the image yourself, use the tag you gave it (for example `strata:0.2.0-cuda13`) in their place.
## One command per card
@@ -187,7 +186,7 @@ The health check asks `GET /v1/models` with the key. During the first download t
## Updating
```sh
-docker pull ghcr.io/niko1221/strata:0.2.0-cuda13 # the new tag (TODO(owner): registry)
+docker pull ghcr.io/niko1221/strata:0.2.0-cuda13 # the new tag (not available yet; with a self-built image, build it again instead)
docker stop strata && docker rm strata
# run the same docker run command again with the new tag (compose: docker compose pull && docker compose up -d)
```
@@ -260,8 +259,8 @@ the old model folder. The container name, the volume and the port can stay as th
## Build it yourself
-You do not need to: the engine packages are published with the release. If you want to build the images (for a computer without
-registry access, or after changing Strata), you need an engine package folder (made by `packaging/package_engine.py`, or fetched
+Until ready-made images are available this is the way to get one, and it stays the way for a computer without
+registry access or after changing Strata. You need an engine package folder (made by `packaging/package_engine.py`, or fetched
by `strata update` into a components folder) and Docker on Linux:
```sh
@@ -284,7 +283,7 @@ builds from source see [AMD_HIP.md](AMD_HIP.md) and [INTEL.md](INTEL.md); then p
## Tested
-2026-10-17, images built from the 0.1.45 engine packages (the 0.2.0 packages are not cut yet), on real cards: NVIDIA RTX 3060 (`cuda13`
+2026-10-17, images built from the 0.1.45 engine packages (images from the 0.2.0 packages have not been run on a card), on real cards: NVIDIA RTX 3060 (`cuda13`
and `cuda12`), Radeon AI PRO R9700 (`rocm-gfx120x`), Intel Arc Pro B70 (`sycl`). On each: the container serves, `GET /v1/models` answers (and
refuses a request without the key), a one-word chat and a tool call work, `docker exec strata monitor --once` works,
`docker stop` ends it with exit code 0 and the graphics memory is free again, and a second start reuses the saved preset.
diff --git a/docs/MCP_SERVER.md b/docs/MCP_SERVER.md
index 4fc053697..278463f78 100644
--- a/docs/MCP_SERVER.md
+++ b/docs/MCP_SERVER.md
@@ -128,7 +128,7 @@ Every result is JSON with a one-line `summary`. It is sent both as text and as M
- the size setup itself would pick: IQ3_XXS from 60 GB of RAM, Q2_0 from about 44 GB, the Coder from about 28 GB,
and the Coder in the low-RAM mode below that when the GPU makes up for the RAM;
- the context setup recommends for the GPU's VRAM;
-- images off.
+- pictures on where the model can read them (the reader runs on the CPU under 24 GB of VRAM and on the GPU from 24 GB, on every make of card; a Mac has none yet).
The first call returns the plan: the download size (58-111 GB), the free disk space, the RAM check, and the exact
setup command. The assistant should show you the plan and call again with `confirm: true` once you agree.
diff --git a/docs/TERMINAL.md b/docs/TERMINAL.md
index de0c1b8ad..743c5103a 100644
--- a/docs/TERMINAL.md
+++ b/docs/TERMINAL.md
@@ -1,44 +1,44 @@
-# Strata terminal commands (implementation in progress)
+# Strata terminal commands
`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).
+For the shortest path, use the [terminal quick start](TERMINAL_QUICKSTART.md). The Terminal installs with one line (see [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md#install-one-line)) and gives you the `strata` command; every command below is typed as `strata ...`. In a source checkout, run `python strata.py ...` from the repository root instead (use `python3` where there is no `python`).
-This checkout adds a source-run terminal entry point beside the existing server:
+Read a server, watch it and start one:
```sh
-python strata.py status --url http://127.0.0.1:8095
-python strata.py status --url http://127.0.0.1:8095 --json
-python strata.py monitor --url http://127.0.0.1:8095 --once
-python strata.py serve --profile path/to/strata-model.json --port 8095
+strata status --url http://127.0.0.1:8095
+strata status --url http://127.0.0.1:8095 --json
+strata monitor --url http://127.0.0.1:8095 --once
+strata serve --profile path/to/strata-model.json --port 8095
```
Discover setup-written model run configs in an installation without loading the engine:
```sh
-python strata.py models list --installed --output json
-python strata.py models inspect MODEL_ID --output json
-python strata.py models list --installed --install-dir /absolute/Strata/install --output json
-python strata.py models list --served --connection work --output json
-python strata.py models import /absolute/path/to/GGUF-directory --plan --output json
+strata models list --installed --output json
+strata models inspect MODEL_ID --output json
+strata models list --installed --install-dir /absolute/Strata/install --output json
+strata models list --served --connection work --output json
+strata models import /absolute/path/to/GGUF-directory --plan --output json
```
-Installed discovery scans only top-level `strata-*.json` files in the checkout containing `strata.py`, or in the existing absolute directory chosen by `--install-dir`/`STRATA_INSTALL_DIR`. It checks the local engine, tokenizer and referenced pack files using the same read-only component inventory as `doctor`. Invalid config candidates stay visible with an error. `models inspect` returns the component report and source-config SHA-256. `component_status: present` means required files exist, while `execution_compatibility: unverified` means model/backend support and real loading have not been proven.
+Installed discovery scans only top-level `strata-*.json` files in the install folders it knows (the Terminal's own folder, the desktop app's install folder and folders earlier installs remembered; in a source checkout, the folder containing `strata.py`), or only in the existing absolute directory chosen by `--install-dir`/`STRATA_INSTALL_DIR`. It checks the local engine, tokenizer and referenced pack files using the same read-only component inventory as `doctor`. Invalid config candidates stay visible with an error. `models inspect` returns the component report and source-config SHA-256. `component_status: present` means required files exist, while `execution_compatibility: unverified` means model/backend support and real loading have not been proven.
`models list --served` uses the saved read-only connection and reports the **current server instance's** model ID and loaded state from telemetry. It is not a catalog of every installed or available model. `models import PATH --plan` inspects a local GGUF file or directory for bounded shard names, presence, regular files and GGUF v3 metadata. It checks for the expected `qwen4exp` architecture and `gpt2` tokenizer fields, and compares shard names with this checkout's known supported setup selections. It parses each bounded tensor directory, rejects payload extents past the end of a shard, and reports observed routed-expert encodings against the known variant's allowed encodings. An optional `mmproj` GGUF in the folder is listed as auxiliary and left untouched. A matching name produces a `setup_args_hint`, not a compatibility verdict: the preview does not read tensor payloads, hash entire files, verify provenance or test an engine load. Full artifact, model-pack, engine-version and hardware checks remain before actual adoption. No import, copy, download, repair or engine launch occurs in these inventory and preview commands.
Save a monitor endpoint separately from the model's serving profile. A connection stores the server root, an optional reverse-proxy prefix and the **name** of a credential environment variable; it never stores the secret:
```sh
-python strata.py connection create work --url https://inference.example --prefix /strata --credential-env STRATA_TELEMETRY_KEY
-python strata.py connection list --output json
-python strata.py connection show work --output json
-python strata.py connection set work prefix=/new-strata --plan --output json
-python strata.py connection set work prefix=/new-strata --if-revision CONNECTION_REVISION
-python strata.py config show --effective --connection work --output json
-python strata.py status --connection work --json
-python strata.py monitor --connection work
-python strata.py logs --connection work --source runtime --follow --output jsonl
+strata connection create work --url https://inference.example --prefix /strata --credential-env STRATA_TELEMETRY_KEY
+strata connection list --output json
+strata connection show work --output json
+strata connection set work prefix=/new-strata --plan --output json
+strata connection set work prefix=/new-strata --if-revision CONNECTION_REVISION
+strata config show --effective --connection work --output json
+strata status --connection work --json
+strata monitor --connection work
+strata logs --connection work --source runtime --follow --output jsonl
```
`config show` reports the source of each effective setting and whether the referenced credential is present, without printing its value or connecting to the server. An explicit `--url` or `--connection` wins over `STRATA_CONNECTION`, then `STRATA_URL`, then the local default. `--credential-env` overrides the selected reference. Direct URL use retains the legacy `STRATA_API_KEY` default; new saved connections default to `STRATA_TELEMETRY_KEY` so a read-only key can be used. Remote roots require HTTPS, and a saved proxy prefix accepts only simple path segments. The source CLI and portable monitor bundle use the same owner-private connection files in `${XDG_CONFIG_HOME:-~/.config}/strata/connections` or `%APPDATA%/Strata/connections`; `STRATA_CONNECTION_DIR` can select an absolute directory. On POSIX, the directory and records must be owner-only. Windows ACL qualification remains open.
@@ -46,75 +46,75 @@ python strata.py logs --connection work --source runtime --follow --output jsonl
Operator profiles are separate from setup's run config. Save one from an installed config, preview edits, and use its name for serving:
```sh
-python strata.py profile create four-gpu --from-config path/to/strata-model.json
-python strata.py profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true --plan
-python strata.py profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true
-python strata.py profile show four-gpu --effective --output json
-python strata.py serve --profile four-gpu --plan --output json
-python strata.py serve --profile four-gpu --output jsonl
-python strata.py doctor --profile four-gpu --components --output json
-python strata.py doctor --profile four-gpu --live --output json
-python strata.py engine calibrate --profile four-gpu --plan --output json
-python strata.py serve --profile four-gpu --ready-file /absolute/path/strata-ready.json
+strata profile create four-gpu --from-config path/to/strata-model.json
+strata profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true --plan
+strata profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true
+strata profile show four-gpu --effective --output json
+strata serve --profile four-gpu --plan --output json
+strata serve --profile four-gpu --output jsonl
+strata doctor --profile four-gpu --components --output json
+strata doctor --profile four-gpu --live --output json
+strata engine calibrate --profile four-gpu --plan --output json
+strata serve --profile four-gpu --ready-file /absolute/path/strata-ready.json
```
`strata serve` is the foreground form: Ctrl+C, a closing terminal, `kill` and a killed parent all end the server and its engine. `strata runtime start` is the background form: a service that keeps serving after the terminal closes and until `strata runtime stop` (`strata runtime cleanup` ends what a lost owner left behind). See [CLOSING.md](CLOSING.md) for every way of ending and what each one does on each OS.
-For a saved profile on POSIX, an owner-only local host can keep the server running and provide repeatable rerun commands:
+For a saved profile, an owner-only local host can keep the server running and provide repeatable rerun commands:
```sh
-python strata.py runtime start --profile four-gpu --plan --output json
-python strata.py runtime start --profile four-gpu --shutdown-timeout 30
-python strata.py runtime status --profile four-gpu --output json
-python strata.py runtime verify --profile four-gpu --wait 300 --output json
-python strata.py runtime verify --profile four-gpu --load --wait 300 --output json
-python strata.py profile set four-gpu parallel=8 batch_groups=auto --plan
-python strata.py profile set four-gpu parallel=8 batch_groups=auto
-python strata.py runtime restart --profile four-gpu --plan --output json
-python strata.py runtime restart --profile four-gpu --startup-wait 300
-python strata.py runtime stop --profile four-gpu
+strata runtime start --profile four-gpu --plan --output json
+strata runtime start --profile four-gpu --shutdown-timeout 30
+strata runtime status --profile four-gpu --output json
+strata runtime verify --profile four-gpu --wait 300 --output json
+strata runtime verify --profile four-gpu --load --wait 300 --output json
+strata profile set four-gpu parallel=8 batch_groups=auto --plan
+strata profile set four-gpu parallel=8 batch_groups=auto
+strata runtime restart --profile four-gpu --plan --output json
+strata runtime restart --profile four-gpu --startup-wait 300
+strata runtime stop --profile four-gpu
```
To switch a managed model to a separate run config file, select the file in the saved profile, preview the owned restart, then pass its candidate digest when restarting:
```sh
-python strata.py profile use-config four-gpu --from-config /absolute/path/next-model.json --plan --output json
-python strata.py profile use-config four-gpu --from-config /absolute/path/next-model.json --if-revision PROFILE_REVISION --output json
-python strata.py runtime restart --profile four-gpu --allow-source-switch --plan --output json
-python strata.py runtime restart --profile four-gpu --allow-source-switch --if-profile-revision NEW_PROFILE_REVISION --if-source-sha256 CANDIDATE_SOURCE_SHA256
+strata profile use-config four-gpu --from-config /absolute/path/next-model.json --plan --output json
+strata profile use-config four-gpu --from-config /absolute/path/next-model.json --if-revision PROFILE_REVISION --output json
+strata runtime restart --profile four-gpu --allow-source-switch --plan --output json
+strata runtime restart --profile four-gpu --allow-source-switch --if-profile-revision NEW_PROFILE_REVISION --if-source-sha256 CANDIDATE_SOURCE_SHA256
```
If an operator edits the **same run config file** while its managed server is running, use the separate migration preview and pin the edited bytes before restart:
```sh
-python strata.py runtime restart --profile four-gpu --allow-source-migration --plan --output json
-python strata.py runtime restart --profile four-gpu --allow-source-migration --if-profile-revision PROFILE_REVISION --if-source-sha256 CANDIDATE_SOURCE_SHA256
+strata runtime restart --profile four-gpu --allow-source-migration --plan --output json
+strata runtime restart --profile four-gpu --allow-source-migration --if-profile-revision PROFILE_REVISION --if-source-sha256 CANDIDATE_SOURCE_SHA256
```
-The local host owns its server child and uses a private Unix control socket and token file; the CLI never signals a PID read from a ready file. Restart drains the current instance, applies the saved profile revision, waits for the new ready file, and launches the previous arguments again if activation fails. Switching the saved profile to a **distinct, regular source file** is explicit and requires the preview's source digest. The old source file must still contain its launch bytes for ordinary rollback. An in-place edit requires `--allow-source-migration`; before drain the host copies the running config bytes to a mode-0600 file in its private runtime directory. If the old file was edited **and** the saved profile now points to a new file, preview and run with both source flags. A failed activation restarts from the snapshot, leaving the operator's edited file untouched. The rollback status reports the snapshot path; after the operator fixes the candidate file, retry it as a distinct source with `--allow-source-switch`. A successful activation removes the unneeded snapshot. A hard link to the old file or a source change after preview is rejected before draining; a source change during activation fails attestation and attempts rollback. The host stores private logs and state under `${XDG_STATE_HOME:-~/.local/state}/strata/runtime` or `STRATA_RUNTIME_DIR` (which must be an absolute, owner-only directory). `runtime start` and `runtime restart` verify the ready-file instance ID against authenticated local telemetry, compare a private MAC of the config bytes and launch arguments actually read by the server, and run a one-token generation before reporting generation readiness. A launch mismatch fails before generation. The MAC is scoped to the owner-managed process; it is not a publisher signature or a model-file hash. An intentionally lazy model remains `unloaded` with `generation_ready=false`; `runtime verify --load` opts into loading and generating. `runtime status` reports the last successful startup or explicit verification, not continuous engine liveness; use `runtime verify` to recheck. The probe validates the bound endpoint and model ID, requires at least one completion token, uses a configured API key only in memory, and puts neither generated text nor credentials in the operation journal. If the optional API monitor is enabled, it can capture the fixed probe request like other inference calls. This one-token smoke check does not establish sustained throughput, answer quality or four-card stability. On POSIX, an inherited pipe makes the server stop its dedicated process group when the owner host dies, including after a hard kill. `runtime status` then reports `stale`; a new `runtime start` waits for the recorded child to exit, verifies the host's file lease is gone and the child has exited, and reclaims private state and any orphaned rollback snapshots without signaling a saved PID. If the child is still present, its ownership record is missing, or the socket has an active listener, recovery refuses and requires inspection. This mechanism has been tested with a fake engine on macOS, not qualified on real multi-GPU workloads or Linux. Windows needs a qualified owner-only control transport and ACL tests before these commands can manage it. The shared Desktop operation journal and full model/device editing contract are still pending.
+The local host owns its server child. On macOS and Linux it uses a private Unix control socket and token file; on Windows it uses a loopback-only TCP listener (127.0.0.1, never a network address) that answers only requests carrying the owner's 256-bit token, kept in an owner-only folder (that is a weaker guarantee than a socket the other users cannot open, and the token is what protects it); the CLI never signals a PID read from a ready file. Restart drains the current instance, applies the saved profile revision, waits for the new ready file, and launches the previous arguments again if activation fails. Switching the saved profile to a **distinct, regular source file** is explicit and requires the preview's source digest. The old source file must still contain its launch bytes for ordinary rollback. An in-place edit requires `--allow-source-migration`; before drain the host copies the running config bytes to a mode-0600 file in its private runtime directory. If the old file was edited **and** the saved profile now points to a new file, preview and run with both source flags. A failed activation restarts from the snapshot, leaving the operator's edited file untouched. The rollback status reports the snapshot path; after the operator fixes the candidate file, retry it as a distinct source with `--allow-source-switch`. A successful activation removes the unneeded snapshot. A hard link to the old file or a source change after preview is rejected before draining; a source change during activation fails attestation and attempts rollback. The host stores private logs and state under `${XDG_STATE_HOME:-~/.local/state}/strata/runtime` or `STRATA_RUNTIME_DIR` (which must be an absolute, owner-only directory). `runtime start` and `runtime restart` verify the ready-file instance ID against authenticated local telemetry, compare a private MAC of the config bytes and launch arguments actually read by the server, and run a one-token generation before reporting generation readiness. A launch mismatch fails before generation. The MAC is scoped to the owner-managed process; it is not a publisher signature or a model-file hash. An intentionally lazy model remains `unloaded` with `generation_ready=false`; `runtime verify --load` opts into loading and generating. `runtime status` reports the last successful startup or explicit verification, not continuous engine liveness; use `runtime verify` to recheck. The probe validates the bound endpoint and model ID, requires at least one completion token, uses a configured API key only in memory, and puts neither generated text nor credentials in the operation journal. If the optional API monitor is enabled, it can capture the fixed probe request like other inference calls. This one-token smoke check does not establish sustained throughput, answer quality or four-card stability. On macOS and Linux, an inherited pipe makes the server stop its dedicated process group when the owner host dies, including after a hard kill. `runtime status` then reports `stale`; a new `runtime start` waits for the recorded child to exit, verifies the host's file lease is gone and the child has exited, and reclaims private state and any orphaned rollback snapshots without signaling a saved PID. If the child is still present, its ownership record is missing, or the socket has an active listener, recovery refuses and requires inspection. The desktop app starts its models through this host on all three systems. Multi-GPU workloads have not been qualified on this path.
Owner-editable operation recipes save typed actions next to profiles. Initialize three examples, preview the exact action and its effects, then run it explicitly:
```sh
-python strata.py ops init --profile four-gpu
-python strata.py ops list --profile four-gpu
-python strata.py ops set restart --profile four-gpu startup_wait_s=45 --plan
-python strata.py ops set restart --profile four-gpu startup_wait_s=45
-python strata.py ops edit restart --profile four-gpu
-python strata.py ops plan restart --profile four-gpu --output json
-python strata.py ops run restart --profile four-gpu --if-revision RECIPE_REVISION --if-profile-revision PROFILE_REVISION
-python strata.py ops run check --profile four-gpu --output json
-python strata.py ops set check --profile four-gpu live=true --plan
-python strata.py ops set check --profile four-gpu live=true
-python strata.py ops plan check --profile four-gpu --output json
-python strata.py ops run check --profile four-gpu --output json
-python strata.py ops set calibrate --profile four-gpu report_dir=/private/path/reports
-python strata.py ops plan calibrate --profile four-gpu --output json
-python strata.py ops run calibrate --profile four-gpu --exclusive --output json
-python strata.py ops runs --profile four-gpu --limit 20 --output json
-python strata.py ops result OPERATION_ID --profile four-gpu --output json
-python strata.py ops history restart --profile four-gpu
-python strata.py ops rollback restart --profile four-gpu --to REVISION
+strata ops init --profile four-gpu
+strata ops list --profile four-gpu
+strata ops set restart --profile four-gpu startup_wait_s=45 --plan
+strata ops set restart --profile four-gpu startup_wait_s=45
+strata ops edit restart --profile four-gpu
+strata ops plan restart --profile four-gpu --output json
+strata ops run restart --profile four-gpu --if-revision RECIPE_REVISION --if-profile-revision PROFILE_REVISION
+strata ops run check --profile four-gpu --output json
+strata ops set check --profile four-gpu live=true --plan
+strata ops set check --profile four-gpu live=true
+strata ops plan check --profile four-gpu --output json
+strata ops run check --profile four-gpu --output json
+strata ops set calibrate --profile four-gpu report_dir=/private/path/reports
+strata ops plan calibrate --profile four-gpu --output json
+strata ops run calibrate --profile four-gpu --exclusive --output json
+strata ops runs --profile four-gpu --limit 20 --output json
+strata ops result OPERATION_ID --profile four-gpu --output json
+strata ops history restart --profile four-gpu
+strata ops rollback restart --profile four-gpu --to REVISION
```
`ops create NAME --profile four-gpu --kind runtime.restart|engine.calibrate.measure|components.verify` adds another typed recipe. `ops edit` opens a temporary JSON copy in `VISUAL` or `EDITOR`; invalid drafts are kept for repair. Recipe revisions are saved atomically with history. `--if-revision` and `--if-profile-revision` prevent an edited recipe or profile from running after a preview; the runtime host checks the profile revision again before draining. `ops plan` is read-only and distinguishes preview effects from the effects of a subsequent run. The calibration recipe runs the existing decode-speed sweep, creates a new report filename under its saved absolute `report_dir`, and requires a fresh `--exclusive` assertion every time. Review and apply that report with the separate `engine calibrate --review-result` and `--apply-result` commands above; a recipe run never applies tuning automatically. The component recipe reads installed files; its optional typed `live=true` setting also queries the host's GPU inventory during both preview and run. Recipes contain known kinds and typed values, never arbitrary shell command text.
@@ -124,31 +124,31 @@ Each accepted `ops run` creates a local operation record with recipe/profile rev
To tune an installed engine, stop all instances using its devices, then measure and review a separate report before applying it:
```sh
-python strata.py engine calibrate --profile four-gpu --measure --exclusive --out calibration.json
-python strata.py engine calibrate --profile four-gpu --review-result calibration.json --output json
-python strata.py engine calibrate --profile four-gpu --apply-result calibration.json --exclusive
-python strata.py engine calibrate --profile four-gpu --review-rollback calibration.json --output json
-python strata.py engine calibrate --profile four-gpu --rollback-result calibration.json --exclusive
+strata engine calibrate --profile four-gpu --measure --exclusive --out calibration.json
+strata engine calibrate --profile four-gpu --review-result calibration.json --output json
+strata engine calibrate --profile four-gpu --apply-result calibration.json --exclusive
+strata engine calibrate --profile four-gpu --review-rollback calibration.json --output json
+strata engine calibrate --profile four-gpu --rollback-result calibration.json --exclusive
```
To measure the **running** server after selecting the intended model and batching profile, run an explicit serving workload and keep its local evidence:
```sh
-python strata.py bench run --profile four-gpu --suite serving-smoke --concurrency 8 --out ./bench-smoke-01
-python strata.py bench report ./bench-smoke-01 --output json
-python strata.py bench run --url http://127.0.0.1:8095 --suite parallel-mixed-v1 --concurrency 8 --repeat 3 --out ./bench-mixed-01
-python strata.py bench run --profile four-gpu --suite parallel-overload-v1 --concurrency 48 --out ./bench-overload-01
-python strata.py bench run --profile four-gpu --suite parallel-cancel-v1 --concurrency 8 --out ./bench-cancel-01
-python strata.py bench run --profile four-gpu --suite parallel-prefill-cancel-v1 --concurrency 8 --out ./bench-prefill-cancel-01
-python strata.py runtime start --profile four-gpu
-python strata.py bench run --profile four-gpu --require-managed-match --suite parallel-mixed-v1 --concurrency 8 --repeat 3 --condition baseline --out ./bench-baseline
+strata bench run --profile four-gpu --suite serving-smoke --concurrency 8 --out ./bench-smoke-01
+strata bench report ./bench-smoke-01 --output json
+strata bench run --url http://127.0.0.1:8095 --suite parallel-mixed-v1 --concurrency 8 --repeat 3 --out ./bench-mixed-01
+strata bench run --profile four-gpu --suite parallel-overload-v1 --concurrency 48 --out ./bench-overload-01
+strata bench run --profile four-gpu --suite parallel-cancel-v1 --concurrency 8 --out ./bench-cancel-01
+strata bench run --profile four-gpu --suite parallel-prefill-cancel-v1 --concurrency 8 --out ./bench-prefill-cancel-01
+strata runtime start --profile four-gpu
+strata bench run --profile four-gpu --require-managed-match --suite parallel-mixed-v1 --concurrency 8 --repeat 3 --condition baseline --out ./bench-baseline
# Attach the read-only monitor in a separate terminal, then repeat the same workload.
-# python strata.py monitor --url http://127.0.0.1:8095 --interval 2
-python strata.py bench run --profile four-gpu --require-managed-match --suite parallel-mixed-v1 --concurrency 8 --repeat 3 --condition monitor-default --out ./bench-monitored
-python strata.py bench compare ./bench-baseline ./bench-monitored --output json
+# strata monitor --url http://127.0.0.1:8095 --interval 2
+strata bench run --profile four-gpu --require-managed-match --suite parallel-mixed-v1 --concurrency 8 --repeat 3 --condition monitor-default --out ./bench-monitored
+strata bench compare ./bench-baseline ./bench-monitored --output json
```
-`bench run` requires a loaded instance and versioned telemetry. It sends one warmup request, a two-request serial phase and a mixed short/long streaming phase; `parallel-mixed-v1` repeats the mixed phase twice per trial. `parallel-overload-v1` instead sends one warmup, a synchronized short/long burst and a recovery request. It requires configured `max_queue` and `queue_timeout`, and `--concurrency` must exceed the reported admission limit; use up to 64 workers for this explicit suite, or up to 16 for the others. The example of 48 workers only fits a server whose reported admission limit is below 48. Expected `admission_full` and `queue_wait_timeout` responses are counted separately from unexpected errors; the suite passes only if some calls run, some are refused or time out, and recovery works. `parallel-cancel-v1` closes one active stream after its first content, then fills the effective slots and closes a queued stream, followed by a recovery request. It requires at least one queue place, a queue timeout of at least two seconds, disconnect telemetry and `--concurrency` at least the effective slot count. It checks that the target was visible, the server observed a client disconnect, companions completed and admission and slots settled. `parallel-prefill-cancel-v1` separately closes a target while the engine reports partial prompt reading in a batch slot, with one companion decoding; it requires at least two effective slots, concurrency at least two and disconnect telemetry. Both cancellation suites verify companion completion, settled resources and recovery. Run them without unrelated client traffic because the disconnect counter is server-wide. `--concurrency` is a client-worker count, not the engine's effective slot count. Supply an inference key through `STRATA_API_KEY`; if monitoring has a separate key, add `--telemetry-credential-env STRATA_TELEMETRY_KEY`. The new output directory contains `results.json`, with request latency, first-token time, output token counts when the API provides them, and sampled active/queued/occupied slots, groups and per-card readings. Prompts, answer text and credentials are excluded. The report records null when a backend signal is unavailable and labels the limits of client-observed timing. `bench run --profile NAME --require-managed-match` is an opt-in gate for a server launched by the POSIX owner host. It rejects a changed profile, changed source config, unverified owner launch, wrong telemetry instance or endpoint before creating benchmark output. It checks again after the workload and retains a failed report if the match was lost. Reports label the result `managed_launch_checked`; default, foreground and remote runs label it `unverified`. This is a beginning/end check of the owner's startup attestation, not continuous verification of running files. These source-run suites do not verify model artifact hashes or driver versions or establish four-GPU throughput on the target host.
+`bench run` is a serving benchmark for your own tuning and comparisons; it is not the draft community benchmark protocol ([BENCHMARK_PROTOCOL.md](BENCHMARK_PROTOCOL.md)), and its output is not a standard submission. It requires a loaded instance and versioned telemetry. It sends one warmup request, a two-request serial phase and a mixed short/long streaming phase; `parallel-mixed-v1` repeats the mixed phase twice per trial. `parallel-overload-v1` instead sends one warmup, a synchronized short/long burst and a recovery request. It requires configured `max_queue` and `queue_timeout`, and `--concurrency` must exceed the reported admission limit; use up to 64 workers for this explicit suite, or up to 16 for the others. The example of 48 workers only fits a server whose reported admission limit is below 48. Expected `admission_full` and `queue_wait_timeout` responses are counted separately from unexpected errors; the suite passes only if some calls run, some are refused or time out, and recovery works. `parallel-cancel-v1` closes one active stream after its first content, then fills the effective slots and closes a queued stream, followed by a recovery request. It requires at least one queue place, a queue timeout of at least two seconds, disconnect telemetry and `--concurrency` at least the effective slot count. It checks that the target was visible, the server observed a client disconnect, companions completed and admission and slots settled. `parallel-prefill-cancel-v1` separately closes a target while the engine reports partial prompt reading in a batch slot, with one companion decoding; it requires at least two effective slots, concurrency at least two and disconnect telemetry. Both cancellation suites verify companion completion, settled resources and recovery. Run them without unrelated client traffic because the disconnect counter is server-wide. `--concurrency` is a client-worker count, not the engine's effective slot count. Supply an inference key through `STRATA_API_KEY`; if monitoring has a separate key, add `--telemetry-credential-env STRATA_TELEMETRY_KEY`. The new output directory contains `results.json`, with request latency, first-token time, output token counts when the API provides them, and sampled active/queued/occupied slots, groups and per-card readings. Prompts, answer text and credentials are excluded. The report records null when a backend signal is unavailable and labels the limits of client-observed timing. `bench run --profile NAME --require-managed-match` is an opt-in gate for a server launched by the POSIX owner host. It rejects a changed profile, changed source config, unverified owner launch, wrong telemetry instance or endpoint before creating benchmark output. It checks again after the workload and retains a failed report if the match was lost. Reports label the result `managed_launch_checked`; default, foreground and remote runs label it `unverified`. This is a beginning/end check of the owner's startup attestation, not continuous verification of running files. These source-run suites do not verify model artifact hashes or driver versions or establish four-GPU throughput on the target host.
`bench run --condition NAME` records a short operator label, such as `baseline`, `monitor-default` or `monitor-fast`; it does not verify that a monitor was attached. `bench compare BASELINE CANDIDATE` reads two saved reports without contacting the server or writing files. It rejects failed runs, different suites/models, changed request fingerprints or concurrency, changed source-config digests and conflicting reported device/settings identity. It pairs phases and reports client-observed p95 TTFT, p95 latency and output throughput, plus admission/queue deltas. Missing values remain unavailable. The comparison is **provisional** even when both runs have `managed_launch_checked`: the owner match is checked only at the beginning and end, and exact driver/engine/model hashes, monitor attachment, host CPU/RSS and telemetry traffic are not attested. For the four-card overhead gate, keep at least three repeated measured phases, save `doctor --live` card/driver evidence, record PCIe and layer topology separately, measure host and monitor CPU/RSS and HTTP calls/bytes separately, and investigate changes against trial variability. A pair of reports alone is not release qualification.
@@ -162,7 +162,7 @@ The basic CLI and status command use Python's standard library. The interactive
```sh
python -m pip install -r requirements-monitor.txt
-python strata.py monitor --url http://127.0.0.1:8095
+strata monitor --url http://127.0.0.1:8095
```
Use the same Python environment that runs Strata. Strata's runtime dependencies are listed separately in `requirements.txt`; the monitor dependency is not needed for `serve` or `status`.
@@ -184,7 +184,7 @@ python dist/strata-monitor.pyz monitor --url https://HOST --once --json
python dist/strata-monitor.pyz logs --url https://HOST --output json
```
-The `.pyz` contains only the bounded telemetry client, connection store, renderers for the Overview and five detail pages, optional TUI module, the same status/monitor/logs command implementation used by `python strata.py`, and Strata's MIT license notice. It has no server, engine, model, setup code or bundled framework. One-shot status, request activity and saved connections work with Python's standard library alone; interactive mode needs an explicit `python -m pip install textual==8.2.8` in that Python environment. The adjacent version-4 `.manifest.json` records a SHA-256 checksum, exact bundle members, Python 3.10 minimum and telemetry schema 1 compatibility. The verifier still accepts older version-1 through version-3 source bundles so a local update can retain and roll back to one. The manifest has no publisher signature, so it is a source-run artifact, not a signed release component. A remote URL still requires HTTPS or a local SSH tunnel; credentials come from an environment variable through `--credential-env` or a saved reference.
+The `.pyz` contains only the bounded telemetry client, connection store, renderers for the Overview and five detail pages, optional TUI module, the same status/monitor/logs command implementation used by `strata`, and Strata's MIT license notice. It has no server, engine, model, setup code or bundled framework. One-shot status, request activity and saved connections work with Python's standard library alone; interactive mode needs an explicit `python -m pip install textual==8.2.8` in that Python environment. The adjacent version-4 `.manifest.json` records a SHA-256 checksum, exact bundle members, Python 3.10 minimum and telemetry schema 1 compatibility. The verifier still accepts older version-1 through version-3 source bundles so a local update can retain and roll back to one. The manifest has no publisher signature, so it is a source-run artifact, not a signed release component. A remote URL still requires HTTPS or a local SSH tunnel; credentials come from an environment variable through `--credential-env` or a saved reference.
Before distributing a candidate to an operator, run its standard-library smoke on each target Python and OS:
@@ -234,7 +234,7 @@ When `--max-queue` is set, at most **effective slots + max queue** HTTP inferenc
`status --json` and `monitor --once --json` return one versioned JSON object. Remote monitor URLs require verified HTTPS; a local SSH tunnel can use `http://127.0.0.1`. For a read-only monitor key, set `STRATA_TELEMETRY_KEY` on the server and pass the same secret to the client through `--credential-env STRATA_TELEMETRY_KEY` (or another client environment variable). Use a distinct inference API key: the server rejects duplicate keys. The telemetry key authorizes `/v1/telemetry` only; it cannot call inference or management endpoints. The existing `STRATA_API_KEY` also works and has its broader legacy permissions. Keys are never put in URLs or command arguments. The client refuses redirects and responses over 2 MiB. Excessively nested JSON is reported as a malformed telemetry response with the same one-record error contract, rather than a Python traceback.
-The interactive monitor has Overview, Serving, Requests, Engine, Hardware and Logs views. Use keys `1`–`6` or Left/Right to switch views, Tab in Serving to cycle Devices / Requests / Groups at wide and compact widths, `/` to filter requests, Up/Down and Page Up/Down to move the selected row, Home/End to jump to the first/last row, Enter to show or hide read-only request, device or slot detail, Space to freeze the display, `r` to refresh, `t` to cycle theme, `?` or F1 for help, and `q` to detach. Filter input is limited to 80 characters and cleaned of terminal controls and bidi formatters as text arrives; `q` remains ordinary text while the filter has focus. Recent detail contains bounded token and timing summaries, never prompt bodies. A selected request, device or slot stays attached to its reported ID across polls, including when a request moves from live to recent history; detail closes and the TUI says “No longer retained” if that ID disappears. An instance restart clears selection even when a new request reuses the same ID. The 60- and 40-column layouts keep the selected request visible. It never starts or stops the server. `NO_COLOR` or `--color never` uses terminal defaults. `--glyphs ascii` avoids special glyphs. The selected terminal font is controlled by the terminal, not Strata.
+The interactive monitor has six views: Overview, Serving, Requests, Engine, Hardware and Logs. The monitor that `strata launch` opens adds a seventh, **Connect** (the address, the key and the setup for your coding apps; see [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md#after-the-start-the-monitor)). Use keys `1`–`6` (`1`–`7` in the launch monitor) or Left/Right to switch views, Tab in Serving to cycle Devices / Requests / Groups at wide and compact widths, `/` to filter requests, Up/Down and Page Up/Down to move the selected row, Home/End to jump to the first/last row, Enter to show or hide read-only request, device or slot detail, Space to freeze the display, `r` to refresh, `t` to cycle theme, `?` or F1 for help, and `q` to detach. Filter input is limited to 80 characters and cleaned of terminal controls and bidi formatters as text arrives; `q` remains ordinary text while the filter has focus. Recent detail contains bounded token and timing summaries, never prompt bodies. A selected request, device or slot stays attached to its reported ID across polls, including when a request moves from live to recent history; detail closes and the TUI says “No longer retained” if that ID disappears. An instance restart clears selection even when a new request reuses the same ID. The 60- and 40-column layouts keep the selected request visible. It never starts or stops the server. `NO_COLOR` or `--color never` uses terminal defaults. `--glyphs ascii` avoids special glyphs. The selected terminal font is controlled by the terminal, not Strata.
Remote model, device and request labels are stripped of terminal controls and bidi formatters before display. The stdlib renderer clips by terminal display cells and pads fixed columns by the same measure; local cases cover combining marks, CJK names, regional-indicator flags and joined emoji at 110, 80, 60 and 40 columns. Terminal implementations can differ on ambiguous-width characters, so the renderer uses the terminal's narrow default for them.
@@ -248,7 +248,7 @@ The [wide four-GPU Serving preview](terminal-previews/serving-110-color.png), [8
The [schema v1 telemetry field matrix](TERMINAL_TELEMETRY_FIELDS.md) gives each displayed value's source, unit, scope, sensitivity and missing-data rule. Use it when connecting another UI or consuming `status --json`.
-The [qualification matrix](TERMINAL_QUALIFICATION.md) lists source-run checks and the remaining target-host gates for the developer.
+The [qualification matrix](TERMINAL_QUALIFICATION.md) is a historical record of the source-run checks made before the 0.2.0 Terminal (11 October 2026).
For a repeatable client stability check, run `tools/monitor_soak.py` with an absolute new report path. `--exercise-ui` resizes the live Textual monitor across 110 x 30, 80 x 24, 60 x 16 and 40 x 12 while a synthetic server rotates an unrelated host GPU row and intermittently omits or duplicates a selected card sensor. It checks selected-card history bounds alongside reconnect, restart and read-only detach. Use `--seconds 1800 --interval 0.5 --exercise-ui` for the long soak. Its JSON is synthetic client evidence; it does not measure engine, model or GPU performance.
@@ -273,4 +273,4 @@ For a four-card run, record the exact GPU model/VRAM, driver, selected device ID
## Current limits
-The `strata code` command returns a missing-component error because the shared Desktop harness source and its session/approval contract have not been integrated. No separate coding-agent loop is bundled here. The source-run checkout now has a POSIX owner bridge, recoverable benchmark and calibration journal receipts, a redacted request-activity feed and a portable read-only monitor bundle. Windows runtime ownership and locking, remaining Desktop authority mappings, complete management journal coverage, signed whole-runtime distribution and qualified native batch/stage samples are pending. Calibration and serving benchmarks have not been run on a real model in this checkout. This implementation does not establish a macOS inference-engine port or four-RTX-6000 performance.
+`strata code` is not available in this version: it exits with code 5 and says the shared Desktop harness component is not installed. To use a coding app with a Strata server, run `strata connect` (see [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md#connect-your-apps-strata-connect)); the desktop app has its own coding harness. Calibration and serving benchmarks (`strata bench run`) are explicit, separate steps; this page does not report results from a real model. Nothing here establishes four-RTX-6000 performance.
diff --git a/docs/TERMINAL_IMPLEMENTATION_STATUS.md b/docs/TERMINAL_IMPLEMENTATION_STATUS.md
index 565ee99a4..34ad72f07 100644
--- a/docs/TERMINAL_IMPLEMENTATION_STATUS.md
+++ b/docs/TERMINAL_IMPLEMENTATION_STATUS.md
@@ -1,5 +1,7 @@
# Terminal work against the 10 October 2026 implementation plan
+> **Historical record (11 October 2026).** This page was written while the Terminal was being built, before Strata 0.2.0. It is kept for the record and is not kept up to date: it describes six views, source-run commands and checks that had not yet been run on target hardware. For what the Terminal does now, see [TERMINAL.md](TERMINAL.md), [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md) and [TERMINAL_QUICKSTART.md](TERMINAL_QUICKSTART.md).
+
Source baseline for the original milestone: `Niko1221/Strata` at `fb58e0dbc8399662c0e47c76578c6e878b14f6cf`. Branch `feat/terminal-cli-monitor-current` merges the public `main` fetched on 11 October 2026 at `61b3fb5dd3f1e8ec09cf7e4e05208bc6d3c46406`. The plan lives at `../output/strata-terminal-implementation-plan.md` in the parent design workspace. This is a working implementation, not a qualified release.
Current-main integration checks on macOS: 706 server tests passed with 11 skipped, all 218 terminal tests passed, and the C++20 batch/stage sampler compiled with warnings as errors and passed. The imported editable Desktop app passed TypeScript checking, a production build and 116 Node tests. The broad setup suite ran 465 tests with two failures and four errors; representative CUDA build and prebuilt-download failures reproduce on a clean public-main checkout, while HIP errors need a ROCm environment absent here. Fake-engine two-replica request/slot correlation and configured card assignment are covered; native GPU builds, native per-replica batch/stage qualification, Windows/Linux install, full Desktop authority and coding harness remain open. The Desktop native shell now supports an opt-in, owner-backed single-profile Serving Start/Stop/Restart/Verify preview, a read-only six-panel Monitor, a read-only Components screen with manual host GPU probe, a reviewed Profile editor for source run config and typed serving overrides, a read-only Models screen with per-config detail and GGUF preflight, a Benchmarks screen for reviewed managed runs, saved reports, workload-checked comparisons and private Markdown export, and a native Calibration screen for reviewed measure/apply/rollback through a pollable host job and shared journal; prototype mutations and its demo monitor sampler are disabled.
diff --git a/docs/TERMINAL_LAUNCH.md b/docs/TERMINAL_LAUNCH.md
index a61214f5f..52670c8cd 100644
--- a/docs/TERMINAL_LAUNCH.md
+++ b/docs/TERMINAL_LAUNCH.md
@@ -7,15 +7,15 @@ in the Terminal's look, with presets, an Advanced table, an access choice and a
## Install (one line)
```sh
-curl -fsSL <release-folder>/install.sh | sh # Linux, macOS
-irm <release-folder>/install.ps1 | iex # Windows PowerShell
+curl -fsSL https://github.com/Niko1221/Strata/releases/latest/download/install.sh | sh # Linux, macOS
+irm https://github.com/Niko1221/Strata/releases/latest/download/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 release folder is the latest GitHub release of Niko1221/Strata (`https://github.com/Niko1221/Strata/releases/latest/download`). The script only fetches and checks; read it first if you like (it is the same file as `install.sh` / `install.ps1` in the repository's `packaging` folder and in the release). Set `STRATA_FEED` to another folder to try a local one; `packaging/make_local_feed.py` builds a test-signed one. How far to trust a piped installer is in [SECURITY.md](../SECURITY.md).
## The screens (`strata launch`)
@@ -76,7 +76,7 @@ folder; the run uses the shared profile `launch-<name>` and the shared tuning pr
`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
+the way that app does and says whether each worked. With `--output json` (`strata connect opencode --check --output json`) it prints one JSON object with the same file and environment fields plus `checks` (one entry per check: `name`, `ok`, `detail`, `seconds`) and `checked_server`; `ok` is true only when both checks passed. The exit code is 0 when both worked and 1 when one failed or the server could not be reached; in that case the object also carries an `error` that says which of the two it was. 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
diff --git a/docs/TERMINAL_QUALIFICATION.md b/docs/TERMINAL_QUALIFICATION.md
index 741ef583a..2f65717b7 100644
--- a/docs/TERMINAL_QUALIFICATION.md
+++ b/docs/TERMINAL_QUALIFICATION.md
@@ -1,5 +1,7 @@
# Terminal qualification matrix
+> **Historical record (11 October 2026).** This page was written while the Terminal was being built, before Strata 0.2.0. It is kept for the record and is not kept up to date: it describes six views, source-run commands and checks that had not yet been run on target hardware. For what the Terminal does now, see [TERMINAL.md](TERMINAL.md), [TERMINAL_LAUNCH.md](TERMINAL_LAUNCH.md) and [TERMINAL_QUICKSTART.md](TERMINAL_QUICKSTART.md).
+
This matrix separates checks already run in this source checkout from release gates that need the supplied UI/harness/TUI assets or a target host. A passed synthetic client test does not establish engine performance or platform support. Record exact commands, source commit, artifacts and environment for every final gate.
| Gate | Evidence in this checkout | Remaining acceptance work |
diff --git a/docs/TERMINAL_QUICKSTART.md b/docs/TERMINAL_QUICKSTART.md
index 12fdf2f86..a11f67f43 100644
--- a/docs/TERMINAL_QUICKSTART.md
+++ b/docs/TERMINAL_QUICKSTART.md
@@ -1,31 +1,30 @@
-# Terminal quick start (source checkout)
+# Terminal quick start
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).
+These commands use the `strata` command that the one-line Terminal install puts on your PATH ([how to install](TERMINAL_LAUNCH.md#install-one-line)). The Terminal carries its own Python, so there is nothing else to install. In a source checkout, type `python strata.py` (or `python3 strata.py`) in place of `strata`, from the repository root. The commands below read, prepare and rerun a model you already have; they do not download one. The complete options, permissions and limits are in [TERMINAL.md](TERMINAL.md).
## Read a running server
With Strata already serving locally, get one machine-readable snapshot:
```sh
-python strata.py status --url http://127.0.0.1:8080 --json
+strata status --url http://127.0.0.1:8080 --json
```
-The interactive monitor is optional. Install its pinned dependency in that same Python environment, then open the one-screen Overview:
+The interactive monitor comes with the installed Terminal. Open the one-screen Overview:
```sh
-python -m pip install -r requirements-monitor.txt
-python strata.py monitor --url http://127.0.0.1:8080
+strata monitor --url http://127.0.0.1:8080
```
-The Overview puts serving state, prompt and answer speed, batch/queue pressure, four selected GPU rows, requests and activity on one screen. Press `1`–`6` for detail, `Space` to freeze the display, `r` to refresh, and `q` to detach. Detach leaves the server running. On a machine without a terminal, use `status --json` or `monitor --once --json`.
+The Overview puts serving state, prompt and answer speed, batch/queue pressure, four selected GPU rows, requests and activity on one screen. Press `1`–`6` for detail (`1`–`7` in the monitor that `strata launch` opens, where `7` is the Connect view), `Space` to freeze the display, `r` to refresh, and `q` to detach. Detach leaves the server running. On a machine without a terminal, use `status --json` or `monitor --once --json`.
For a remote server, use HTTPS or a local SSH tunnel. A saved connection stores only the credential environment variable's **name**:
```sh
-python strata.py connection create work --url https://example.invalid --credential-env STRATA_TELEMETRY_KEY
-python strata.py monitor --connection work
+strata connection create work --url https://example.invalid --credential-env STRATA_TELEMETRY_KEY
+strata monitor --connection work
```
Set `STRATA_TELEMETRY_KEY` in the environment before connecting. Replace `example.invalid` with your own server root. The monitor client never needs a management credential.
@@ -35,56 +34,56 @@ Set `STRATA_TELEMETRY_KEY` in the environment before connecting. Replace `exampl
Use the run config written by setup. Start by reviewing its components and effective launch; neither command starts an engine:
```sh
-python strata.py doctor --profile /absolute/path/to/strata-model.json --components --output json
-python strata.py serve --profile /absolute/path/to/strata-model.json --plan --output json
+strata doctor --profile /absolute/path/to/strata-model.json --components --output json
+strata serve --profile /absolute/path/to/strata-model.json --plan --output json
```
-For repeatable local management on POSIX, create a named profile from that config. Review changes before saving them:
+For repeatable local management, create a named profile from that config. Review changes before saving them:
```sh
-python strata.py profile create four-gpu --from-config /absolute/path/to/strata-model.json
-python strata.py profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true --plan
-python strata.py profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true
-python strata.py profile show four-gpu --effective --output json
-python strata.py runtime start --profile four-gpu --plan --output json
-python strata.py runtime start --profile four-gpu
-python strata.py runtime verify --profile four-gpu --output json
+strata profile create four-gpu --from-config /absolute/path/to/strata-model.json
+strata profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true --plan
+strata profile set four-gpu parallel=8 batch_groups=auto max_queue=32 queue_timeout=15 batch_telemetry=true
+strata profile show four-gpu --effective --output json
+strata runtime start --profile four-gpu --plan --output json
+strata runtime start --profile four-gpu
+strata runtime verify --profile four-gpu --output json
```
Choose slot and queue settings for the actual model and card memory. A requested `parallel=8` does not prove the engine loaded eight effective slots. Check the reported values after start. To change a running profile, save the edit, review the restart, then execute it:
```sh
-python strata.py profile set four-gpu parallel=4 --plan
-python strata.py profile set four-gpu parallel=4
-python strata.py runtime restart --profile four-gpu --plan --output json
-python strata.py runtime restart --profile four-gpu
+strata profile set four-gpu parallel=4 --plan
+strata profile set four-gpu parallel=4
+strata runtime restart --profile four-gpu --plan --output json
+strata runtime restart --profile four-gpu
```
-The restart is an explicit operation. `profile set` alone does not restart or retune a running model. `runtime stop --profile four-gpu` stops only the owned instance; `q` in Monitor does not. The POSIX runtime host and rollback path have fake-engine tests, but real GPU and Windows ownership qualification remains open.
+The restart is an explicit operation. `profile set` alone does not restart or retune a running model. `runtime stop --profile four-gpu` stops only the owned instance; `q` in Monitor does not. The desktop app starts its models through the same runtime host on every system.
## Check cards, calibrate and benchmark
Read installed components without launching the engine. The `--live` forms also probe host GPUs:
```sh
-python strata.py components verify --profile four-gpu --output json
-python strata.py doctor --profile four-gpu --live --output json
+strata components verify --profile four-gpu --output json
+strata doctor --profile four-gpu --live --output json
```
Calibration is separate from serving. Review the plan and measure a decode sweep only when the selected devices are available for exclusive use. Measuring writes a report but does not apply settings:
```sh
-python strata.py engine calibrate --profile four-gpu --plan --output json
-python strata.py engine calibrate --profile four-gpu --measure --exclusive --out /absolute/path/to/calibration.json
-python strata.py engine calibrate --profile four-gpu --review-result /absolute/path/to/calibration.json --output json
+strata engine calibrate --profile four-gpu --plan --output json
+strata engine calibrate --profile four-gpu --measure --exclusive --out /absolute/path/to/calibration.json
+strata engine calibrate --profile four-gpu --review-result /absolute/path/to/calibration.json --output json
```
After reviewing the report, applying and rolling back remain separate explicit actions. Both require exclusive device access:
```sh
-python strata.py engine calibrate --profile four-gpu --apply-result /absolute/path/to/calibration.json --exclusive
-python strata.py engine calibrate --profile four-gpu --review-rollback /absolute/path/to/calibration.json --output json
-python strata.py engine calibrate --profile four-gpu --rollback-result /absolute/path/to/calibration.json --exclusive
+strata engine calibrate --profile four-gpu --apply-result /absolute/path/to/calibration.json --exclusive
+strata engine calibrate --profile four-gpu --review-rollback /absolute/path/to/calibration.json --output json
+strata engine calibrate --profile four-gpu --rollback-result /absolute/path/to/calibration.json --exclusive
```
Check the candidate report and owner state before either action. The full preconditions and rollback behavior are in [TERMINAL.md](TERMINAL.md).
@@ -92,7 +91,7 @@ Check the candidate report and owner state before either action. The full precon
After the model is loaded, save an explicit serving benchmark report:
```sh
-python strata.py bench run --profile four-gpu --suite serving-smoke --concurrency 4 --out /absolute/path/to/new-bench-report
+strata bench run --profile four-gpu --suite serving-smoke --concurrency 4 --out /absolute/path/to/new-bench-report
```
The benchmark writes into a new output directory and does not publish its result. Synthetic screenshots and local fake-engine tests do not establish performance on a four-card host. Capture the exact GPU generation, model, driver and workload before comparing real runs.
diff --git a/docs/TEST_REQUESTS.md b/docs/TEST_REQUESTS.md
index e32a63d60..67197f6d1 100644
--- a/docs/TEST_REQUESTS.md
+++ b/docs/TEST_REQUESTS.md
@@ -15,5 +15,8 @@ This list is edited by the maintainers. An item stays until a report answers it.
| Pascal (sm_61: Tesla P40, P100, GTX 10 series) | Older cards run on the fp32 path and can behave differently from newer ones | #875, #876 |
| A Linux host with 32 GB of RAM or less | The expert file tier and the resident mode depend on how much of the model fits in RAM | #1194 |
| A long soak (an hour or more of back-to-back requests) on a split or resident setup | Shows crashes, drift and heat that a short run does not | #848 |
+| AMD RX 7000 series (RX 7900 XTX, 7900 XT, 7800 XT and similar, RDNA 3) on Linux or Windows | The RX 7000 builds have not been run on a real RX 7000 card by us; the Docker image for them is also untested on a card | none yet |
+| Windows with an AMD card: the app or the Terminal, one model, one picture sent | The Windows AMD build has not been run on a real card, and neither has its picture reader (CPU under 24 GB, GPU from 24 GB) | none yet |
+| A Mac with Apple silicon (macOS 15 or newer): the app or the Terminal with a real model | Mac builds have run on very few Macs. Tell us the Mac's memory, the model, the speed, and anything that failed. The Mac app has no picture reader yet. The signing script has not been run against Apple's real notary service yet, so a first-launch warning is expected and useful to hear about | none yet |
To add a request, open a pull request that adds a row, or tell the maintainers in an issue.
diff --git a/packaging/ENGINE-COMPONENT.md b/packaging/ENGINE-COMPONENT.md
index 217ccad0a..68c08dfa8 100644
--- a/packaging/ENGINE-COMPONENT.md
+++ b/packaging/ENGINE-COMPONENT.md
@@ -2,7 +2,9 @@
One format for every engine package: Windows CUDA 13 and 12, Windows HIP, Linux CUDA, Linux HIP, Linux SYCL and macOS
Metal. Control (`strata_control/engine_component.py`) reads it, checks it, and only then starts the engine.
-`packaging/package_engine.py` writes it. Packages are local and unsigned for now; publishing and signing are S6.
+`packaging/package_engine.py` writes it. A package you make locally is unsigned and loads. A package in the release feed is signed with the
+feed key (an Ed25519 key the owner keeps offline), and `strata update` / "Update engine" install it only when that signature verifies
+([UPDATES.md](UPDATES.md)). The installers carry an engine of their own, so a new install needs no download to start a model.
## Folder
@@ -63,9 +65,10 @@ Settings or `strata update` in the Terminal". A package
for another GPU or an older driver is `EngineMissing` with its reason. A tampered newer package never falls back silently
to nothing: a good older package is used and the tampered one is listed under `problems` in `strata components engine`.
-## Signature (S6)
+## Signature
-`signature` is `null` today. S6 fills it and registers the verifier:
+`signature` is `null` in a package made locally. The release feed's packages carry one; the updater registers the verifier
+(`strata_control/signing.py`) and requires it for every package it installs:
engine_component.register_signature_verifier(fn) # fn(payload: bytes, signature: dict, component) -> None, raises if bad
engine_component.signing_payload(manifest_dict) # canonical bytes the signature covers
@@ -76,7 +79,7 @@ UTF-8). It contains every file hash, so one signature covers the whole package.
* unsigned package: loads, reported `unsigned`;
* signed, no verifier registered: loads, reported `unverified` (never "verified");
* signed, verifier registered: must verify, otherwise refused;
-* `STRATA_REQUIRE_SIGNED_COMPONENTS=1`: unsigned and unverifiable packages are refused (the setting S6 turns on for released builds).
+* `STRATA_REQUIRE_SIGNED_COMPONENTS=1`: unsigned and unverifiable packages are refused (the updater turns it on while it checks a downloaded package).
## Building a package
@@ -89,7 +92,7 @@ Without `--include`/`--tree` it takes the entrypoint, the libraries beside it, `
defaults to the checkout's commit (`-dirty` when the tree has changes). It prints the size, file count and the SHA-256 of
the manifest file (which holds every file's hash), used as the package's digest in notes.
-## What each target's package holds (S1, local, unpublished)
+## What each target's package holds
| Package | Built on | Contents | Notes |
|---|---|---|---|
@@ -98,7 +101,7 @@ the manifest file (which holds every file's hash), used as the package's digest
| `windows-x86_64` hip | the owner PC, `tools/hip/build_windows.bat` (ROCm 10.2 nightly wheels) then `tools/hip/package_windows.py` | `strata.exe`, `strata-device.exe`, the ROCm DLLs and the rocBLAS/hipBLASLt kernels of the zip (`--tree`) | no Windows AMD test machine yet; with `STRATA_NO_VISION` unset it also builds the two picture readers (`strata-vision.exe` on the CPU, `strata-vision-hip.exe` on the GPU) |
| `linux-x86_64` cuda | a Linux box with the CUDA toolkit | `strata`, `libstrata_kq.so`, `libcudart/libcublas/libcublasLt` (13.x) | the GPU driver's `libcuda` stays the PC's |
| `linux-x86_64` hip | a box with ROCm (the Python wheels are enough) | `strata`, the HIP runtime, hipBLAS/hipBLASLt/rocBLAS, comgr + libLLVM, `rocblas/library` and `hipblaslt/library` for the listed gfx archs; `packaging/build_hip_linux.sh` builds it with both picture readers |
-| `linux-x86_64` hip, gfx1103 (Radeon 780M / Phoenix iGPU) | `packaging/build_hip_gfx1103.sh` on the mini PC (TheRock gfx110X-all SDK) | the same set as the gfx1200/1201 package, with `rocblas/library` and `hipblaslt/library` for gfx1103 (600 MiB) | experimental, unvalidated: the iGPU resets now and then (MES REMOVE_QUEUE, notes-minipc.md); never kill the engine mid-request; run configs set `STRATA_NO_ARENA_THP=1`. `engine_component.resolve` picks a HIP package only when its `archs` list a gfx target the Linux kfd topology reports |
+| `linux-x86_64` hip, gfx1103 (Radeon 780M / Phoenix iGPU) | `packaging/build_hip_gfx1103.sh` on the mini PC (TheRock gfx110X-all SDK) | the same set as the gfx1200/1201 package, with `rocblas/library` and `hipblaslt/library` for gfx1103 (600 MiB) | experimental, unvalidated: the iGPU resets now and then (MES REMOVE_QUEUE); never kill the engine mid-request; run configs set `STRATA_NO_ARENA_THP=1`. `engine_component.resolve` picks a HIP package only when its `archs` list a gfx target the Linux kfd topology reports |
| `linux-x86_64` sycl | a box with oneAPI DPC++ | `strata` (JIT from SPIR-V), libsycl, the Unified Runtime adapters, MKL SYCL libraries | the Level Zero loader and compute runtime are the PC's driver |
| `macos-arm64` metal | an Apple Silicon Mac | `strata`, `metal/kernels/*.metal`, `metal/engine-msl/*.metal`, `metal/ggml-common.h`, `metal/data/*.bin` | the Metal engine compiles its kernel sources when it starts; since S1 it finds them beside the executable (`metal/src/resource_path.h`: environment variable, then `<exe dir>/metal/`, then the compiled-in source path) |
@@ -110,8 +113,9 @@ GPU architecture) into the folder `package_engine.py` packages; libraries the di
A HIP package carries two programs for pictures next to `strata` (`vision` in its BUILD.json): `strata-vision` is the CPU reader, which
needs nothing of the GPU runtime and starts on every PC, and `strata-vision-hip` is the same reader on the card (llama.cpp's HIP
-backend, built for the package's `archs`; BUILD.json `vision_archs`). Setup writes the run config with the GPU reader first and the CPU
-reader as `vision.cpu_exe`; when the GPU reader does not start (the card is not in its build, the HIP runtime does not load, the card is
+backend, built for the package's `archs`; BUILD.json `vision_archs`). Pictures are on by default. The reader runs on the CPU for a card under 24 GB and on the card from 24 GB, on every make of card (the rule is
+`strata_control/vision_reader.py`; `--vision gpu` or `--vision cpu` picks the other one for a model). When the run config names the GPU reader first
+and the CPU reader as `vision.cpu_exe`, and the GPU reader does not start (the card is not in its build, the HIP runtime does not load, the card is
busy) the server starts the CPU reader by itself and prints one line. Both programs have RUNPATH `$ORIGIN` on Linux; on Windows the
ROCm DLLs they import sit beside the programs or in `rocm/bin` (the engine's PATH entry, `lib_dirs`). `strata_control/vision_reader.py`
holds the choice; `tools/test_vision_reader.py` the tests.
diff --git a/packaging/README.md b/packaging/README.md
index 91b995efe..989ca1355 100644
--- a/packaging/README.md
+++ b/packaging/README.md
@@ -1,28 +1,33 @@
# Strata packaging: targets, recipes and locks
-Revision: Phase A. This directory holds the per-target build recipes and the machine-readable
+Revision: Strata 0.2.0. This directory holds the per-target build recipes and the machine-readable
manifests. **It describes what can be built where, and it is explicit about what has *not* been
built or tested.** Nothing here is a support claim.
+The installers carry the engine: the desktop installers hold an engine package for their platform and graphics card, and the first
+start copies it into the per-user component folder after checking every file against its manifest. A new install therefore starts a
+model without a download; later engines come from the signed feed ([UPDATES.md](UPDATES.md)). The Terminal install is the other
+route: one line, and the first model brings the engine for that PC from the same release.
+
## The target matrix
-A backend name alone is not a target. Each row is an OS × CPU ABI × backend tuple, and a row is
+A backend name alone is not a target. Each row is an OS x CPU ABI x backend tuple, and a row is
`qualified` only after the acceptance checklist has actually run on it.
-| Target tuple | App artifact | Engine package | Status on this Mac |
+| Target tuple | App artifact | Engine package | Status |
| --- | --- | --- | --- |
-| `macos-arm64-metal` | `.app` + `.dmg` (Tauri) | source-built `strata` | **built.** App self-test 8/8 from inside the mounted DMG; engine built from source and 17/17 kernel-parity suites pass on the real M4 GPU. Real-model inference **not run** (no pack fits 16 GiB / 21 GiB free). |
-| Terminal `darwin-arm64` | self-contained `.tar.gz` (42 MB) | any | **built and verified.** Runs from a moved directory in a clean environment with no usable system Python; serving, `status`, `timeskip` and `tune` all exercised on the bundled interpreter. |
-| `windows-x86_64-cuda` | NSIS `.exe` (Tauri) | `setup.py` / `tools/windows` | **not built here.** Config present; needs a Windows host with an NVIDIA GPU. |
-| `windows-x86_64-hip` | NSIS `.exe` (Tauri) | `tools/hip/build_windows.bat` | **not built here.** Needs Windows + AMD. |
-| `linux-x86_64-cuda` | AppImage (Tauri) | `setup.py` | **not built here.** Needs a Linux host with an NVIDIA GPU. |
-| `linux-x86_64-hip` | AppImage (Tauri) | `cmake -DSTRATA_ENABLE_HIP=ON` | **not built here.** Needs Linux + ROCm. |
-| `linux-x86_64-sycl` | AppImage (Tauri) | `sycl/setup_intel.py` | **not built here.** Needs Linux + Intel Arc. Documented upstream as experimental. |
-| `windows-x86_64-sycl` | — | — | **gated.** No native Windows SYCL path exists upstream; it needs a separate feasibility gate, not a recipe. |
-| `macos-x86_64-*` | — | — | **unsupported.** The macOS engine is Apple-Silicon only (`metal/CMakeLists.txt` requires Apple Silicon for the Metal runtime). |
+| `macos-arm64-metal` | `.app` + `.dmg` (Tauri) | Metal `strata`, bundled | **built.** The app's self-test passed from inside the mounted DMG and the engine's 17 kernel-parity suites pass on an Apple M4 GPU. A large model does not fit the 16 GiB test Mac. No picture reader on Mac yet. Signing and notarising: `packaging/mac/sign-and-notarize.sh` (see [mac/README.md](mac/README.md)); it has been run with stand-ins for Apple's service, not yet against the real one. |
+| Terminal `darwin-arm64` | self-contained `.tar.gz` | any | **built and verified.** Runs from a moved directory in a clean environment with no usable system Python. |
+| `windows-x86_64-cuda` | NSIS `.exe` (Tauri) | `cuda13` and `cuda12` packages | **built and tested** on a Windows PC with an NVIDIA card: silent install with a PATH of System32 only, a real model, an agent chat. |
+| `windows-x86_64-hip` | NSIS `.exe` (Tauri) | `tools/hip/build_windows.bat` | **built; never run on a real AMD card.** |
+| `linux-x86_64-cuda` | AppImage (Tauri) | `setup.py`; built in a glibc 2.35 chroot | **cuda13 built and tested** (RTX 3060 and RTX A4000: app in the browser, a real model, a picture). cuda12 built. |
+| `linux-x86_64-hip` | AppImage (Tauri) | `packaging/build_hip_linux.sh` | **RX 9000 (gfx1200 / gfx1201) built and tested** on a Radeon AI PRO R9700. **RX 7000 (gfx1100 / 1101 / 1102) built; not run on an RX 7000 card.** |
+| `linux-x86_64-sycl` | | `sycl/setup_intel.py` | Documented as experimental ([INTEL.md](../docs/INTEL.md)). |
+| `windows-x86_64-sycl` | none | none | **gated.** No native Windows SYCL path exists upstream; it needs a separate feasibility gate, not a recipe. |
+| `macos-x86_64-*` | none | none | **unsupported.** The macOS engine is Apple-Silicon only (`metal/CMakeLists.txt` requires Apple Silicon for the Metal runtime). |
**Cross-compilation is not attempted for the desktop app.** Tauri bundles are per-OS and the
-Windows installer must be produced on Windows. What *is* portable, and therefore tested here, is
+Windows installer must be produced on Windows. What *is* portable is
everything below the carrier: the Python contracts, the owner transport, the checks, and the engine
build recipes.
@@ -91,13 +96,13 @@ with the shell (a kill-on-close Job Object around the app on Windows; the host w
single instance: a second launch focuses the open window. One app can run several engines (profiles `app-1`, `app-2`, ...).
docs/CLOSING.md has every close path and how each is tested.
-**The engine** is not in the installer. It is a component in the per-user component folder
+**The engine** comes with the installer (`<install>/engine-bundle/<package folder>`, the same layout as below); the first start checks it against its own manifest and copies it into the per-user component folder, where Control finds it like any engine that `strata update` installed. It is a component in the per-user component folder
(`%LOCALAPPDATA%\Strata\components`, `$XDG_DATA_HOME/strata/components`, or `STRATA_COMPONENTS_DIR`):
components/engine/<version>-<platform>-<backend>/
engine-component.json schema 2: id/name "strata-engine", version, platform, backend, archs, min_driver,
build_id, min_runtime (optional), entrypoint, files [{path, sha256, bytes}],
- signature (null until S6); full table and the checks in ENGINE-COMPONENT.md
+ signature (null for a local package, set by the release feed); full table and the checks in ENGINE-COMPONENT.md
strata[.exe] *.dll | *.so the binary and the GPU runtime libraries beside it
A run config names it as `"exe": "component:strata-engine"`; at start `strata_control/engine_component.py` picks the package
@@ -105,8 +110,10 @@ for this PC (platform, then the backend its GPU needs: nvidia-smi / rocminfo / s
architectures, `min_driver` and `min_runtime` are checked; the newest version wins), checks every file's size and
SHA-256 (a start hashes the whole package; a mismatch is `EngineIntegrityError` and nothing starts) and puts the package
folder first on the library path.
-Nothing matching is `EngineMissing`: exit 5, "No engine for this PC was found in ... The app never downloads an engine
-while it starts or serves", and no fetch. `packaging/package_engine.py` makes a local package from a build folder.
+Nothing matching is `EngineMissing`: `strata serve` ends with exit 5 and "No engine for this PC was found in ... The app never downloads an engine
+while it starts or serves", and no fetch. That is the start itself. Everything before it is a warning, not a refusal: `strata launch` says in plain
+words that it could not find an engine for this computer, asks whether to go on (Enter means yes), downloads the model and ends with the next step
+(exit code 0, nothing started), and the app shows the same warning with an "Update engine" button in Settings. `packaging/package_engine.py` makes a local package from a build folder.
**No acquisition at run time.** `STRATA_NO_ACQUIRE=1` (set by the Tauri shell for the host, and for Control by the host)
makes `strata_control/acquisition.py` refuse pip, downloads and compiles; on the host side `server/acquisition.mjs`
@@ -127,8 +134,10 @@ user chooses to download are a separate, explicit action. `apps/host/tests/no-ac
* There is no CI. Every recipe here is written to be run by hand; making them automated is separate
work.
-* No signing or notarization assets, and no update-feed bootstrap trust. Both need owner-supplied
- credentials (work plan D04).
+* Signing needs the owner's credentials, which are never in this tree. The update feed and every engine package are signed with the feed key
+ (`feed_tool.py`, [UPDATES.md](UPDATES.md)); the app installers with the Tauri updater key. The Mac app and Terminal archive are signed and
+ notarised on a Mac that holds the Developer ID certificate, with `packaging/mac/sign-and-notarize.sh` ([mac/README.md](mac/README.md)). No
+ Windows code-signing certificate is configured in this tree; Windows may warn about an installer that is not signed.
* No font or asset redistribution evidence has been gathered (D05). The app currently ships the
brand assets from the supplied UI ZIP, which is fine for an internal candidate and not sufficient
for redistribution.
diff --git a/packaging/UPDATES.md b/packaging/UPDATES.md
index d938a11cd..90afe9b73 100644
--- a/packaging/UPDATES.md
+++ b/packaging/UPDATES.md
@@ -104,7 +104,7 @@ Then, in git, once, in the commit that ships the first signed release:
* the Tauri public key into `apps/desktop/src-tauri/tauri.conf.json` (`plugins.updater.pubkey`) and into `update_keys.json` as `app_minisign_public`
(the Terminal verifies the app installer with it).
-Until then `update_keys.json` is empty and every feed is refused with "this build trusts no update key": a build with no key cannot install anything.
+A build whose `update_keys.json` has no key refuses every feed with "this build trusts no update key": it cannot install anything, which is why the keys go into the release commit.
A key rotation is a release that carries both public keys; the old private key signs that release, the new one signs the next.
## Releasing (when the owner says go)
@@ -116,12 +116,13 @@ A key rotation is a release that carries both public keys; the old private key s
python packaging/feed_tool.py build-feed --out RELEASE --sequence N --key <feed-key.json> --engine RELEASE/engine --control RELEASE/control --app-json <tauri latest.json>
python packaging/feed_tool.py verify-feed RELEASE --pub <feed-key.pub.json>
-Where the feed is hosted (GitHub release assets, a static host, ...) is the owner's decision; the default address in
-`strata_cli/update_cmd.py` is a placeholder until then, and nothing in this tree uploads anything.
+The feed is hosted as the assets of the latest GitHub release of Niko1221/Strata. `strata update` reads
+`https://github.com/Niko1221/Strata/releases/latest/download/strata-feed.json` (with `strata-feed.json.sig` beside it; this is the default in `strata_cli/update_cmd.py`),
+`install.sh` and `install.ps1` use the same folder, and the app updater reads `.../latest/download/latest.json`. `--feed URL|DIR` or `STRATA_FEED` points a PC at another feed, for example a local test feed. Nothing in this tree uploads anything.
## Testing locally
Everything above runs against a folder or a loopback server: `tests/terminal/test_update_feed.py` (signatures, hashes, downgrades, selection),
`tests/terminal/test_updater.py` (end to end against a loopback HTTP feed with stub engines: update, test-start, switch; a failing test start
keeps the old engine; an interrupted download resumes; rollback; Control; the app installer's minisign check), `apps/host/tests/component-updates.test.mjs`
-(the Settings buttons). For a real engine on a box: `phaseA-tests/split/s6/` (prepare + driver).
+(the Settings buttons). For a real engine on a box, build a package with `packaging/package_engine.py`, serve it from a local feed made by `packaging/make_local_feed.py`, and run `strata update --feed` against it.