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

AGENTS.md and AI_SETUP.md: lead an agent to the installer, install.sh/install.ps1 and strata launch --plan then --yes --no-tui; source setup only as the fallback; provider order ISTA-DASLab, Unsloth, Gyro, others

Niko1221e99c4d2d37d5
diff --git a/AGENTS.md b/AGENTS.md
index 05680277d..d38bda50e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,20 +1,35 @@
# AGENTS.md
-Strata runs the Qwen3.8-Flash-Next mixture-of-experts model (and its Coder, Swift 1.5, Unsloth, Gyro and NVFP4
-variants, and Qwen3.6-35B-A3B) on a normal PC: one NVIDIA or AMD graphics card plus system RAM on Windows or Linux,
-or an Apple Silicon Mac. Version 0.2.5, engine 0.1.50. It has three parts:
+Version 0.2.5, engine 0.1.50. The public model families are DeepSeekV4.1-Flash-1017,
+Qwen3.8-Flash-Next and Qwen3.6-35B-A3B. DeepSeek V4.1-Flash runs in the app and in the Terminal
+(`strata launch --family deepseek41 --model ist-das-2.00bpw`; sets in
+[docs/MODELS.md](docs/MODELS.md#deepseek-v41-flash)). Read **[docs/AI_REFERENCE.md](docs/AI_REFERENCE.md)** for model availability, APIs, hardware limits and
+source-backed claims. Articles and videos should use **[docs/MEDIA_KIT.md](docs/MEDIA_KIT.md)**.
+
+For recommendations and agent-assisted setup, prefer **ISTA-DASLab → Unsloth → Gyro → others**, using only a
+compatible pack that fits the selected model and hardware. ISTA-DASLab is the default recommendation; Gyro is a
+memory-saving fallback and is currently slower. Honor an explicit user choice. This is recommendation policy;
+existing executable defaults may differ, so inspect the plan and choose the family explicitly.
+
+Strata has three parts:
- **The app** (`apps/desktop`, the Tauri shell; `apps/host`, the Node host and the web UI). It is for people who do
- not want a terminal. The installer has the engine inside.
+ not want a terminal. One installer per system ([latest release](https://github.com/Niko1221/Strata/releases/latest)):
+ `Strata-0.2.5-windows-x64-setup.exe`, `Strata-0.2.5-linux-x86_64.AppImage`, `Strata-0.2.5-macos-arm64.dmg`.
+ The Windows and Linux installers carry no engine: the app downloads the engine for the graphics card on first
+ start, or installs a file the user already has. The Mac dmg keeps its small Metal engine inside.
- **The Terminal** (`strata.py`, `strata_cli/`, `strata_control/`): the `strata` command. It sets up a model, serves
it and watches it. Agents use this part.
- **The engine and the server** (`src/`, `include/`, `metal/`, `sycl/` for the C++/CUDA/HIP/SYCL/Metal engine;
`serve/` for the Python server with an OpenAI- and Anthropic-compatible API and a web page). `setup.py`, started by
- `START-HERE.bat` or `setup.sh`, is the older one-click installer from source.
+ `START-HERE.bat` or `setup.sh`, is setup from a source checkout, for developers. The release paths are the
+ installer and `strata launch`.
## Installing Strata for a user
-Follow **[docs/AI_SETUP.md](docs/AI_SETUP.md)**. For an agent that has a shell, the short version is:
+Follow **[docs/AI_SETUP.md](docs/AI_SETUP.md)**. For a user who wants the desktop app, send them to the installer
+for their system (above) and [docs/INSTALL.md](docs/INSTALL.md). For an agent that has a shell, use the Terminal; the
+short version is:
1. Install the Terminal. It needs no administrator rights.
@@ -27,27 +42,28 @@ Follow **[docs/AI_SETUP.md](docs/AI_SETUP.md)**. For an agent that has a shell,
2. Check what would happen. Nothing is changed:
```sh
- strata launch --plan --model q2_0
+ strata launch --plan --family qwen --model q2_0
```
3. Set up and serve without questions. It downloads the engine for the card and the model (tens of GB), starts the
server, prints the addresses and returns. The server keeps running.
```sh
- strata launch --model q2_0 --yes --no-tui
+ strata launch --family qwen --model q2_0 --yes --no-tui
```
Useful flags (all of them: `strata launch --help`): `--family`, `--model-path` (files the user already has),
`--data-dir`, `--context 32k|64k|128k`, `--vision off|on|gpu|cpu`, `--parallel N`, `--gpu 0,1`,
`--access local|lan|cloudflare|tailscale`, `--port`, `--api-key-env NAME`, `--new-key`, `--save-preset NAME`,
- `--output json`. `strata launch --status` shows what is serving, `strata launch --stop` stops it, and
+ `--speed faster|full` (DeepSeek), `--output json`. `strata launch --status` shows what is serving, `strata launch --stop` stops it, and
`strata launch --show-key` prints the API key.
4. Connect the user's apps: `strata connect` lists them, `strata connect <app> --check` sends one prompt and one tool
call the way that app does.
-Keep the server on `127.0.0.1` unless the user asks for more. Beyond it an API key is recommended: `--access lan` makes one for you, and `--no-api-key` serves without one (a warning, never a refusal; on a public tunnel the warning is stronger). The old route (clone
-the repository and run `START-HERE.bat --yes` or `./setup.sh --yes`) still works and is the fallback when the
-Terminal cannot run. Strata's MCP server ([docs/MCP_SERVER.md](docs/MCP_SERVER.md)) offers the same steps as tools.
+Keep the server on `127.0.0.1` unless the user asks for more. Beyond it an API key is recommended: `--access lan` makes one for you, and `--no-api-key` serves without one (a warning, never a refusal; on a public tunnel the warning is stronger). Source setup (`START-HERE.bat`, `setup.sh`) is the fallback for a developer or for a system with no release package; it is
+documented in [docs/SOURCE_INSTALL.md](docs/SOURCE_INSTALL.md). Those wrappers exist in a source checkout, not in the
+released app. Do not tell an app user to find a `.bat` file.
+Source setup does not make an unsupported model or backend compatible. Strata's MCP server ([docs/MCP_SERVER.md](docs/MCP_SERVER.md)) offers the same steps as tools.
## Working on the code
diff --git a/docs/AI_SETUP.md b/docs/AI_SETUP.md
index 5d8be6739..bfe87d5da 100644
--- a/docs/AI_SETUP.md
+++ b/docs/AI_SETUP.md
@@ -1,288 +1,172 @@
-# Installing Strata for a user (instructions for AI agents)
-
-This page is written for an AI coding assistant (Claude Code, Cursor, Codex, GitHub Copilot, ...) that a user asked to
-set up Strata on their PC. Strata runs the Qwen3.8-Flash-Next model locally on one NVIDIA or AMD graphics card plus
-system RAM (or on an Apple Silicon Mac), and serves an OpenAI- and Anthropic-compatible API on `http://127.0.0.1:8080`.
-The human-oriented version of everything below is [INSTALL.md](INSTALL.md).
-
-You use the **Terminal**: the `strata` command. Install it with one line, then `strata launch` downloads the engine
-for the card and the model, and starts the server. If the Terminal cannot run on this PC, step 9 has the older route
-from source.
-
-Work through the steps in order. Tell the user what you are doing in plain words; they may not be technical.
-
-## 0. Ground rules
-
-- **Recommend an API key beyond this computer; do not force it.** Keep the default (`--access local`, the server listens on
- `127.0.0.1` only, no key needed). Only if the user asks for access from other devices, use `--access lan`. Strata makes a long
- random key for you then. Give the user the key (`strata launch --show-key`). If the user says they do not want a key, use
- `--no-api-key`: it starts and warns that anyone who can reach the port can use the model and its tools. Tell the user so.
- Do not put a tunnel or port forward in front of a server without a key unless the user asks for it.
-- Do not change the user's system beyond what Strata does. The Terminal installs into the user's home folder and needs
- no administrator rights. It does not install drivers, Python packages or compilers. Ask before installing drivers.
-- The model download is ~70 GB (94 GB for Unsloth's UD-IQ4_XS, 111 GB for UD-Q4_K_XL). Confirm the user is fine with
- that before you start, especially on a metered connection.
-- The first `strata launch` is long-running (an hour or more on a slow connection). Run it in the background or with a
- long timeout and poll its output; do not kill it because it is quiet for a while. It is resumable: running the same
- command again continues where it stopped.
-- Piping a script from the internet into a shell runs code you have not read. Tell the user what the line does (step 2).
- If they prefer, download the script first, show it, and run it only after they agree.
-
-## 1. Check the PC
-
-Requirements (details: [INSTALL.md](INSTALL.md#what-you-need)):
-
-- **GPU:** NVIDIA RTX 20, 30, 40 or 50 series, or AMD Radeon RX 7900 XT / XTX, RX 7800 XT / 7700 XT, RX 9060 XT,
- RX 9070 / 9070 XT, Radeon AI PRO R9700, RX 6800 / 6900 series; 12 GB of VRAM or more (an NVIDIA card with 8 GB runs,
- slowly). GTX 10 series and older, and integrated GPUs, are not supported; Pascal / Volta cards (P40, V100) and some
- older AMD cards have experimental paths the user opts into ([OLDER_GPUS.md](OLDER_GPUS.md)). A **Mac** needs Apple
- Silicon (M1 or newer), macOS 15 or newer and 16 GB of memory or more ([MAC.md](MAC.md)).
-- **Driver:** NVIDIA 580 or newer. AMD on Linux: the kernel's amdgpu driver; on Windows: a current AMD Adrenalin
- driver. If the driver is missing or too old, tell the user to update it (NVIDIA App / nvidia.com/drivers, or AMD
- Software) and restart; do not install drivers yourself unless they ask.
-- **RAM:** 32 GB or more (see step 3). **Disk:** ~80 GB free, ideally on an NVMe SSD. **CPU:** x86-64 with AVX2.
- Without AVX2 (Xeon E5 v1/v2 and older) the ready-made engine refuses to start; the route from source builds an
- experimental and slow engine on the PC (10-20 minutes): tell the user that before starting
- ([INSTALL.md](INSTALL.md#older-cpus-experimental)).
-- **OS:** Windows 10/11, Linux x86-64 (Ubuntu 22.04/24.04 and Debian 12/13 are fully automatic), or macOS on Apple Silicon.
-
-To check by hand:
-
-| What | Windows (PowerShell) | Linux | Mac |
-| --- | --- | --- | --- |
-| OS | `[Environment]::OSVersion` | `cat /etc/os-release` | `sw_vers` |
-| NVIDIA GPU, VRAM, driver | `nvidia-smi --query-gpu=index,name,memory.total,driver_version --format=csv` | the same | - |
-| AMD GPU | `Get-CimInstance Win32_VideoController \| Select-Object Name, AdapterRAM` (AdapterRAM is capped at 4 GB; trust the model name) | `lspci \| grep -i -E 'vga\|display'`; VRAM: `cat /sys/class/drm/card*/device/mem_info_vram_total` (bytes); `rocm-smi` only if ROCm is installed | - |
-| RAM | `(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB` | `free -g` | `sysctl -n hw.memsize` (bytes) |
-| Free disk | `Get-PSDrive -PSProvider FileSystem` | `df -h .` | `df -h ~` |
-
-If the PC does not meet them, say which part is missing and stop.
+# Set up Strata for a user
+
+Use this guide when a user asks an AI agent to install Strata (version 0.2.5). There are two release routes. Pick
+one; do not start from a source checkout.
+
+- **The Terminal and `strata launch`** (below). This is the route for an agent that has a shell.
+- **The desktop app.** One installer per system: `Strata-0.2.5-windows-x64-setup.exe`,
+ `Strata-0.2.5-linux-x86_64.AppImage`, `Strata-0.2.5-macos-arm64.dmg`, from the
+ [latest release](https://github.com/Niko1221/Strata/releases/latest). The Windows and Linux installers carry no
+ engine: on first start the app shows the engine for the user's graphics card and downloads it, or installs a file the
+ user already has ("I already have the file"). Details: [INSTALL.md](INSTALL.md).
+
+Model availability, provider preference and API details are in [AI_REFERENCE.md](AI_REFERENCE.md).
+
+## 1. Check the computer and the requested model
+
+- Check OS, CPU architecture, graphics cards, driver, available RAM/VRAM and free disk space.
+- Use the [hardware guides](INSTALL.md#what-you-need). Linux and Windows packages are x86-64; Mac packages are
+ Apple Silicon and need macOS 15 or newer. Older GPUs, Intel Arc and low-memory machines have specific limits.
+- Model support is separate from hardware support. Qwen3.6 currently uses CUDA or HIP; it is not a Metal/SYCL model.
+ DeepSeekV4.1-Flash-1017 (`--family deepseek41`) runs in the app and in the Terminal, on NVIDIA RTX 30, 40 and 50
+ (Windows and Linux) and on the AMD Radeon AI PRO R9700 under Linux. It has three sets: 1.75 bpw (239 GB of disk),
+ 2.00 bpw (257 GB) and 2.25 bpw (274 GB), and for a 12 GB card it needs 46 to 64 GB of RAM. The context is 8K.
+ `--speed faster|full` (or `--full-quality`) chooses how many experts it uses per word; Faster is the default on a
+ PC with 16 GB of graphics memory or less. Print the plan first:
+ `strata launch --plan --family deepseek41 --model ist-das-2.00bpw`.
+- Check the **chosen pack's** memory and disk needs. Do not reuse a Flash-Next estimate for every family.
+ Unified memory is one pool, not RAM plus VRAM. A completed download does not establish that a model can run.
+- Keep the default local-only access. Share the server over a network only when the user asks; recommend an API key
+ beyond localhost and explain any deliberate use of `--no-api-key`.
+- Explain substantial downloads and follow the user's existing authorization and network/storage constraints.
+ Do not install drivers or system build tools as an unannounced side effect of a normal Terminal install.
## 2. Install the Terminal
-One line. It needs no administrator rights. It checks what kind of PC this is, downloads the Terminal archive, checks
-its SHA-256, unpacks it into the user's home folder, checks the release's signed update feed, and puts `strata` on the
-PATH.
+The installer downloads a private Python runtime and Control, verifies the release checksums and signed feed, and
+installs into the user's home folder. The engine and model are acquired during launch.
+**Linux / Mac:**
+
+```sh
+curl -fsSL https://github.com/Niko1221/Strata/releases/latest/download/install.sh -o install.sh && sh install.sh
```
-Linux, Mac: curl -fsSL https://github.com/Niko1221/Strata/releases/latest/download/install.sh -o install.sh && sh install.sh
-Windows (PowerShell): irm https://github.com/Niko1221/Strata/releases/latest/download/install.ps1 | iex
-```
-On Windows, open a new terminal window afterwards (the PATH changed). Check it: `strata --version`.
+**Windows PowerShell:**
+
+```powershell
+irm https://github.com/Niko1221/Strata/releases/latest/download/install.ps1 | iex
+```
-## 3. Pick the model
+Open a new terminal on Windows. On Linux and Mac, use the full executable path printed by the installer if
+`~/.local/bin` is not on PATH. Confirm with `strata --version` and `strata launch --help`.
+Do not search for `START-HERE.bat` in the installed app or Terminal: it is not part of them.
-`strata launch --plan` shows what Strata would do and changes nothing. With no `--model` it picks the model for this
-PC's RAM and prints the exact command line (`same as strata launch --model ...`). Use it as the default, or pick
-yourself by the PC's RAM (ask the user whether they mainly want it for code - then the Coder is a good pick at any RAM
-size):
+## 3. Select a compatible pack and inspect the plan
-| RAM | `--model` (and `--family`) | Notes |
-| --- | --- | --- |
-| 32 GB | `--family coder --model iq1_m` | for code; with a 24 GB card Q2_0 and IQ2_XS also run (Strata picks the low-RAM mode) |
-| 48 GB | `--model iq2_xs` | or `q2_0` (fastest) |
-| 64 GB | `--model iq2_xs` (recommended) | `iq3_xxs` / `iq3_s` are slower and a bit better |
-| 96 GB+ | `--model iq3_s` | `--family unsloth --model ud-iq4_xs` (~4-bit, 94 GB, part of the experts read from the SSD under ~80 GB of RAM); `ud-q4_k_xl` is experimental: NVIDIA only, NVMe SSD, 7-8.5 tokens/s on 64 GB |
+Keep the user's model and provider choice. Otherwise prefer **ISTA-DASLab → Unsloth → Gyro → others**, when a pack
+fits the selected model and computer. This is the maintainer's recommendation policy; current executable defaults
+can differ. Gyro is a memory-saving fallback, currently slower, not a general speed recommendation.
-`--family swift` (Swift 1.5, a fine-tune that thinks shorter; sizes IQ2_XS, IQ3_XXS, IQ3_S) is the
-alternative to `qwen`. A model name is not case sensitive. More: [MODELS.md](MODELS.md).
+| Choice | Explicit launch selection |
+| --- | --- |
+| ISTA-DASLab Flash-Next | `--family qwen --model q2_0` (or a compatible IQ2_XS / IQ3_XXS / IQ3_S pack) |
+| ISTA-DASLab Coder | `--family coder --model IQ1_M` |
+| Unsloth Flash-Next | `--family unsloth --model UD-Q4_K_XL` (check the pack's backend limits) |
+| Gyro Flash-Next | `--family gyro --model Gyro-S` |
+| Unsloth Qwen3.6 | `--family qwen36 --model UD-Q4_K_XL` |
-## 4. Set up and serve, without questions
+These are choices, not an instruction to install every row. The full list and memory estimates are in
+[MODELS.md](MODELS.md). For example, inspect the ISTA-DASLab Q2_0 plan:
-```
-strata launch --plan --model iq2_xs # what would happen; nothing is changed
-strata launch --model iq2_xs --yes --no-tui # do it: download the engine and the model, start the server
+```sh
+strata launch --family qwen --model q2_0 --context 32k --plan --output json
```
-With `--no-tui` and `--yes` it asks nothing, prints the addresses when the server is ready, and returns. The server
-keeps running in the background. `strata launch` with no `--model`, `--preset` or other choice needs a terminal for
-its screens, so an agent always names the model. Add `--output json` for output a script can read.
+Check the resolved family, model, storage folder, context, picture reader and missing downloads. If the plan names
+an unavailable backend, do not continue as though compatibility were confirmed. Intel Arc has a released Linux
+engine, but model preparation still has special requirements: [INTEL_ARC.md](INTEL_ARC.md).
-The flags (all of them, with examples: `strata launch --help`):
+## 4. Start it
-| Flag | Meaning |
-| --- | --- |
-| `--model NAME` | the size: `q2_0`, `iq2_xs`, `iq3_xxs`, `iq3_s`, `iq1_m`, `ud-iq4_xs`, `ud-q4_k_xl`, ... (the error message for a wrong name lists them) |
-| `--family NAME` | the model version when several have that size: `qwen`, `swift`, `coder`, `unsloth` |
-| `--model-path PATH` | files the user already has: a folder of shards or one `.gguf` file |
-| `--data-dir DIR` | where new model files go. Models you already have stay where they are and stay usable; add `--move-data` to move them into DIR |
-| `--context SIZE` | `32k`, `64k`, `128k`, `256k` or a number of tokens |
-| `--vision off\|on\|gpu\|cpu` | read pictures. On by default when the model can read them: the reader runs on the CPU for a card under 24 GB and on the GPU from 24 GB, on NVIDIA and AMD cards. `off` turns it off |
-| `--parallel N` | requests answered at the same time, 1 to 8 (default: fit to the card) |
-| `--gpu LIST` | card numbers, e.g. `0` or `0,1` (several cards share the model) |
-| `--tune quick\|thorough\|skip` | find the fastest settings first (default here: `skip`) |
-| `--access local\|lan\|cloudflare\|tailscale` | who can connect; beyond `local` a key is made for you |
-| `--port N` | the server port (default 8080) |
-| `--api-key KEY`, `--api-key-env NAME`, `--new-key` | the key clients must send |
-| `--no-api-key` | share without a key (a warning, not a refusal; recommended only on a network you trust) |
-| `--save-preset NAME` | keep these choices; `strata launch --preset NAME` starts them again |
-| `--plan` | show what would happen and exit |
-| `--yes`, `--no-tui` | no questions, no screens |
-| `--status`, `--stop`, `--show-key` | what is serving, stop it, print the key |
-
-Notes:
-- **No engine for this PC.** `strata launch` does not refuse. It says "Strata couldn't find an engine for this computer",
- goes on to download the model (with `--yes` it does not ask), and ends without starting anything (exit code 0; with `--output json` the answer
- has `"serving": false` and an `engine_problem`). Tell the user which card was not recognised and stop. Updating the
- engine later with `strata update` can fix it.
-- **Exit codes:** 0 done, 2 a flag or name is wrong, 5 the Terminal or the engine cannot do it, 6 an install or the
- server start failed (the engine log is named in the message), 130 stopped.
-- **Linux:** nothing needs `sudo`: the Terminal does not install packages. **Windows:** the first start may ask once
- whether to allow Strata on the network if you used `--access lan`.
-- **AMD on Windows:** only the AMD driver is needed. The AMD engine is a ready-made download. It has not been run with a
- model on a real AMD card on Windows by us: ask the user to report how it runs ([AMD_HIP.md](AMD_HIP.md)).
-- **Mac:** the Metal engine is fetched like any other. Pictures are on by default and read on the Mac's GPU ([MAC.md](MAC.md)).
-
-## 5. While it downloads, tell the user
-
-- It downloads about 70 GB from Hugging Face; how long depends on their connection (at 100 Mbit/s roughly 1.5-2
- hours). It can be stopped and continues where it left off.
-- Then it prepares the model for their PC (a few minutes).
-- **When the model starts, the PC can be slow or stop responding for 1-3 minutes** (longest the first time): Strata
- loads 35-55 GB into RAM and locks part of it for the graphics card. That is normal; they should not close the window.
-- Nothing leaves their PC: the model runs locally.
-
-## 6. Check that it is serving
-
-`strata launch` prints `Strata is serving.` with the addresses when it is done. Later:
+After the plan matches the user's computer and requested setup:
-```
-strata launch --status # lists what is serving, with its address
-strata launch --stop # stops it and frees the graphics memory
-strata launch --preset NAME # starts a saved preset again (after --save-preset NAME)
+```sh
+strata launch --family qwen --model q2_0 --context 32k --yes --no-tui
```
-No browser opens by itself. Add `--open` to `strata launch` if the user wants the web page.
+`--no-tui` prints the address and returns after startup while the server continues in the background. Keep the
+launch process alive during model acquisition; large downloads and preparation can take a long time. Poll progress
+and logs rather than promising a universal startup time. Repeating an interrupted launch resumes completed work.
-## 7. Verify
+Useful options:
-The HTTP server answers once the model is loaded (30-90 s on later starts, a few minutes the first time). Poll:
+| Option | Meaning |
+| --- | --- |
+| `--model-path PATH` | Use existing supported model files; a matching filename alone does not prove compatibility |
+| `--data-dir PATH` | Folder for new downloads; existing files stay put unless `--move-data` is also given |
+| `--vision on\|off\|gpu\|cpu` | Picture reading, subject to model and packaged-reader support |
+| `--gpu 0,1` | Selected GPUs; do not use source setup's `--gpus` spelling here |
+| `--parallel N` | Requested concurrent slots, 1–8; check what actually fits and starts |
+| `--save-preset NAME` | Keep these launch choices for later |
+| `--open` | Open the server's browser page after it starts |
+| `--restart` | Replace an already running launch with different settings; interrupts active answers |
-```
-curl http://127.0.0.1:8080/health
-```
+`--yes` does not authorize a restart by itself. When a model is already running, inspect its state before using
+`--restart` or `--stop`. Use `strata launch --help` for the installed release's full list.
-It returns `{"status": "ok", "model": ..., "max_context": ..., "images": ..., "api_key": ..., "loaded": true, ...}`.
-Then:
+## 5. Verify the running service
-```
-curl http://127.0.0.1:8080/v1/models
-curl http://127.0.0.1:8080/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"strata\", \"messages\": [{\"role\": \"user\", \"content\": \"Say hello in five words.\"}], \"max_tokens\": 64, \"reasoning_effort\": \"none\"}"
+```sh
+strata launch --status
+strata doctor --live
```
-With an API key, add `-H "Authorization: Bearer <key>"`.
+Check the printed address and model, then query `/health` and `/v1/models` at that address. With the default port:
-## 8. Connect the user's apps
+**Linux / Mac:**
-- **Browser:** `http://127.0.0.1:8080` - Chat, a live Monitor, and About (settings and addresses).
-- **Any OpenAI-compatible app or agent:** base URL `http://127.0.0.1:8080/v1`, any API key (or the configured one),
- any model name.
-- **Anthropic-compatible apps:** base URL `http://127.0.0.1:8080`, without `/v1`. Those apps add `/v1/messages`
- themselves.
-- **Codex CLI and other Responses API apps:** `http://127.0.0.1:8080/v1/responses` (stateless; Codex's
- `config.toml`: [DETAILS.md](DETAILS.md#the-responses-api-and-codex-cli)).
-- **Claude Code:** `ANTHROPIC_BASE_URL=http://127.0.0.1:8080`, `ANTHROPIC_MODEL` set to a Claude model name it knows
- (Strata ignores the name), and any `ANTHROPIC_AUTH_TOKEN` (or the configured key).
-- **The easy way for a coding app:** `strata connect` lists them (OpenCode, Codex CLI, Claude Code, oh-my-pi, pi,
- Hermes Agent, OpenClaw). `strata connect <app>` prints the file and environment for the running server,
- `strata connect <app> --write` writes it after asking (and keeps a backup), `strata connect <app> --check` sends
- one prompt and one tool call the way that app does and says whether each worked.
-- **Thinking level:** `"reasoning_effort": "none" | "low" | "medium" | "high"` (default high).
-- Strata answers one request at a time; `--parallel N` in `strata launch` decodes up to N together
- ([BATCHING.md](BATCHING.md)). API details: [DETAILS.md](DETAILS.md#using-it).
-
-## 9. If the Terminal cannot run: install from source
+```sh
+curl -fsS http://127.0.0.1:8080/health
+curl -fsS http://127.0.0.1:8080/v1/models
+```
-Use this only when step 2 does not work on the PC (for example a CPU without AVX2, or no internet access to GitHub
-Releases). It needs git or the zip, and on Linux `sudo` for Python and build tools.
+**Windows PowerShell:**
-```
-git clone https://github.com/Niko1221/Strata.git
+```powershell
+Invoke-RestMethod http://127.0.0.1:8080/health
+Invoke-RestMethod http://127.0.0.1:8080/v1/models
```
-Without git: download https://github.com/Niko1221/Strata/archive/refs/heads/main.zip and unzip it. Pick a drive with
-enough free space: the model files go to a `Strata-data` folder next to the Strata folder (or `--data-dir <path>`
-on another drive). Setup's own check prints the GPU(s), driver, RAM, CPU, free disk and whether this PC can run
-Strata, and installs nothing except Python and the `.venv` it needs to run:
+Use the configured credential for protected endpoints. Confirm the model is loaded, then send a real request or
+run the relevant tool check below. **Exit code 0 alone is insufficient:** launch can finish after downloading a model
+without starting it when no usable engine is available. Report that as downloaded, not installed and verified.
-```
-Windows: START-HERE.bat --check
-Linux: ./setup.sh --check
+## 6. Connect a tool
+
+```sh
+strata connect
+strata connect opencode
+strata connect opencode --check --output json
```
-Run setup without questions, from the Strata folder (Windows: in `cmd`, or `cmd /c START-HERE.bat ...` from PowerShell).
-The model is picked as in step 3, with setup's flag names (`--family qwen|swift|coder|unsloth --model Q2_0|IQ2_XS|...`):
+The first command lists adapters; the second prints settings; the third sends a prompt and tool-call check. Use the
+adapter the user actually needs. `--write` changes that tool's configuration and keeps a backup; use it within the
+user's authorization. Printed configuration and a previous vendor test are not a successful current-server check.
-```
-Windows: START-HERE.bat --yes --family qwen --model IQ2_XS --vision yes --no-start
-Linux: ./setup.sh --yes --family qwen --model IQ2_XS --vision yes --no-start
-```
+- OpenAI-compatible clients: use the printed server address plus `/v1`.
+- Anthropic-compatible clients: use the server root; the client adds `/v1/messages`.
+- Use the actual API key when enabled. Tool identifiers and limits: [connection guide](TERMINAL_LAUNCH.md#connect-your-apps-strata-connect).
+- Flash-Next's template defaults to thinking on with `xhigh` effort; `high` maps to `xhigh`. Requests, shared Chat
+ settings and run-config settings can override defaults. Do not assert a sampling configuration without inspecting it.
-The flags (all of them: `START-HERE.bat --help`):
+## 7. Handoff, update or stop
-| Flag | Meaning |
-| --- | --- |
-| `--yes` | take the recommended answer to every question (no prompts) |
-| `--family qwen\|swift\|coder\|unsloth` | the model version |
-| `--model Q2_0\|IQ2_XS\|IQ3_XXS\|IQ3_S\|IQ1_M\|UD-IQ4_XS\|UD-Q4_K_XL` | the size (the Coder is IQ1_M, Unsloth UD-IQ4_XS or UD-Q4_K_XL) |
-| `--context N` | context in tokens; default by VRAM: 32768 under 14 GB, 65536 under 20 GB, else 131072 |
-| `--vision yes\|no\|gpu\|cpu` | read pictures. Pass `yes` to get the best reader for the card (the CPU under 24 GB, the GPU from 24 GB, any make); `no` turns them off |
-| `--gpu N` / `--gpus 0,1` / `--gpus all` | one card, or several sharing the model (default: the card with the most VRAM) |
-| `--backend cuda\|hip` | NVIDIA or AMD engine; chosen by itself on a PC with only one kind of card |
-| `--data-dir PATH` | where new model files go. Nothing is moved unless you add `--move-data`; the saved default folder changes only with `--move-data` or `--set-default-data-dir` |
-| `--port N` | the server port (default 8080) |
-| `--host H --api-key K` | listen beyond this PC; only together with a key |
-| `--no-start` | install only, do not start the server |
-| `--setup` | install another model or change settings of an installed one |
-| `--check` | only check the PC |
-
-`--no-start` is recommended for agents: the server runs in the foreground until its window is closed, which would
-block your shell. Start it separately:
+Tell the user which model is running, where its files are, its address, how the tool check went, and any limitations.
-```
-Windows (PowerShell): Start-Process -FilePath ".\run-iq2_xs.bat" (opens its own window)
-Linux: nohup ./run-iq2_xs.sh > strata-server.out 2>&1 &
+```sh
+strata launch --preset NAME
+strata launch --status
+strata launch --stop
+strata update --check
```
-Setup prints the start script it wrote (`start script: run-<model>.bat`). The name is the family tag plus the size,
-lower case: `run-iq2_xs`, `run-swift-iq2_xs`, `run-coder-iq1_m`, `run-unsloth-ud-iq4_xs`. The engine log is
-`strata-<model>.log` in the Strata folder. Then continue with step 7.
-
-Notes:
-- **Linux:** setup uses `sudo apt` (or dnf/pacman) to install Python with venv if it is missing, and on AMD may need
- `build-essential` and `git`. You cannot type the user's password: if a `sudo` step is needed, ask the user to run it
- (e.g. `sudo apt install python3-venv build-essential git`) and then rerun setup.
-- **AMD on Linux:** setup installs ROCm into `.venv` (~10 GB, no sudo) unless a system ROCm 7 exists, and compiles the
- engine for the card (10-20 minutes, once).
-- **AMD on Windows:** setup downloads the ready-made AMD engine (~550 MB, ROCm included) - nothing is compiled and only
- the AMD driver is needed. Before the model download it runs `engine\strata-device.exe --list-devices`; if that does
- not list the card, the driver is the problem (tell the user to update AMD Software). One card per model. Pictures use
- the 24 GB rule like everywhere else.
-- **NVIDIA with no ready-made engine for the card:** setup offers to install build tools and compile (20-40 minutes);
- `--yes` accepts.
-- **Mac:** `./setup.sh` builds the Metal engine on the Mac (needs Apple's Command Line Tools, `xcode-select --install`).
-
-## 10. When something fails
-
-| Symptom | What to do |
-| --- | --- |
-| `the NVIDIA driver is too old` | The user updates the driver (NVIDIA App or nvidia.com/drivers) and restarts; run the command again. |
-| Download or install stopped | Run the same command again; it continues. |
-| `Strata couldn't find an engine for this computer` | The card is not one the engine packages cover, or the update feed was not reachable. Check the card against the list in step 1, check the internet, run `strata doctor`, then `strata update`. |
-| `port 8080 is already in use` | Strata is already running (check `/health` and `strata launch --status`), or use `--port 8081`. |
-| Very slow, disk busy, or "the engine stopped unexpectedly" | Not enough free RAM: close programs, or choose a smaller size (`q2_0` or `iq2_xs`). |
-| `ExpertCache: cudaMalloc(...) failed: out of memory` with free VRAM (Windows) | The page file is off or tiny: set a fixed size (Custom size, the same initial and maximum size, e.g. 65536 MB) and restart; a page file Windows grows on demand ("System managed") may not grow in time (#60). |
-| `prompt ... exceeds the context` | Start again with a bigger `--context`. |
-| No AMD GPU found (Linux) | The amdgpu driver lists no GPU; check the card and driver. Integrated GPUs are not supported. |
-| A Mac says the app is "damaged" (the app, not the Terminal) | The file is fine: [MAC.md](MAC.md) has the one command. |
-
-More: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) and the [full table](DETAILS.md#troubleshooting). If it still fails,
-run `strata doctor`, collect its output and the engine log named in the error message, and suggest an issue at
-https://github.com/Niko1221/Strata/issues.
-
-## Alternative: the MCP server
-
-Strata also has an MCP server, so an AI tool can check, install, start and stop Strata through tool calls
-(`strata_status`, `strata_models`, `strata_install`, `strata_start`, `strata_stop`, `strata_logs`) instead of the
-shell commands above. See [MCP_SERVER.md](MCP_SERVER.md).
+Stop active models before `strata update`. Very old Terminals require rerunning the installer; see
+[updating](INSTALL.md#updating). Show credentials only to the intended user; redact them from shared logs and reports.
+
+## 8. Source-only and unsupported setups
+
+A source build is a separate workflow: [SOURCE_INSTALL.md](SOURCE_INSTALL.md). `START-HERE.bat`, `SETUP.bat`,
+`UPDATE.bat`, `setup.sh` and generated `run-<model>` scripts belong to that workflow. Do not pass their flags to
+`strata launch`, promise a source build will support an unknown model, or describe a source-only command as an
+installed-app command. If a required backend or artifact is missing, say exactly what is missing.