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.mdindex 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, servesit 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 theserver, 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 toolcall 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 codediff --git a/docs/AI_SETUP.md b/docs/AI_SETUP.mdindex 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.