This repository hosts runtime configuration for Atomic Chat Desktop and Atomic Chat Mobile. The desktop client fetches the manifest at startup and refreshes it periodically, so changes here propagate to installed desktop clients (macOS, Windows, Linux) without an application release.
Mobile uses separate production and dev catalogs. That document defines the mobile schema, metadata reuse and coordinated admin cutover; existing desktop manifests retain their current contracts.
TL;DR for non-developers — to add a new model or provider, edit
providers/registry.jsonon GitHub, open a Pull Request, get it reviewed, merge it. All running Atomic Chat clients will pick up the change within an hour.
providers/
registry.json # Single source of truth for cloud providers
schema.json # JSON Schema (Draft-07) used by CI validation
media.json # Image and video models of cloud and self-hosted providers (read by core)
schema.media.json # JSON Schema (Draft-07) for the remote media catalog
models/
recommended.json # Recommended models surfaced in onboarding (frozen shape)
schema.json # JSON Schema (Draft-07) for the recommended-models manifest
staff-picks.json # Curated Staff Picks list shown by default in Hub
schema.staff-picks.json # JSON Schema (Draft-07) for the staff-picks manifest
mobile.json # Mobile production catalog (exact download artifacts)
mobile-dev.json # Independent mobile dev catalog
schema.mobile.json # JSON Schema (Draft-07) shared by both mobile catalogs
README.mobile.md # Mobile contract, metadata reuse and admin migration
decision.json # Decision models (TurboQuant checkpoints and llama.cpp GGUFs)
schema.decision.json # JSON Schema (Draft-07) for the decision catalog
embedding.json # Embedding models served on /v1/embeddings (llama.cpp GGUFs)
schema.embedding.json # JSON Schema (Draft-07) for the embedding catalog
atomic-prism-models.json # Which Bonsai GGUF files need PrismML llama.cpp (atomic-prism)
schema.atomic-prism-models.json # JSON Schema (Draft-07) for the Prism model rules
foundry-local-models.json # Foundry Local model sources: resolver, Microsoft catalog, curated models
schema.foundry-local-models.json # JSON Schema (Draft-07) for the Foundry Local model list
litert-lm-models.json # LiteRT-LM models: Hugging Face listing rules, curated models
schema.litert-lm-models.json # JSON Schema (Draft-07) for the LiteRT-LM model list
geniex-models.json # GenieX models: Hugging Face GGUF rules, curated GGUFs and AI Hub bundles
schema.geniex-models.json # JSON Schema (Draft-07) for the GenieX model list
backends/
llamacpp-upstream-releases.json # Mirrored llama.cpp releases with min_core_version (cores >= 0.15.0)
llamacpp-upstream-releases-schema.json # JSON Schema (Draft-07) for the release list
manifest.json # Legacy llama.cpp catalog for cores < 0.15.0 (one release every core runs)
schema.json # JSON Schema (Draft-07) for the backends manifest
turboquant-manifest.json # TurboQuant backend catalog (one unified release tag)
turboquant-schema.json # JSON Schema (Draft-07) for the TurboQuant manifest
atomic-prism-manifest.json # PrismML llama.cpp releases (candidate / approved per asset)
atomic-prism-schema.json # JSON Schema (Draft-07) for the PrismML manifest
sdcpp-manifest.json # stable-diffusion.cpp build catalog (read by core)
sdcpp-manifest.staging.json # sd.cpp candidate slot: test builds, then sdcpp-approve.yml
sdcpp-schema.json # JSON Schema (Draft-07) for the sd.cpp manifest
audiocpp-manifest.json # audio.cpp build catalog (read by core; appears with the first approval)
audiocpp-manifest.staging.json # audio.cpp candidate slot: test builds, then audiocpp-approve.yml
audiocpp-schema.json # JSON Schema (Draft-07) for the audio.cpp manifest
mlx-manifest.json # The pinned mlx-server build (read by core and the desktop Makefile)
mlx-manifest.staging.json # The MLX candidate slot (mirror-mlx.yml, mlx-approve.yml)
mlx-schema.json # JSON Schema (Draft-07) for the MLX manifest
foundry-local-manifest.json # microsoft/foundry-local releases (read by core)
foundry-local-schema.json # JSON Schema (Draft-07) for the Foundry Local manifest
litert-lm-manifest.json # LiteRT-LM library wheels on PyPI per platform, plus OpenVINO (read by core)
litert-lm-schema.json # JSON Schema (Draft-07) for the LiteRT-LM manifest
geniex-manifest.json # GenieX SDK zips on Qualcomm's S3 mirror, Windows on Snapdragon X (read by core)
geniex-schema.json # JSON Schema (Draft-07) for the GenieX manifest
runtimes/
tensorrt-llm.json # TensorRT-LLM managed-engine runtime descriptor
vllm.json # vLLM managed-engine runtime descriptor (branch only until live acceptance)
schema.json # JSON Schema (Draft-07) for a runtime descriptor, shared by every engine
environments/
linux.json # Linux environment manifest (where core may install Docker + the NVIDIA toolkit)
linux.schema.json # JSON Schema (Draft-07) for the Linux environment manifest
windows.json # Windows environment manifest (the rootfs core imports as its own WSL2 distribution)
windows.schema.json # JSON Schema (Draft-07) for the Windows environment manifest
windows-arm64.json # Windows on Arm environment manifest (an aarch64 rootfs; read only by an arm64 core)
windows-arm64.schema.json # JSON Schema (Draft-07) for the Windows on Arm environment manifest
app/
latest.json # Installers the atomic.chat landing page links to
schema.json # JSON Schema (Draft-07) for the landing release manifest
.github/
workflows/validate.yml # Validates every manifest on every PR
workflows/mirror-upstream.yml # Mirrors + signs an upstream llama.cpp release
workflows/upstream-approve.yml # Approves a mirrored llama.cpp tag (engine update pipeline)
workflows/mirror-prism.yml # Mirrors + signs a PrismML release, lists it as candidate (engine update pipeline)
workflows/prism-approve.yml # Approves a listed PrismML release (engine update pipeline)
workflows/mirror-sdcpp.yml # Mirrors + signs an sd.cpp build from the Atomic fork into a manifest
workflows/sdcpp-approve.yml # Moves a checked sd.cpp build from staging to the live manifest
workflows/mirror-audiocpp.yml # Mirrors + signs an audio.cpp build from the Atomic fork into the staging manifest
workflows/audiocpp-approve.yml # Moves a checked audio.cpp build from staging to the live manifest
actions/windows-code-sign/ # Authenticode signing with the Azure Key Vault HSM key (AzureSignTool, OIDC)
scripts/mirror.mjs # Asset whitelist + manifest generation
scripts/upstream-releases.mjs # Release list upkeep: add, approve, promote, withdraw, prune, check
scripts/prism-manifest.mjs # PrismML release list: latest, add, gate, approve, withdraw, check
scripts/upstream-verify.mjs # engine-candidate check of a mirrored tag, and the approval gate
scripts/sdcpp-approve.mjs # sd.cpp approval: check the staged manifest, write the live one
scripts/audiocpp-approve.mjs # audio.cpp approval: check the staged manifest, write the live one
scripts/audiocpp-manifest-check.mjs # audio.cpp manifest integrity (required backends, companion, hashes)
entitlements.plist # Entitlements for the signed macOS binaries
Makefile # make mirror TAG=... and friends
README.md
Future configuration domains (themes, default prompts, etc.) will live in
sibling directories such as themes/, prompts/, and so on. Each domain
gets its own subdirectory and its own schema.
The registry only describes cloud providers that need API keys (OpenAI, Anthropic, OpenRouter, Mistral, Groq, xAI, Gemini, MiniMax, Hugging Face, NVIDIA, …).
The following are not in the registry and must not be added:
| Excluded | Why |
|---|---|
| Local providers (llama.cpp, etc) | Discovered at runtime by the client's engine manager. |
azure |
Kept inside the client as a baseline fallback — it requires per-resource configuration. |
| API keys | Must always remain on the user's machine. The api_key field MUST be "" in the registry. |
raw.githubusercontent.com/AtomicBot-ai/atomic-chat-conf/main/providers/registry.json
│
▼ fetched once per hour (TTL = 1h)
┌─────────────────────────────────┐
│ Atomic Chat client (web-app) │
│ - validates schema_version │
│ - merges with `azure` │
│ - caches in localStorage │
└─────────────────────────────────┘
If the network is unreachable or the manifest is malformed, the client falls
back to its built-in baseline (azure only) plus whatever was previously
cached. The application never crashes due to a registry issue.
- Open
providers/registry.jsonon GitHub. - Click the pencil icon ("Edit").
- Find the provider block (for example,
"provider": "openrouter"). - Add a new entry to its
modelsarray, copying the shape of an existing entry. Example:{ "id": "openai/gpt-5.5", "name": "GPT-5.5", "version": "1.0", "description": "Short, factual one-liner. 1M ctx, vision + tools.", "capabilities": ["completion", "tools", "vision"] } - Bump
updated_atat the top of the file to today (YYYY-MM-DDTHH:MM:SSZ). - Commit the change to a new branch and open a Pull Request.
- Wait for CI ("Validate registry") to pass — it checks the file against
schema.json. - Request a review and merge.
The same as above, but you add a whole provider object to the top-level
providers array. Use any existing provider as a template. Required fields:
provider— short, lowercase, unique id (e.g.cohere).base_url— OpenAI-compatible base URL.settings— at minimum, anapi-keyandbase-urlcontroller pair.models— may be[]if you want users to discover models manually.api_key— always"".
If your provider needs extra HTTP headers (Anthropic does, for example), use
the optional custom_header array.
The client's Refresh (↻) button on a provider page is hybrid: it merges
this curated registry list with whatever the provider returns from a live
GET /v1/models, deduped by id. This is what lets custom / self-hosted
providers (vLLM, llama.cpp, LM Studio, …) surface their real model ids.
For a few clouds the live /v1/models endpoint returns hundreds of
junk/internal ids that would pollute the picker. To opt such a provider out of
the live probe, set the optional boolean:
"supports_model_listing": falsetrue(or the field omitted) → registry list ∪ live/v1/models(default).false→ curated registry list only; the client never calls/v1/models.
This is backwards-compatible — older clients simply ignore the field — so it
does not require a schema_version bump.
When the user connects a provider, the client checks the key before calling
the provider connected. By default it asks GET {base_url}/models with the
key: a list means the key works, a 401 means it is invalid. A few providers
answer their model list without any key, so a wrong key would pass. For those,
key_check names a request that needs a valid key:
"key_check": { "path": "/key" }"key_check": { "url": "https://huggingface.co/api/whoami-v2" }pathis joined ontobase_url;urlis an absolute HTTPS URL. Exactly one of the two.methodis optional and onlyGETis allowed.- Any 2xx answer means the key works; a 401 that is not about missing permissions means it is invalid; anything else leaves the key saved but "not verified".
- Set it only to an endpoint the provider documents as requiring a valid key and costing nothing to call, and put the doc link in the PR.
- A
urlhost must bebase_url's host or share its parent domain (CI checks this). The client uses aurlcheck only while the user's base URL is still on such a host, so a key typed for another server is never sent to the provider.
Providers with a key_check today:
openrouter—{ "path": "/key" }, i.e.GET https://openrouter.ai/api/v1/key, documented under Limits and Get current API key (401 for a missing or invalid key).huggingface—{ "url": "https://huggingface.co/api/whoami-v2" }, the Hub's Auth endpoint;huggingface_hubreads its 401 as "Invalid user token" and notes it is strictly rate-limited.
aimlapi and edenai document their model lists as needing no key, and
nvidia documents no key-information endpoint; none of the three documents a
free endpoint that rejects an invalid key, so they have no key_check. A wrong
key there is found by the first chat it fails.
Older clients ignore the field, so it needs no schema_version bump.
The capabilities array on each model uses these values:
| Value | Meaning |
|---|---|
completion |
Standard chat / completion endpoint. |
tools |
Native function-calling / tool-use support. |
vision |
Accepts image inputs. |
embeddings |
Embedding endpoint available for this model. |
reasoning |
Exposes structured reasoning_details (e.g. DeepSeek R1). |
Every manifest carries a top-level schema_version. The Atomic Chat client embeds
its highest supported version. If you ship a manifest whose schema_version
exceeds what older clients understand, they will fall back to their cached or
baseline manifest and prompt the user to update Atomic Chat.
Bump schema_version only when adding new required fields or changing the
shape of existing fields in a backwards-incompatible way. Adding a new
provider or new model never requires a bump.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/recommended.json drives the Recommended
section in two places of the Atomic Chat client:
- The Hub screen (
/hub). - The first-run Setup / onboarding screen.
Each entry is a small object — only the model id and the i18n key for the
chip label live here. The full Hugging Face metadata (quants, mmproj, file
sizes) is fetched at runtime from huggingface.co. A bundled, slim
fallback in the client covers the offline first launch.
Entry shape (full schema in models/schema.json):
{
"model_name": "unsloth/gemma-4-E4B-it-GGUF",
"description_key": "hub:recEverydayUse",
"platforms": ["macos", "windows", "linux"],
"active": true
}| Field | Required | Notes |
|---|---|---|
model_name |
yes | Hugging Face repo id (owner/name). |
description_key |
yes | i18n key for the chip label. Must start with hub: and exist in the client's hub.jsons. |
platforms |
no | Subset of ["macos", "windows", "linux"]. Omit to show on every platform. |
active |
no | Defaults to true. Set to false to hide an entry without deleting it. |
These keys are translated in
web-app/src/locales/*/hub.json
and mapped to chip colors in web-app/src/constants/recommendedModelChip.ts:
| Key | Chip color | English label |
|---|---|---|
hub:recEverydayUse |
green | Everyday use |
hub:recVisionKnowledge |
purple | Vision & knowledge |
hub:recFinetuningChat |
blue | Fine-tuning & chat |
hub:recMathReasoning |
yellow | Math & reasoning |
hub:recForMlx |
orange | For MLX |
Adding a brand-new description_key requires both adding the translation in
the Atomic-Chat repo and publishing a client release — until then, older
clients render the entry with a neutral gray chip.
platforms is purely a presentation hint:
- MLX models (anything from the
mlx-communityorg or marked aslibrary_name: "mlx") only run on macOS — list them with"platforms": ["macos"]. - GGUF models generally run everywhere; setting
platformslets you promote a different default for Windows/Linux users (e.g. recommend Llama 3.1 GGUF on Windows when MLX is not an option).
The Atomic Chat client filters this list locally based on the host OS before rendering.
The client and manifest distinguish *_64, legacy *_64_plus (between 64
and nominal 128 GiB), *_128, and *_128_plus. The ids apply separately to
vram_ (largest single GPU) and unified_ (Mac/ARM shared memory). Nominal
128 allows reporting tolerance: 127–129 GiB VRAM and 127.5–128.5 GiB unified,
with exclusive upper edges. The existing 64 edges stay at 65 and 64.5 GiB.
Ship the client with the new vocabulary before publishing this manifest;
schema version stays 1 because old clients ignore unknown tier keys and keep
using *_64_plus and the original recommendation lists.
Each high tier has an ordered lead, a Gemma 4 31B vision alternative with its F16 projector pinned, and another text/coding option. The larger options trade memory and download size for model capacity; this is not a throughput ranking. The AtomicChat Qwen3.6 mirrors have no projector and are offered for text.
File evidence records exact HF file
sizes, revision ids, and LFS hashes checked on 2026-09-17, including every shard.
node --test .github/scripts/recommendation-tiers.test.mjs checks the pins,
complete shard sets, local catalog membership, and weight-plus-projector fit
at each tier's lower edge. macOS's load ceiling is 85% of unified memory;
weights within 50% are comfortable by the client rule. Other platforms use the
whole pool before warning about spill. Neither rule guarantees runtime fit at
arbitrary context lengths. Refresh the evidence when rotating these choices.
- Edit the model/variant in
models/catalog.jsonand reference its ID in therecommendedcollection. - Bump the canonical catalog's
updated_atand regenerate compatibility exports withnode .github/scripts/export-model-catalog.mjs. - Run
make validate, review the canonical diff and generated exports, then open a Pull Request. - Request a review and merge after CI passes. Do not independently edit the deprecated
models/recommended.jsonexport.
All running Atomic Chat clients pick up the change within an hour.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/staff-picks.json drives the Staff picks
list that the Hub screen (/hub) shows by default, before the user types a
search query. It is deliberately a separate file from
models/recommended.json: shipped production clients reject a manifest whose
schema_version is higher than the one they were built against, so the
recommended-models manifest is frozen at version 1 with its original entry
shape. Staff picks get their own file, their own schema, and their own
version dial.
Entry shape (full schema in
models/schema.staff-picks.json):
{
"model_name": "AtomicChat/Qwen3.6-27B-GGUF",
"title": "Qwen3.6 27B",
"summary": "Prioritizes stability and real-world coding quality.",
"description_key": "hub:recCoding",
"icon": "qwen",
"format": "gguf",
"categories": ["reasoning", "coding", "tools"],
"order": 80,
"active": true
}| Field | Required | Notes |
|---|---|---|
model_name |
yes | Hugging Face repo id (owner/name). |
title |
no | Display name override. Falls back to the name derived from the repo id. |
summary |
no | One-line English description shown on the row. |
description_key |
no | i18n key for the chip label. Must start with hub:. Takes priority over summary for the chip. |
icon |
no | Bundled icon key. Unknown keys fall back to the model-family logo, then to a letter. |
format |
no | gguf (default) or mlx. Decides which picks the Hub resolves at all — see below. |
categories |
no | Capability pills: general, reasoning, coding, vision, tools, compact, multilingual. |
platforms |
no | Subset of ["macos", "windows", "linux"]. Omit to show on every platform. |
order |
no | Lower sorts first; entries without an order sort last. Must be unique. |
active |
no | Defaults to true. Set to false to hide a pick without deleting it. |
A model that ships both a GGUF and an MLX build gets two entries. The Hub shows the GGUF one by default and swaps to the MLX one only while the MLX format filter is selected, so the list never carries the same model twice.
format has to be declared rather than inferred from the repo id, because the
client uses it to decide which picks to resolve: an entry that is off screen
costs neither a catalog lookup nor a Hugging Face request. Give the MLX entry
"platforms": ["macos"] (CI rejects an MLX pick without it), the same order
as its GGUF twin plus 5, and "description_key": "hub:recForMlx".
Editing flow is identical to the recommended-models manifest: edit on GitHub,
bump updated_at, open a PR, wait for the "Validate registry" workflow.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/decision.json lists the decision models of the Hub's Decision
category: models that answer typed questions (choice, score, noul) about
a state in one forward pass, served on /v1/systemone. The app downloads every
listed file into <data>/decision/models/<id>/, checking bytes and sha256, and
the core starts the decision server on the model's engine. One decision model
runs at a time.
A model runs on one of two engines, set by engine:
engine |
format |
What the files are | min_engine |
|---|---|---|---|
llamacpp (default) |
checkpoint |
A laya checkpoint folder TurboQuant converts to GGUF once | TurboQuant tag b10269-1.7.0 |
llamacpp-upstream |
gguf |
One GGUF (role: "model"), plus an mmproj for vision |
Upstream tag, e.g. b11370 |
The upstream builds that serve a type are: b11370 for laya, openjev, lev, kev
and nimble; b11371 for clef; b11418 for clef with images. Until the
upstream manifest reaches a model's min_engine, the app lists the model with a
"needs llama.cpp b+" notice instead of a Start button.
| Field | Required | Notes |
|---|---|---|
id |
yes | Folder name under decision/models and the model id the engine answers with. |
repo, revision |
yes | Hugging Face repo and the full commit every file is pinned to. |
files |
yes | path, bytes, sha256 from the Hugging Face API; GGUF files also carry role. |
engine |
upstream only | llamacpp or llamacpp-upstream. Also the settings page that manages the model. |
format |
upstream only | checkpoint or gguf. An upstream model is always gguf. |
decision_type |
upstream only | The GGUF <arch>.decision.type: laya, openjev, lev, kev, nimble, clef. |
icon |
no | Bundled logo key (web-app/src/lib/model-logo.ts, ICON_KEY_LOGOS). Omitted: Convai. |
vision |
no | true for a model that reads images. It must list an mmproj file. |
default |
no | The model suggested first on its engine's page. At most one per engine. |
context |
yes | Prompt context the engine is started with (-c). |
Clients that predate the engine field keep only checkpoint models: they drop
every model without the checkpoint files. So the catalog keeps
schema_version: 1 and must always hold a default checkpoint model; the
integrity check enforces both. A new logo key needs the image in the app first,
then the icon value here.
The local speech, music and sound-effect models for audio.cpp are the kind: "audio" entries of
models/catalog.json, listed by its audio collection. Edit them there only:
models/audio.json is their generated export (see model catalog ownership). A
client projects the audio collection, with the core's projectAtomicModelCollection or from the
export, and sends each model's family, task and options in the load request; the core has no
catalog of its own. Files are pinned by revision, bytes and sha256, and client downloads go to
<data>/audio/models/<filename>.
An entry is keyed audio:<id>, has format: "gguf", engines: ["audio-cpp"], and the variants
default (all-required-files) plus one per quant whose selection is the quant's id.
icon is the developer's logo key (qwen, openmoss, acestep, stability; a client
without the key shows a generic mark) and description is one line for a model picker, at most 80
characters. .github/scripts/audio-catalog-check.mjs checks these and what follows; models/schema.audio.json
checks the export. To add a model or move one to a newer commit of its repository:
node .github/scripts/refresh-model-catalog.mjs audio:<id> audio-cpp/audio.cpp-gguf <full commit>
node .github/scripts/export-model-catalog.mjs
make validateThe refresh reads bytes and sha256 of every quant from that commit; a new entry needs its quants'
path and filename first.
controls, defaults and ranges say which form fields a client shows before the model is loaded.
attribution is text a client must show with the model: Stable Audio's license asks for
"Powered by Stability AI", keeps its use free only under USD 1M of yearly revenue, and asks commercial
users to register with Stability AI.
Our audio.cpp builds leave out eSpeak-ng, which is GPL, so the check refuses models that phonemize with it, such as Kokoro and Piper.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/embedding.json lists the embedding models of the Hub's Embedding
category: models that turn an input into a vector, served on the Local API
Server's OpenAI-compatible /v1/embeddings. The app downloads every listed
file into <data>/embedding/models/<id>/, checking bytes and sha256, and the
core starts one llama-server --embedding for the model the user turned on.
One embedding model runs at a time, beside the chat model; API clients pick it
by passing its id as model.
Every model runs on stock llama.cpp (engine: "llamacpp-upstream",
format: "gguf"): one GGUF (role: "model"), plus an mmproj projector for a
model that reads more than text. Until the user's llama.cpp reaches a model's
min_engine, the app lists the model with an "update llama.cpp" notice
instead of a Start button. EmbeddingGemma 2 (gemma-embedding2) needs b11454.
| Field | Required | Notes |
|---|---|---|
id |
yes | Folder name under embedding/models and the model id the engine answers with (model in API calls). |
repo, revision |
yes | Hugging Face repo and the full commit every file is pinned to. |
files |
yes | path, role, bytes, sha256 from the Hugging Face API. One model, at most one mmproj. |
context |
yes | Tokens per input the engine is started with: -c, and -b/-ub (an encoder reads one whole input per batch, media tokens included). |
max_context |
yes | The longest input the model was trained for. |
dims |
yes | Vector length /v1/embeddings returns. |
matryoshka_dims |
no | Shorter lengths a vector can be cut to (re-normalize after cutting). The server never cuts. |
pooling |
yes | mean, cls or last: passed as --pooling. |
modalities |
yes | text, plus image / audio for a model with an mmproj. |
image_max_tokens |
no | --image-max-tokens: the token budget one image is resized to, at most half of context. |
prompts |
no | query / document text the model expects before each text input. Shown in the app for clients to copy; the server never adds it. |
icon |
yes | Bundled logo key (web-app/src/lib/model-logo.ts, ICON_KEY_LOGOS). |
min_engine |
yes | The oldest upstream tag that runs the model, b<build>. |
default |
no | The model the app suggests first. Exactly one. |
An input beyond text goes in a content array of one input item and gives
one vector; text and media can be mixed in one item:
{
"model": "embeddinggemma-2",
"input": [
"task: search result | query: a red square",
{ "content": [{ "type": "image_url", "image_url": { "url": "data:image/png;base64,<base64 png or jpeg>" } }] },
{ "content": [{ "type": "input_audio", "input_audio": { "data": "<base64 wav, mp3 or flac>" } }] }
]
}Media must be inline (data: URLs or base64): the core refuses links, so the
engine never fetches a URL a client hands it, and answers malformed or
undecodable media with a 400 that names the field. dimensions other than
dims is refused too: the server returns full vectors, and a client that wants
one of the matryoshka_dims keeps the first values and L2-normalizes them. A new logo key needs the image in
the app first, then the icon value here.
providers/media.json lists the image and video generation models that cloud
providers and self-hosted servers offer through the core. Only the core reads
it (released apps never fetch it). The core answers the app's media pickers
from it and routes /v1/images/generations, /v1/images/edits and
/v1/videos for these models to the provider.
Per provider id (a provider of providers/registry.json, or automatic1111 and
sdcpp-server, which the app ships itself) there is an image and/or a video
section:
| Field | Notes |
|---|---|
api |
The core adapter (dialect) that speaks this provider's media API, e.g. openai-images, gemini-veo. |
models[].id |
The id the provider takes as model, and the id clients pass to the core. |
models[].default |
Offered as soon as the provider is connected. At most one per provider and kind. |
models[].api |
Overrides the section's adapter for one model (MiniMax H3 uses the V2 video API). |
models[].workflows |
Image: create, transform, inpaint, reference, edit. Video: create, image-to-video. |
models[].params |
What the generation form offers: sizes, aspect ratios, resolutions, durations, quality, seed and so on. A missing key is a hidden control. |
models[].options |
Adapter settings for one model (the Hugging Face inference provider, the NVIDIA request schema). |
dialects holds each adapter's default workflows and parameters. The core uses
them for a model a provider lists live that this file does not name.
No hosts here. An adapter derives every URL from the provider's registered
base_url in code, so this file can never send an API key to a new host.
Compatibility. Changes are additive. A core that does not know a dialect
or a parameter skips that entry and keeps the rest. Raise catalog_version on
every change; the core keeps the newer of its bundled baseline and this file.
Bump schema_version only for a breaking change, and only after the core
parser accepts the new version. A model that stops working at a provider is
removed here; no release is needed.
Cores from 0.15.0 read the upstream release list instead and use this file only as a fallback. It stays for the cores already released, so it only ever names a release every core runs.
backends/manifest.json is the catalog of
downloadable llama.cpp backend builds the Atomic Chat client offers on
Windows, Linux (x64 and arm64) and Apple Silicon. It exists to dodge GitHub's unauthenticated API
rate limit (60 req/hr/IP): the client used to resolve the backend list
straight from api.github.com/repos/ggml-org/llama.cpp/releases/latest,
which dead-ended on shared / NAT / VPN networks (see ATO-199). It now reads
this static file via raw.githubusercontent.com, which has no per-IP limit.
The file mirrors the shape of a GitHub release JSON (tag_name +
assets[].name) so the client reuses its existing asset-name parser
verbatim — only the source URL changed.
The archives themselves are served from this repository's own releases,
where the Windows and macOS binaries carry Atomic Chat's signatures — see
Signed mirror below. download_base names that stream;
drop the field and the client falls back to the upstream ggml-org CDN, which
is what a tag we have not mirrored has to do.
{
"$schema": "./schema.json",
"updated_at": "2026-06-17T00:00:00Z",
"tag_name": "b9691",
"download_base": "https://github.com/AtomicBot-ai/atomic-chat-conf/releases/download",
"assets": [
{
"name": "llama-b9691-bin-win-cpu-x64.zip",
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
"size": 18468077
},
{ "name": "cudart-llama-bin-win-cuda-12.4-x64.zip" }
]
}$schema/updated_atare advisory; the client readstag_name,download_baseandassets[], so the GitHub-mirror shape is preserved.sha256andsizeare verified by the client after download and always travel together. An asset without them is one we do not host: thecudart-*companions stay on the upstream CDN (their DLLs are NVIDIA's own, already signed by NVIDIA, and mirroring them would triple the size of every release for no gain).- Windows (x64 and arm64), Linux (x64 and arm64) and
macos-arm64assets are listed. Windows arm64 is CPU, OpenCL (Adreno), Vulkan and CUDA 13; Linux arm64 is CPU, Vulkan and CUDA 13; Linux x64 is CPU, Vulkan, ROCm and CUDA (every toolkit upstream ships, 12.x and 13.x). ROCm is matched by version pattern on both platforms. The Snapdragon, SYCL and OpenVINO builds are not mirrored. The Linux CUDA companion carries the tag in its name (cudart-llama-<tag>-bin-ubuntu-cuda-<toolkit>-<arch>.tar.gz). macOS used to be bundled-only and was deliberately omitted; it now resolves from this manifest like the other platforms, so an engine update reaches macOS users without an Atomic Chat release. The client still ships a bundled macOS build as the offline baseline and picks whichever is newer. macos-x64is deliberately absent. Runtime engine updates on macOS are Apple Silicon only. The client filters macOS assets by host architecture, so an Intel host resolves nothing from this manifest and stays on its bundled build. Adding the asset would start serving updates to Intel Macs, which is a product decision, not a manifest edit.- The
cudart-*companions are listed for completeness; the client's backend regex ignores them (it matches onlyllama-<tag>-bin-...), so they are harmless.
backends/llamacpp-upstream-releases.json
lists the mirrored releases newest first, the same way the PrismML manifest
does. Each release names the oldest core it runs on (min_core_version) and
each archive its validation:
candidate: mirrored, not verified. No core offers it unless the user opted into unverified builds.approved: verified for the cores the release names and offered to them.
A core takes, per backend, the newest release that is not withdrawn, whose
min_core_version it meets and whose archive for that backend is approved.
That is how an engine update that needs a core change reaches only the cores
that have the change: list it with min_core_version set to the core that
shipped the change. 0.0.0 means every core that reads the list.
{
"$schema": "./llamacpp-upstream-releases-schema.json",
"schema_version": 1,
"updated_at": "2026-10-13T00:00:00Z",
"upstream_repo": "ggml-org/llama.cpp",
"download_base": "https://github.com/AtomicBot-ai/atomic-chat-conf/releases/download",
"releases": [
{
"tag": "b11500",
"commit": "0000000000000000000000000000000000000000",
"published_at": "2026-10-10T00:00:00Z",
"min_core_version": "0.16.0",
"notes_url": "https://github.com/ggml-org/llama.cpp/releases/tag/b11500",
"assets": [
{
"name": "llama-b11500-bin-macos-arm64.tar.gz",
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
"size": 12087702,
"validation": "approved"
}
]
}
]
}- The backend is read from the archive name, as in
backends/manifest.json. Thecudart-*companions are not listed: they stay on the ggml-org CDN. withdrawn: { "reason": "..." }pulls a release from offers. Installed packs are kept.backends/manifest.jsonmust name an approved release of the list withmin_core_version0.0.0, with the same hashes. CI enforces it (upstream-releases.mjs check), so the file older cores follow can only move to a release every core runs.- A newer release that is approved for every backend an older one is, for the
same or older cores, replaces it; the mirror drops replaced releases from
the list (the one
backends/manifest.jsonnames stays).
Upstream ships its macOS binaries ad-hoc-signed and its Windows binaries unsigned. Atomic Chat both downloads these archives at runtime and bundles one in its installer, so before this pipeline existed the app either shipped an unsigned binary or re-signed it on each developer's machine. Now one CI run per tag produces a single artifact that serves both paths.
make mirror TAG=b10405 # run the pipeline, list the tag as a candidate, wait for it
make mirror TAG=b10405 PUBLISH=1 # same, then promote it for every core (moves backends/manifest.json)
make mirror-select TAG=b10405 # dry run: show which assets that tag would mirror
make verify-release TAG=b10405 # check the published macOS asset's signature.github/workflows/mirror-upstream.yml
downloads the whitelisted assets from ggml-org, signs the Windows binaries
with our DigiCert code signing key in Azure Key Vault and the macOS binaries with our Developer ID
(hardened runtime, secure timestamp), repacks each archive with its original
layout, publishes them under the upstream tag, then lists the tag in the
release list as a candidate, with a sha256 per archive, and commits it to
main. Linux archives pass through byte-for-byte: there is no Linux signing
mechanism here. With PUBLISH=1 it also promotes the tag and regenerates
backends/manifest.json; MIN_CORE=0.16.0 lists it for cores from that
version.
The lists move after the upload succeeds, never before — clients
resolve download URLs from them, so the reverse order would hand them 404s.
A tag with approved archives is never re-mirrored: a re-run re-signs every
archive, and clients already hold the old hashes. Older mirrored releases are
pruned (RETAIN=3 by default), except the ones the release list still offers
and the one backends/manifest.json names.
Windows signing needs no secret: the sign-windows jobs run in the
codesign environment, sign in to Azure through GitHub OIDC (the Entra app's
federated credential is bound to that environment) and read AZURE_CLIENT_ID,
AZURE_TENANT_ID, AZURE_KEY_VAULT and AZURE_CODESIGN_CERT from its
variables. The key is a non-exportable RSA-HSM key in Key Vault Premium; the
app holds Key Vault Crypto User and Key Vault Certificate User on that vault
only. Required secrets: APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD
(macOS). The temporary keychain the macOS job
creates gets a password generated on the runner, so that one is not a secret.
-
Run
make mirror TAG=<tag>. Pick the newest completeb<build>release: releases publish their tag before every asset finishes uploading, and ggml-org'slatestis not a build at all. The pipeline fails loudly if a required asset is missing from the tag, which is the check that used to be manual. The tag lands as a candidate. -
Run
make upstream-verify TAG=<tag>. It starts core'sengine-candidateworkflow on the signed archives mirrored here (candidate_id=conf-<tag>): core's suites and its live llama.cpp tests on five OSes, the current pin beside the candidate. It waits for the run and prints the verdict:pass,failorincomplete, with what failed. -
On a branch, approve what passed and open a pull request:
- every core runs it:
make upstream-promote TAG=<tag>(also movesbackends/manifest.json); - it needs a core change:
make upstream-approve TAG=<tag> MIN_CORE=<core>, once that core is released; - some backends failed: add
ONLY=<archive>,<archive>to approve the rest.
Both refuse a tag that no successful
engine-candidaterun names;FORCE=1goes ahead anyway. Merge the approval before the nextmake mirror: a newer tag replaces a release with nothing approved, so the mirror drops it from the list (and, pastRETAIN, deletes its mirrored release), and it can no longer be approved. - every core runs it:
-
A release that turns out bad:
make upstream-withdraw TAG=<tag> REASON="...".
The engine update pipeline
(atomic-hatchet-pipeline,
Hatchet task engine-bump) runs these steps itself once a day, for the newest
llama.cpp build its checks call green:
mirror-upstream.ymlwithcandidate_id=<id>(it finds its run by[cid:<id>]in the title) andmin_core_versionset to the core the latest Atomic Chat release ships (atomicCore.versionin itspackage.json), so an approved build reaches users without an app release.- Core's
engine-candidateon the signed archives (repo=AtomicBot-ai/atomic-chat-conf,core_ref=<that core release>, or the first newer core release that can check the engine). Anything butpassstops here: the tag stays a candidate. upstream-approve.yml, the CI counterpart ofmake upstream-approve: the same gate, thenapprovefor cores frommin_core_versionand a commit to main. It never promotes, sobackends/manifest.jsonand cores before 0.15.0 stay on their release.
A re-run for a tag that is already approved changes nothing. Both workflows
share the mirror-upstream concurrency group, so they never rewrite the
release list at the same time. To stop automatic releases, turn them off in
the pipeline (PUBLISH_ENABLED=false); a bad one is withdrawn as above.
Cores from 0.15.0 re-read the list every hour; older cores read
backends/manifest.json when they start. Do not edit backends/manifest.json
by hand: CI refuses a tag the release list does not approve for every core.
backends/turboquant-manifest.json is
the catalog of downloadable TurboQuant llama.cpp builds
(AtomicBot-ai/atomic-llama-cpp-turboquant) the Atomic Chat client offers as
a second provider on Windows and Linux x64 (alongside the upstream
provider above). It exists for the same rate-limit reason as the upstream
manifest: the index lives here so the client never has to scan
api.github.com.
The fork publishes every variant of a build under one release tag, named
b<upstream-build>-<fork-semver> — e.g. b10018-1.3.0 is upstream llama.cpp
build b10018 carrying fork version 1.3.0. All entries therefore share the
same tag; the per-entry tag field is retained so an older scattered release
set stays expressible without a schema change.
{
"$schema": "./turboquant-schema.json",
"updated_at": "2026-07-31T09:00:00Z",
"commit": "5bc5c248d",
"backends": [
{ "id": "windows-x64-cpu", "tag": "b10018-1.3.0", "asset": "llama-turboquant-windows-x64-cpu.zip" },
{ "id": "windows-x64-cuda-12.4", "tag": "b10018-1.3.0", "asset": "llama-turboquant-windows-x64-cuda-12.4.zip" },
{ "id": "windows-x64-cuda-13.3", "tag": "b10018-1.3.0", "asset": "llama-turboquant-windows-x64-cuda-13.3.zip" },
{ "id": "windows-x64-vulkan", "tag": "b10018-1.3.0", "asset": "llama-turboquant-windows-x64-vulkan.zip" },
{ "id": "linux-x64-cpu", "tag": "b10018-1.3.0", "asset": "llama-turboquant-linux-x64-cpu.tar.gz" },
{ "id": "linux-x64-cuda-12.4", "tag": "b10018-1.3.0", "asset": "llama-turboquant-linux-x64-cuda-12.4.tar.gz" },
{ "id": "linux-x64-cuda-13.3", "tag": "b10018-1.3.0", "asset": "llama-turboquant-linux-x64-cuda-13.3.tar.gz" },
{ "id": "linux-x64-rocm", "tag": "b10018-1.3.0", "asset": "llama-turboquant-linux-x64-rocm.tar.gz" },
{ "id": "linux-x64-vulkan", "tag": "b10018-1.3.0", "asset": "llama-turboquant-linux-x64-vulkan.tar.gz" },
{ "id": "macos-arm64", "tag": "b10018-1.3.0", "asset": "llama-turboquant-macos-arm64.tar.gz" }
]
}idis the clean, release-aligned backend id the client uses verbatim.tagmust matchb<build>-<major>.<minor>.<patch>and must be identical across all entries; the archive download URL is built as…/releases/download/<tag>/<asset>against the releases CDN (not rate-limited).assetmust bellama-turboquant-<id>.zip(Windows) orllama-turboquant-<id>.tar.gz(Linux/macOS). The release also publishes.zipcopies of the Linux and macOS archives — do not list those.- Windows CUDA archives ship
ggml-cuda.dllbut no CUDA runtime DLLs, so the client still fetches thecudart-*companion from the pinned ggml-org release (or reuses one already installed under the upstream provider). Verified onb10018-1.3.0. - Linux GPU tiers (
cuda-12.4,cuda-13.3,rocm) are downloaded at runtime by the client;linux-x64-vulkanis what the installer bundles as the offline fallback.linux-x64-rocmtargets RDNA2–RDNA4 and needs a host ROCm runtime, so the client only offers it after a conservative hardware probe. macos-arm64is bundled into the installer, not downloaded at runtime, but it is listed here so the build system resolves it from the same pin.
Also static and hand-maintained. Pick the new release tag, set the same
tagon everybackends[]entry, keepassetasllama-turboquant-<id>.{zip,tar.gz}, bumpcommit+updated_at, open a PR, and merge once CI is green. Consumers pin an immutable commit of this repository, so a merge alone does not upgrade anyone — the Atomic Chat client must bump its pinned revision in a deliberate compatibility change.
backends/atomic-prism-manifest.json
lists the builds of PrismML's llama.cpp fork
(PrismML-Eng/llama.cpp) the
atomic-prism provider runs Bonsai models on (PQ2_0, PTQ1_0 tensor types
upstream llama.cpp does not load). Schema:
backends/atomic-prism-schema.json.
- Tags are
prism-b<build>-<sha7>;<build>is the upstream llama.cpp build the fork is cut from, soprism-b10787-…is older than upstreamb11734. - PrismML ships its macOS binaries ad-hoc-signed and its Windows binaries
unsigned, so they are mirrored and signed like upstream llama.cpp and
sd.cpp:
mirror-prism.ymlsigns the Windows binaries (Azure Key Vault key, after dropping every tool butllama-server) and the macOS ones (Developer ID, hardened runtime), publishes the desktop archives as a release here under the PrismML tag and lists them with their ownsha256. Linux archives and the cudart companions pass through byte-for-byte. download_baseis one for the whole manifest. It points here only once every listed tag is mirrored; builds listed before signing began are mirrored as they are (SIGN=0), keeping the hashes clients hold. An approved build is never re-signed.- Per release:
min_core_version, optionalwithdrawn; per asset:candidateorapproved. A core offers the newest release it meets whose asset for its machine is approved (or a candidate, with "Allow unverified PrismML builds" on). Windows CUDA packs need theircudartcompanion approved with them. models/atomic-prism-models.jsonsays which Bonsai files need PrismML and from which build (min_prism_build). It is edited by hand.
make prism-mirror TAG=prism-b10787-73bfe6c MIN_CORE=0.18.2— mirror and sign the release and list it ascandidate(runs CI).- Run core's
engine-candidateworkflow withengine=atomic-prism,tag=<tag>,repo=AtomicBot-ai/atomic-chat-conf(the signed archives) andcore_refset to the core release the build is for. It must pass. make prism-approve TAG=… MIN_CORE=0.18.2— refuses a tag no passing engine-candidate run names (FORCE=1skips that), then approves every asset, GPU packs and companions included: CI checks CPU builds only.- Open a PR and merge once CI is green. A bad release is pulled with
make prism-withdraw TAG=… REASON="…".
When a new Bonsai packing needs a newer build, raise min_prism_build in the
model rules by hand. Core keeps an offline copy of this manifest
(src/backend/catalog/prism-manifest-baseline.json); re-copy it there when it
matters for offline first runs.
The engine update pipeline
(atomic-hatchet-pipeline,
engine atomic-prism) runs the same steps for a build its checks call green,
once it is enabled there (PUBLISH_ENGINES):
mirror-prism.ymlwithcandidate_id=<id>andmin_core_versionset to the core the latest Atomic Chat release ships: sign, release here, list as candidate.- Core's
engine-candidateon the signed archives (repo=AtomicBot-ai/atomic-chat-conf,core_ref=<that core release>, or the first newer one that has the PrismML check: v0.18.6 and later). Anything butpassstops here: the tag stays a candidate. prism-approve.yml: the same gate, thenapprovefor cores frommin_core_versionand a commit to main.
Both workflows push to main and share the prism-manifest concurrency group.
The mirror publishes the release before it touches the manifest, so a listed
archive is always downloadable.
A re-run for a tag that is already listed or approved changes nothing.
Core installs sd-server from
backends/sdcpp-manifest.json (schema:
backends/sdcpp-schema.json): one tag_name,
one archive per backend id with its sha256 and size, downloaded from this
repository's releases (download_base). Cores re-read it within the hour.
- Every archive is built by the Atomic fork,
AtomicBot-ai/stable-diffusion.cpp
(workflow
Release (Atomic): a releasemaster-<n>-<sha7>per leejet tag), and signed here bymirror-sdcpp.yml: Authenticode on Windows, Developer ID on macOS; Linux archives and the cudart companion pass through byte-for-byte. Withatomic_rev(the fork commit the archives were built at, 7 hex) the release here and the manifest are taggedmaster-<n>-<sha7>-a<rev>. - Core moves an installed engine only to a higher build number
<n>, or from a bare tag to the-a<rev>rebuild of it; two rebuilds of one tag are equal, and it never moves back. backends/sdcpp-manifest.staging.jsonis the candidate slot: the mirror writes it, test builds of the app read it (ATOMIC_SDCPP_MANIFEST_URL), core'sengine-candidatechecks the build it names, andsdcpp-approve.ymlcopies it into the live manifest. It names the newest candidate, passed or not.
-
In the fork, run
Release (Atomic)withupstream_tag=master-<n>-<sha7>andpublish=true. Note the fork commit it built: that isatomic_rev. -
Mirror into the staging slot:
gh workflow run mirror-sdcpp.yml --repo AtomicBot-ai/atomic-chat-conf \ -f tag=master-<n>-<sha7> -f atomic_rev=<rev> \ -f manifest_path=backends/sdcpp-manifest.staging.json
It publishes the signed release
master-<n>-<sha7>-a<rev>here, then commits the staging manifest to main. -
Run core's
engine-candidatewithengine=sd-cpp,repo=AtomicBot-ai/atomic-chat-conf,tag=master-<n>-<sha7>-a<rev>andconf_refat or after the mirror's commit. It must pass. Itsresults.json(artifactengine-candidate-results) records the conf commit it read asconf.sha. -
Approve:
gh workflow run sdcpp-approve.yml --repo AtomicBot-ai/atomic-chat-conf \ -f tag=master-<n>-<sha7>-a<rev> -f conf_sha=<conf.sha>
sdcpp-approve.yml does nothing when the live manifest already names the tag.
Otherwise it refuses unless:
backends/sdcpp-manifest.staging.jsonatconf_sha, a commit of main, names the tag, downloads from this repository, and lists every archive with thesizeandsha256of this repository's release of the tag (the release'sdigest);- a successful
engine-candidaterun in core has the tag as a word of its title (the fork'smaster-<n>-<sha7>run does not count), and itsresults.jsonsaysstatus: pass,engine: sd-cpp,candidate.repoAtomicBot-ai/atomic-chat-confandcandidate.tagthe tag (upstream-verify.mjs gate --engine sd-cpp).
Then it writes that staging manifest, with a new updated_at, to
backends/sdcpp-manifest.json, validates it like CI does and pushes
chore(sdcpp-manifest): approve <tag> to main. The live manifest gets the
staging manifest of conf_sha, not of main, so a newer candidate in the slot
does not matter.
The mirror refuses the tag the live manifest names: a re-run re-signs every
archive in place, and clients already hold the old hashes. Mirroring with
manifest_path=backends/sdcpp-manifest.json still writes the live manifest
directly, without the check; it is for emergencies only.
The engine update pipeline
(atomic-hatchet-pipeline,
Hatchet task engine-bump, engine sd-cpp) runs the same steps for a fork
build its checks call green, once it is enabled there (PUBLISH_ENGINES):
mirror-sdcpp.ymlwithtag,atomic_rev,manifest_path=backends/sdcpp-manifest.staging.json,publish_manifest=trueandcandidate_id=<id>(it finds its run by[cid:<id>]in the title).- Core's
engine-candidateon the signed release (repo=AtomicBot-ai/atomic-chat-conf,tag=master-<n>-<sha7>-a<rev>, the staging manifest atconf_ref). Anything butpassstops here: the build stays in the staging slot and never goes live. sdcpp-approve.ymlwithtag,conf_sha(the run'sresults.jsonconf.sha) andcandidate_id.
Every core gets the build: sd.cpp has no min_core_version. Both workflows
share the mirror-sdcpp concurrency group, so the release and the manifests
are never rewritten at the same time. To stop automatic releases, turn them off
in the pipeline.
Revert the approval commit (chore(sdcpp-manifest): approve <tag>) on main.
The live manifest names the previous tag again, and cores that have not
installed the bad build yet stop being offered it. Cores that have installed
it stay on it, because core never moves an engine back; they leave it only for
a newer build number, so the fix is the next build through the steps above.
The revert works only while the previous tag's release still exists here: the
mirror prunes all but the newest retain sd.cpp releases (3 by default),
keeping only the tags the manifests name.
Core installs audiocpp_server (engine audio-cpp) from
backends/audiocpp-manifest.json (schema:
backends/audiocpp-schema.json), read from
this repository's main (ATOMIC_AUDIOCPP_MANIFEST_URL overrides it). The
shape is sd.cpp's: one tag_name, upstream_repo, and one archive per backend
id with its sha256 and size, downloaded from this repository's releases
(download_base) or, without it, from upstream_repo's release of the tag.
The flow is sd.cpp's too, with its own files, so the two engines never touch
each other's manifests or releases.
-
The live manifest does not exist until the first approval writes it.
backends/audiocpp-manifest.staging.jsonis the candidate slot: the mirror writes it by default, test builds of the app read it, core'sengine-candidatechecks the build it names, andaudiocpp-approve.ymlcopies it into the live manifest. It names the newest candidate, passed or not. Its first content is upstream'sv0.9.3as published (nodownload_base, not re-signed), so core work can start before the fork exists. -
Builds come from the Atomic fork, AtomicBot-ai/audio.cpp (workflow
Release (Atomic): a release per upstream tagvX.Y.Z, with archivesaudio-<tag>-bin-<backend id>.zipand the CUDA runtime companionaudio-<tag>-cudart-win-cu12-x64.zip), and are signed here bymirror-audiocpp.yml: Authenticode on Windows, Developer ID on macOS; Linux archives and the cudart companion pass through byte-for-byte. Withatomic_rev(the fork commit the archives were built at, 7 hex) the release here and the manifest are taggedvX.Y.Z-a<rev>. -
source_repo=0xShug0/audio.cppmirrors upstream's own archives instead, for emergencies and the bootstrap (bare tag only, noatomic_rev). Upstream publishes the six required builds and the CUDA 12 runtime under its own names; its non-portable, ROCm and CUDA 13 archives are not mirrored:Backend id Fork archive Upstream archive macos-arm64audio-<tag>-bin-macos-arm64.zip(universal)audio-<tag>-bin-macos-arm64-metal.tar.gz(arm64 only)win-cpu-x64audio-<tag>-bin-win-cpu-x64.zipaudio-<tag>-bin-windows-x64-cpu-portable.zipwin-vulkan-x64audio-<tag>-bin-win-vulkan-x64.zipaudio-<tag>-bin-windows-x64-vulkan-portable.zipwin-cuda12-x64audio-<tag>-bin-win-cuda12-x64.zipaudio-<tag>-bin-windows-x64-cuda12.4.zipwin-cudart-cu12(companion)audio-<tag>-cudart-win-cu12-x64.zipaudio-<tag>-cudart-windows-x64-cuda12.4.ziplinux-cpu-x64audio-<tag>-bin-linux-cpu-x64.zipaudio-<tag>-bin-ubuntu-x64-cpu-portable.tar.gzlinux-vulkan-x64audio-<tag>-bin-linux-vulkan-x64.zipaudio-<tag>-bin-ubuntu-x64-vulkan-portable.tar.gzwin-cuda13-x64,linux-cpu-arm64,linux-cuda13-arm64,win-cpu-arm64,win-cuda13-arm64audio-<tag>-bin-<backend id>.zip— -
Core orders tags by version; at an equal version the
-a<rev>rebuild is newer than the bare tag. It never moves an installed engine back.
-
In the fork, run
Release (Atomic)withupstream_tag=vX.Y.Zandpublish=true. Note the fork commit it built: that isatomic_rev. -
Mirror into the staging slot (the default
manifest_path):gh workflow run mirror-audiocpp.yml --repo AtomicBot-ai/atomic-chat-conf \ -f tag=vX.Y.Z -f atomic_rev=<rev>
It publishes the signed release
vX.Y.Z-a<rev>here, then commits the staging manifest to main. -
Run core's
engine-candidatewithengine=audio-cpp,repo=AtomicBot-ai/atomic-chat-conf,tag=vX.Y.Z-a<rev>andconf_refat or after the mirror's commit. It must pass. Itsresults.json(artifactengine-candidate-results) records the conf commit it read asconf.sha. -
Approve:
gh workflow run audiocpp-approve.yml --repo AtomicBot-ai/atomic-chat-conf \ -f tag=vX.Y.Z-a<rev> -f conf_sha=<conf.sha>
audiocpp-approve.yml does nothing when the live manifest already names the
tag. Otherwise it refuses unless:
backends/audiocpp-manifest.staging.jsonatconf_sha, a commit of main, names the tag, downloads from this repository, and lists every archive with thesizeandsha256of this repository's release of the tag (the release'sdigest);- a successful
engine-candidaterun in core has the tag as a word of its title, and itsresults.jsonsaysstatus: pass,engine: audio-cpp,candidate.repoAtomicBot-ai/atomic-chat-confandcandidate.tagthe tag (upstream-verify.mjs gate --engine audio-cpp). A run on the fork's own release of a bare tag names the same word but not this repository, so it does not count.
Then it writes that staging manifest, with a new updated_at, to
backends/audiocpp-manifest.json, validates it like CI does and pushes
chore(audiocpp-manifest): approve <tag> to main. Unlike sd.cpp, a bare tag
(vX.Y.Z, mirrored from upstream or from the fork without atomic_rev) may
be approved too: no installed engine predates the first build, and the fork's
later -a<rev> build of the same tag still reaches every client as an update.
The mirror refuses the tag the live manifest names: a re-run re-signs every
archive in place, and clients already hold the old hashes. Mirroring with
manifest_path=backends/audiocpp-manifest.json writes the live manifest
directly, without the check; it is for emergencies only.
The engine update pipeline
(atomic-hatchet-pipeline)
does not run audio.cpp yet. When it does, it runs the steps above as it does
for sd.cpp: mirror-audiocpp.yml with candidate_id=<id>, core's
engine-candidate with engine=audio-cpp, then audiocpp-approve.yml with
the run's conf.sha; each run is found by [cid:<id>] in its title. Both
conf workflows share the mirror-audiocpp concurrency group, so the release
and the manifests are never rewritten at the same time; sd.cpp and llama.cpp
mirrors run independently.
Revert the approval commit (chore(audiocpp-manifest): approve <tag>) on
main. The live manifest names the previous tag again (reverting the very first
approval removes the live manifest), and cores that have not installed the bad
build yet stop being offered it. Cores that have installed it stay on it,
because core never moves an engine back; the fix is the next build through the
steps above. The revert works only while the previous tag's release still
exists here: the mirror prunes all but the newest retain audio.cpp releases
(vX.Y.Z and vX.Y.Z-a<rev> tags only, 3 by default), keeping the tags the
manifests name.
backends/mlx-manifest.json pins the one
mlx-server build Atomic Chat runs MLX models with on Apple Silicon. Builds
come from the AtomicBot-ai/mlx-vlm fork, which builds a
Neywa-Labs/mlx-vlm release tag with
its patch series, signs the binary with the Developer ID and notarizes it.
mirror-mlx.yml copies such a build into
a release here; the manifest points at that copy. Schema:
backends/mlx-schema.json.
{
"$schema": "./mlx-schema.json",
"upstream_repo": "AtomicBot-ai/atomic-chat-conf",
"tag_name": "mlxvlm-macos-arm64-a1b2c3d",
"upstream_tag": "v0.7.12",
"published_at": "2026-11-12T10:00:00Z",
"assets": [
{
"backend": "macos-arm64",
"name": "mlxvlm-mlx-server-macos-arm64.tar.gz",
"sha256": "…",
"size": 287000000
}
]
}backends/mlx-manifest.staging.json is
the candidate slot, in the same form: mirror-mlx.yml writes it, core's
engine-candidate checks it, mlx-approve.yml copies it into the live one.
- Atomic Chat core reads it from
main(no pinned commit) to show the MLX build catalog, check for an MLX update and install one into<data>/mlx/backends. It keeps the last accepted copy on disk and answers from it when offline.ATOMIC_MLX_MANIFEST_URL(https://orfile://) points core at another copy during development. - The desktop Makefile (
make build-mlx-serverinatomic-chat) bundles the same build into the installer, checkingsha256before unpacking, and writes{tag, published_at}next to the binary so core can compare the bundled build with downloaded ones.MLX_MANIFEST=<file>points it at a local copy. - The hatchet pipeline compares new Neywa-Labs/mlx-vlm releases with
upstream_tag.
Because core reads main directly, merging a newer published_at offers
that build as an update to every running client within about an hour.
upstream_repo— the repository whose release holds the archive: this one for a mirrored build,AtomicBot-ai/mlx-vlmfor the builds beforemirror-mlx.yml. The download URL ishttps://github.com/<upstream_repo>/releases/download/<tag_name>/<name>.tag_name—mlxvlm-macos-arm64-<commit>, the fork commit the build was made at. Released cores accept no other form. The commit hash says nothing about order.upstream_tag(optional) — the Neywa-Labs/mlx-vlm release the build is based on. Clients ignore it.published_at— the release'spublishedAton GitHub. This is the version order: clients treat a build as an update only when it was published strictly later than the active one, so rolling the manifest back to an older release never downgrades anyone. A bad build is fixed by a newer one.assets— exactly one archive,backend: "macos-arm64".sha256andsizeare mandatory: the pinned hash is the only check on what gets executed.sha256is the asset's GitHubdigestwithout thesha256:prefix.
The release that backends/mlx-manifest.json on main points at must not
be deleted, and its asset must not be re-uploaded. Deleting it breaks every
MLX install and every desktop build (404); re-uploading the archive changes
its hash, so every install and build fails the sha256 check. To ship a
different build, publish a new release and repoint the manifest. Once main
points elsewhere, the old release may go. mirror-mlx.yml refuses to mirror
the tag the live manifest names, and prunes only mirrored MLX releases no
manifest names.
The hatchet pipeline does this for every new Neywa-Labs/mlx-vlm release; by hand it is the same three steps:
-
Mirror the fork's build of the tag.
atomic_revis the first seven characters of the fork commit the build ran at (in the fork release's notes):gh workflow run mirror-mlx.yml -R AtomicBot-ai/atomic-chat-conf -f tag=v0.7.12 -f atomic_rev=a1b2c3d
It checks the Developer ID signature and the notarization on macOS, copies the archive into the release
mlxvlm-macos-arm64-<atomic_rev>here and writes the staging manifest. -
Check it on a core release: core's
engine-candidate.ymlwithengine=mlx,repo=AtomicBot-ai/atomic-chat-conf,tag=mlxvlm-macos-arm64-<atomic_rev>. Itsresults.jsonmust saypass;conf.shain it is the commit of this repository it read. -
Approve with that commit:
gh workflow run mlx-approve.yml -R AtomicBot-ai/atomic-chat-conf -f tag=mlxvlm-macos-arm64-a1b2c3d -f conf_sha=<conf.sha>
It checks the staging manifest of that commit against the release, refuses a tag no passing
engine-candidaterun backs, and pushes it tobackends/mlx-manifest.json.
backends/foundry-local-manifest.json
lists the Foundry Local releases Atomic Chat core installs as the
foundry-local engine build: the native Foundry Local library and ONNX
Runtime GenAI that run the foundry-local provider's models. Schema:
backends/foundry-local-schema.json;
integrity checks:
.github/scripts/foundry-local-manifest-check.mjs.
{
"$schema": "./foundry-local-schema.json",
"schema_version": 1,
"upstream_repo": "microsoft/foundry-local",
"releases": [
{
"tag": "v2.1.0",
"published_at": "2026-09-30T00:43:42Z",
"min_core_version": "0.18.0",
"c_api_version": 2,
"notes_url": "https://github.com/microsoft/foundry-local/releases/tag/v2.1.0",
"assets": [
{ "platform": "macos-arm64", "name": "foundry-local-osx-arm64.tgz", "size": 52293589, "sha256": "2eeb…080a" }
]
}
]
}Core reads it from main with an hour's cache and a copy on disk, and installs
a release only when the client asks (POST /atomic/v1/engine-builds/foundry-local/install).
Without distribution, the archive URL is
https://github.com/<upstream_repo>/releases/download/<tag>/<name>.
With distribution: "atomic-conf", it is
https://github.com/AtomicBot-ai/atomic-chat-conf/releases/download/foundry-local-<tag>/<name>.
Every download is checked
against size and sha256 before it is unpacked. ATOMIC_FOUNDRY_LOCAL_MANIFEST_URL
(https:// or file://) points core at another copy during development.
schema_version—1.upstream_repo— alwaysmicrosoft/foundry-local.releases— newest first bypublished_at. Each release names its upstreamtag(vX.Y.Z), the upstreampublished_at,notes_url, and:min_core_version— the oldest core that understands the entry. Core skips a release whosemin_core_versionis newer than itself, so a release that needs new core code can be listed without breaking cores already installed.c_api_version—FOUNDRY_LOCAL_API_VERSIONfromsdk_v2/cpp/include/foundry_local/foundry_local_c.hat that tag. Core skips a release whosec_api_versionits host does not support: a C API bump changes the structures the host passes to the library.distribution— optional, the only accepted value isatomic-conf. Omit it for the original Microsoft archives.assets— one archive per platform, all five required:win-x64,win-arm64,macos-arm64,linux-x64,linux-arm64. Core selects byplatform, never by parsingname.sizeandsha256identify the published archive. Repacked assets are also downloaded from their final URLs and compared with the verified local archives before listing.
Besides the schema, CI rejects a duplicate tag, a duplicate platform or
asset name within a release, a release missing one of the five platforms, and
releases out of published_at order.
Once a release entry is on main, its fields do not change: installed builds
are identified by tag, and a different archive under the same tag would fail
every install's sha256 check. A new upstream release is a new entry at the
top; a broken one is removed (new installs stop within the hour), not edited.
gh api repos/microsoft/foundry-local/releases/tags/v2.1.0 --jq '{tag: .tag_name, published_at, notes_url: .html_url, assets: [.assets[] | {name, size, sha256: (.digest | ltrimstr("sha256:"))}]}'
gh api "repos/microsoft/foundry-local/contents/sdk_v2/cpp/include/foundry_local/foundry_local_c.h?ref=v2.1.0" --jq .content | base64 -d | grep 'define FOUNDRY_LOCAL_API_VERSION'Map each asset to its platform (osx-arm64 is macos-arm64), set
min_core_version to the first core release that supports this release,
insert the entry at the top of releases, validate the Foundry schema and
integrity checks below, and open a PR.
The five selected native archives and the retained original Windows x64 ZIP are published in
foundry-local-v2.4.0.
The candidate contains both
2.4.0 (C API 3) and the original 2.1.0 (C API 2). Windows x64 selects the
NPU-compatible foundry-local-win-x64-openvino-1-8-1.zip, whose public bytes,
size (93,972,839) and SHA-256
(23ce1fea75d64254e99042c3e99e1fc2bb0dd5befff07d4a013857920c67b2a1)
were verified after publication. The five original release assets are unchanged. The candidate requires core 0.22.4, the release that includes managed CUDA
preparation and Windows DLL isolation. Promote it after that core release is
published and app/server qualification in tasks 3.3 and 4.3 is complete.
Older cores continue to select the original 2.1.0.
Build with Python 3.11 or later. Only the release maintainer needs Python,
network access to NuGet and authenticated gh for publication.
packages.json pins the three Microsoft NuGet packages and Intel OpenVINO 1.8.1
(Windows x64 only), including their versions and catalog SHA-512 hashes. The packer validates all
inputs before packaging native files for each RID, preserves native bytes,
includes each package's licenses and notices, and verifies every output
member, runtime JSON hash, executable mode and ORT symlink.
macOS ORT aliases resolve to the same versioned dylib. Windows archives
include the supplied WinML DLLs and import libraries. The NPU-compatible Windows
x64 archive is named foundry-local-win-x64-openvino-1-8-1.zip; it adds the pinned
Intel EP and its native dependencies under lib/openvino/. The Intel package
uses an MIT license expression instead of a root LICENSE file: retain its
original nuspec, README and third-party notices. Core 2.4 hosts explicitly
register this EP on their shared ORT environment instead of the system WinML
OpenVINO 1.8 EP, whose experimental API calls fail on ORT 1.31. Both native DLL
signatures and all other platforms' original payloads are preserved.
The original foundry-local-win-x64.zip remains in the release unchanged. The
publisher verifies it against the original three Microsoft packages and adds
the new archive under its own name. A candidate must point Windows x64 at the
new name only after the new public download is verified. Existing development
installs of the original 2.4.0 archive must be unloaded and explicitly removed
before installing the corrected candidate: the immutable build check correctly
refuses to replace a recorded digest silently. This does not remove models.
python3 .github/scripts/foundry-local/pack.py /tmp/foundry-nuget /tmp/foundry-assets
python3 .github/scripts/foundry-local/publish.py /tmp/foundry-nuget /tmp/foundry-assets backends/foundry-local-manifest.candidate.json --min-core-version 0.22.0 --target change/upgrade-foundry-local-2-4
npx --yes ajv-cli@5 validate -s backends/foundry-local-schema.json -d 'backends/foundry-local-manifest*.json' --strict=false
node .github/scripts/foundry-local-manifest-check.mjs backends/foundry-local-manifest.json backends/foundry-local-manifest.candidate.jsonArchive timestamps and ownership are normalized for repeat builds. An existing release asset must match the verified local archive before any missing asset is uploaded. Publication never overwrites an asset. A rerun resumes an interrupted draft or verifies the existing public release. The candidate is written only after all five selected public downloads match local bytes, GitHub sizes and SHA-256 digests. Preserve the original Python/zlib environment when reproducing compressed bytes (this release used Python 3.11.11 and zlib 1.2.12). A different compressor producing a different archive is rejected by the publication check.
For a Windows-only packaging change, use pack.py <cache> <out> --rid win-x64.
The focused checks are python3 .github/scripts/foundry-local/test_pack.py and
python3 .github/scripts/foundry-local/test_publish.py, followed by
node --test .github/scripts/foundry-local-manifest-check.test.mjs.
Use the absolute path of the candidate in the core process environment.
export ATOMIC_FOUNDRY_LOCAL_MANIFEST_URL="file://$PWD/backends/foundry-local-manifest.candidate.json"Set this variable before starting core. Implement the distribution URL and C API 3 support in core against this candidate. Native loading, accelerator preparation and model generation are qualified in the core/app/server tasks.
Remove its entry from the production manifest to stop new offers as caches
refresh. Keep release assets immutable. An installed runtime stays selected
until an explicit local action. To return a host to its retained 2.1.0,
unload the 2.4.0 sessions, delete only the 2.4.0 build through
DELETE /atomic/v1/engine-builds/foundry-local/v2.4.0/<platform>,
then confirm selection of 2.1.0 and a response from the existing model.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/foundry-local-models.json tells
the app where Foundry Local models come from and which of them Atomic Chat has
curated. Schema:
models/schema.foundry-local-models.json;
integrity checks:
.github/scripts/foundry-local-models-check.mjs.
The endpoints are undocumented. Both the resolve endpoint and the catalog are internal Microsoft APIs that answer without an account. They can change without notice. Small changes (a host, a path, a region) are fixed by editing this file, which reaches clients within the hour; a changed response format needs an app release.
The list currently has no curated models ("models": []): hashing the
first ten models means downloading 212 GB, which has not been done yet. Until
then the Hub shows the Microsoft catalog only, marked "Microsoft catalog, not
verified by Atomic Chat".
The app reads it from main with an hour's cache and keeps the last accepted
copy when the fetch fails. In the Model Hub, under the "Foundry Local" format,
it shows the curated models first and then the chat models of the Microsoft
catalog at catalog.url. A catalog variant with the same asset_id and
version as a curated one is shown as the curated entry. The app downloads a
variant itself, from Azure Blob Storage, through the link resolver returns;
core never downloads Foundry Local models.
A curated file is checked by size and sha256 from this list. A catalog
variant has no hash anywhere (the API does not publish one, and Microsoft's own
client checks size only), so it is checked by the sizes in its container
listing — which is why only a curated entry counts as verified.
schema_version—1. The app ignores a list with a higher one and keeps its last accepted copy.resolver.url_template— the resolve URL, with{region}and{asset_id}(URL-encoded by the app). The answer'sblobSasUriis a read+list SAS link to the variant's blob container that lives for a few hours; on a 403 the app resolves again and resumes.resolver.regions— tried in order until one answers.catalog.url— the Microsoft catalog (asset-gallery) the app queries.models[]—id,name,description,task(chat),license,context_length(the largest of the variants),tools,reasoning, andvariants[]:id— unique across the list: it names the download and the folder<data>/foundry-local/models/<id>/. The catalog name, lowercased.device(cpu,gpu,npu) andexecution_provider(cpu,cuda,webgpu,openvino,qnn,vitisai; never TensorRT-RTX).platforms— where the variant is offered:cpuon all five;cudaonwin-x64andlinux-x64;webgpuon Windows andmacos-arm64;qnn,openvino,vitisaion the Windows platform the accelerator exists for.context_length— only when the variant's context is smaller than the model's (NPU builds are compiled for 4K); the app uses it instead.source—{kind: "azureml", asset_id, version, path_prefix}: the full asset id as the catalog spells it, its version, and the folder inside the container (kvTags.directoryPath).files[]—path(relative topath_prefix, and to the variant folder on disk),size,sha256. At least one.
Besides the schema, CI rejects duplicate model or variant ids, the same asset
twice, a duplicate file path within a variant, ./.. path segments, a model
without variants, a resolve template missing {region} or {asset_id}, a
non-https catalog.url, a variant offered on a platform its execution
provider does not run on, and a variant context_length not smaller than the
model's.
The app skips a variant whose source.kind, execution provider or device it
does not know, and a model left with no variants; the rest of the list still
applies. So a new kind of source (say, hf) is added as extra variants next
to the existing azureml ones, never by converting them: released apps keep
the variants they understand.
- Find its variants in the catalog (
POSTtocatalog.urlwith{"filters": [{"field": "labels", "operator": "eq", "values": ["latest"]}], "pageSize": 50}, followingcontinuationToken); keepdeploymentOptions"Foundry Local on Devices" and dropNvTensorRTRTXExecutionProvider. - Resolve each variant (
resolver.url_template). Model fields come frommodelEntity.kvTags:contextLength,supportsToolCalling,supportsReasoning,license;path_prefixisdirectoryPath. - List the container (
<blobSasUri base>?restype=container&comp=list&prefix=<path_prefix>/&<sas>) for paths and sizes only. - Download every file once and take
shasum -a 256. Never copy a hash from anywhere else:blobManifestDigestuses an unknown algorithm. - Add the model, run
make validate, open a PR.
backends/litert-lm-manifest.json lists
the LiteRT-LM releases Atomic Chat core installs as the litert-lm engine
build: Google's native LiteRT-LM library, which runs the litert-lm
provider's .litertlm models. Google ships no desktop binaries on GitHub, so
the source is the litert-lm-api wheels on PyPI; the core unpacks a wheel as
a zip and keeps only its native files. Schema:
backends/litert-lm-schema.json; integrity
checks:
.github/scripts/litert-lm-manifest-check.mjs.
{
"$schema": "./litert-lm-schema.json",
"schema_version": 1,
"releases": [
{
"version": "0.18.1",
"published_at": "2026-10-19T22:44:33Z",
"min_core_version": "0.19.0",
"abi": 1,
"notes_url": "https://github.com/google-ai-edge/LiteRT-LM/releases/tag/v0.18.1",
"assets": [
{ "platform": "macos-arm64", "url": "https://files.pythonhosted.org/packages/cd/4d/…/litert_lm_api-0.18.1-py3-none-macosx_12_0_arm64.whl", "name": "litert_lm_api-0.18.1-py3-none-macosx_12_0_arm64.whl", "size": 21430663, "sha256": "e599…55cb" }
],
"accelerators": [
{ "id": "openvino", "platform": "win-x64", "version": "2026.4.1", "url": "https://files.pythonhosted.org/packages/d0/44/…/openvino-2026.4.1-22982-cp312-cp312-win_amd64.whl", "name": "openvino-2026.4.1-22982-cp312-cp312-win_amd64.whl", "size": 84964415, "sha256": "4e04…cd87" }
]
}
]
}Core reads it from main with an hour's cache and a copy on disk, and installs
a release only when the client asks (POST /atomic/v1/engine-builds/litert-lm/install
or POST /atomic/v1/engines/litert-lm/update). The wheel is downloaded from
its url and checked against size and sha256 before it is unpacked; the
core then loads it once in a probe run and only after that offers the build.
ATOMIC_LITERT_LM_MANIFEST_URL (https:// or file://) points core at
another copy during development.
schema_version—1.releases— newest first bypublished_at. Each release names the LiteRT-LMversion(the PyPI version oflitert-lm-api), its PyPI upload time aspublished_at,notes_url, and:min_core_version— the oldest core that understands the entry. Core skips a release whosemin_core_versionis newer than itself.abi— our number, not Google's: the set and signatures of the C API functions the core's binding reads. It goes up when they change, which can happen within a LiteRT-LM minor version (0.18.1 was such a fix). Core skips a release whoseabiit does not support, and the active build is the newest installed one with a supportedabi.assets— onelitert-lm-apiwheel per platform, all four required:macos-arm64(macosx_12_0_arm64),linux-x64(manylinux_2_27_x86_64),linux-arm64(manylinux_2_27_aarch64),win-x64(win_amd64). There are no wheels for macOS x64 or Windows arm64, so the provider does not exist there. Core selects byplatform, never by parsingname.urlis the explicitfiles.pythonhosted.orglink from the PyPI JSON API: the path holds hash directories the version does not determine, so it is not a template.accelerators— optional,win-x64only: theopenvinowheel with the OpenVINOversion. Intel NPU models need its native libraries; core downloads it only onPOST /atomic/v1/runtimes/litert-lm/accelerators/prepare, never with the build, since it is 85 MB that only NPU owners need. Anycp3xxwheel will do: core takes onlyopenvino/libs, which is the same in each.
Besides the schema (which already rejects an asset without size or
sha256, a URL outside PyPI and an unknown platform), CI rejects a duplicate
version, a duplicate platform or asset name within a release, a release
missing one of the four platforms, an accelerator listed twice or outside
win-x64, releases out of published_at order, and a published release whose
content changed.
Once a release entry is on main, its fields do not change: the core keeps an
installed build under its version, and a different wheel under the same
version would fail every install's sha256 check. CI compares every release
with the same version on the base branch and fails when the content differs.
A fix is a new release at the top; a broken one is removed (new installs
stop within the hour), not edited.
Take the URLs, sizes and upload time from the PyPI JSON API, then download
every wheel and count sha256 yourself: the hash in the manifest is the only
check on what core loads into its own process, so it must not be a copy of
the one PyPI reports.
curl -fsS https://pypi.org/pypi/litert-lm-api/0.18.1/json | jq '[.urls[] | select(.filename | test("macosx_12_0_arm64|manylinux_2_27|win_amd64")) | {name: .filename, url, size, sha256: .digests.sha256, published_at: .upload_time_iso_8601}]'
curl -fsS https://pypi.org/pypi/openvino/2026.4.1/json | jq '.urls[] | select(.filename | endswith("-cp312-cp312-win_amd64.whl")) | {name: .filename, url, size, sha256: .digests.sha256}'
curl -fLO "<url>" && shasum -a 256 "<name>"Map each wheel to its platform, set published_at to the earliest upload
time of the release, abi to the number core's binding supports for it (a
new number when the C API changed), and min_core_version to the first core
release that supports this one. Insert the entry at the top of releases,
run make validate, and open a PR with the shasum -a 256 output in its
description.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/litert-lm-models.json tells the app
and atc which LiteRT-LM models Atomic Chat has checked and where to find the
rest on Hugging Face. Schema:
models/schema.litert-lm-models.json;
integrity checks:
.github/scripts/litert-lm-models-check.mjs.
{
"$schema": "./schema.litert-lm-models.json",
"schema_version": 1,
"updated_at": "2026-10-22T00:00:00Z",
"huggingface": {
"orgs": ["litert-community"],
"filter": "litert-lm",
"backends": { "macos-arm64": ["cpu", "gpu"], "linux-x64": ["cpu", "gpu"], "linux-arm64": ["cpu", "gpu"], "win-x64": ["cpu", "gpu"] }
},
"models": [
{
"id": "gemma-4-e2b", "name": "Gemma 4 E2B", "description": "…", "task": "chat", "license": "apache-2.0",
"repo": "litert-community/gemma-4-E2B-it-litert-lm", "revision": "41c5…bce7", "gated": false,
"context_length": 32003, "tools": true, "reasoning": true, "vision": true,
"variants": [
{ "id": "gemma-4-e2b-gpu", "backend": "gpu", "platforms": ["macos-arm64", "linux-x64", "linux-arm64", "win-x64"],
"file": { "path": "gemma-4-E2B-it.litertlm", "size": 2588147712, "sha256": "1819…a63c" } },
{ "id": "gemma-4-e2b-npu-lnl", "backend": "npu", "npu": "intel-lnl", "platforms": ["win-x64"],
"file": { "path": "gemma-4-E2B-it_intel_LNL.litertlm", "size": 2960506880, "sha256": "…" } }
]
}
]
}The NPU variant above shows the shape only: the published list has none yet, since NPU opens after acceptance on a real Intel NPU machine.
The core never downloads LiteRT-LM models. The client downloads a variant's
file from https://huggingface.co/<repo>/resolve/<revision>/<path> into
<data>/litert-lm/models/<variant id>/, checks size and sha256, asks the
core to check the file (POST /atomic/v1/models/litert-lm/check) and writes
model.yml last. For a gated repository it sends the user's HF token, and
only to Hugging Face hosts. VITE_LITERT_LM_MODELS_URL (app, dev builds) and
ATC_LITERT_LM_MODELS_URL (atc) point a client at another copy during
development.
schema_version—1; a client keeps the last list it accepted when this is higher than it knows.updated_at— when the list last changed.huggingface— where models beyond the curated ones come from:orgs— organisations the client lists,filter— alwayslitert-lm, the model tag it filters on.backends— for each platform, the backends the client may offer for Hugging Face models there. Onlymacos-arm64,linux-x64,linux-arm64andwin-x64;npuonly onwin-x64.
models— curated models, shown first in the order listed; may be empty. Each hasid,name,description,task(chat),license, the Hugging Facerepoand the full commitrevisionits files are pinned to,gated, the defaultcontext_length(the host never goes above the file's own maximum), thetools,reasoningandvisionflags, andvariants:id— unique across the list: it names the download task and the folder on disk.backend—cpu,gpuornpu;npu— the NPU generation annpuvariant's file is compiled for ahead of time,intel-lnl(Lunar Lake) orintel-ptl(Panther Lake). Required onnpuvariants, forbidden on others.platforms— where the variant is offered.npuruns only onwin-x64.min_runtime_version— optional, the oldest LiteRT-LM the file loads in, when it is known before the download; the core reads the real one from the file.file—pathinside the repository (the file keeps its name in the variant folder),sizeandsha256.
A client hides a variant whose backend, NPU target or platform it does not
know, and a model left with no variants, instead of dropping the list. Besides
the schema, CI rejects duplicate model or variant ids, two curated models for
one repo, unsafe file paths, a backend on a platform where it does not run,
and an unknown platform or backend in huggingface.backends.
The client lists GET /api/models?author=<org>&filter=litert-lm for every
org, shows those models after the curated ones marked "Hugging Face, not
checked by Atomic Chat", and uses the curated entry instead for a repo the
list already has. Variants come from the .litertlm file names of the repo at
the commit of the listing:
- a
-gpuor_gpusuffix —gpu; _intel_LNLor_intel_PTL—npuwithintel-lnlorintel-ptl;- no suffix —
cpu, and alsogpuwhen the repo has no GPU-suffixed file; -web,_web, other chip suffixes (_sm<n>,_mt<n>,_Google_Tensor_*and the like) and.taskfiles are never offered;- a variant whose backend
huggingface.backendsdoes not allow on the host platform is not offered.
Size and sha256 come from the LFS metadata of the repo tree, so these files
are checked too.
A backend that turns out bad on a platform is closed without a release of the
app or atc, within the hour of the merge: remove the platform from the
platforms of the curated variants with that backend, and remove the backend
from that platform in huggingface.backends for Hugging Face models.
Pin revision to the repo's current commit
(curl -fsS https://huggingface.co/api/models/<repo> | jq -r .sha), pick the
files by the rule above, and download each one from its resolve/<revision>
URL. Count sha256 and size yourself (shasum -a 256, stat): do not copy
them from Hugging Face. Read each file with core's litert-host inspect for
its backends, context and modalities; its tool calling and thinking flags are
often false even when the model has both, so take tools and reasoning
from the model card, together with any minimum LiteRT-LM version. Prefer the
main file for a gpu variant when it lists gpu: a -gpu file is text only,
and gemma-4-E2B-it-gpu.litertlm produced broken output on Metal. Run
the same greedy prompt on CPU and GPU before opening a GPU variant on a
platform. Then run make validate, and open a PR with the shasum -a 256
table in its description.
backends/geniex-manifest.json lists the
GenieX releases Atomic Chat core installs as the geniex engine build:
Qualcomm's GenieX SDK (geniex.dll, its llama_cpp and qairt plugins and
the Microsoft-signed HTP files), which runs the geniex provider's GGUF
models and AI Hub bundles on the Snapdragon X NPU, GPU or CPU. Qualcomm
publishes the SDK as a zip on GitHub and on its S3 mirror
(qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-geniex/); the core
unpacks the zip and keeps only lib/**. Schema:
backends/geniex-schema.json; integrity
checks:
.github/scripts/geniex-manifest-check.mjs.
{
"$schema": "./geniex-schema.json",
"schema_version": 1,
"releases": [
{
"version": "0.9.3",
"published_at": "2026-10-19T23:09:06Z",
"min_core_version": "0.20.0",
"abi": 1,
"notes_url": "https://github.com/qualcomm/GenieX/releases/tag/v0.9.3",
"assets": [
{ "platform": "win-arm64", "url": "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-geniex/geniex-sdk-windows-arm64-v0.9.3.zip", "name": "geniex-sdk-windows-arm64-v0.9.3.zip", "size": 91519631, "sha256": "3edf…0446" }
]
}
]
}Core reads it from main with an hour's cache and a copy on disk, and only on
Windows arm64 with a Snapdragon X Elite or X2 Elite: elsewhere the provider
does not exist. It installs a release only when the client asks
(POST /atomic/v1/engines/geniex/update or the first install from the
provider page). The zip is downloaded from its url and checked against
size and sha256 before it is unpacked; the core then runs
geniex-host probe against the unpacked lib/ and offers the build only
after the probe answers. No administrator rights, driver install or test
signing: the HTP files load from the build folder.
ATOMIC_GENIEX_MANIFEST_URL (https:// or file://) points core at another
copy during development.
schema_version—1.releases— newest first bypublished_at. Each release names the GenieXversion(the release tag without itsv), thereleased_atof the mirror'smanifest-<tag>.jsonaspublished_at,notes_url(the GitHub release page), and:min_core_version— the oldest core that understands the entry. Core skips a release whosemin_core_versionis newer than itself.abi— our number, not Qualcomm's: the set and signatures of the C API functions the core's binding reads. GenieX is pre-1.0 and changes its header with minor versions, so it goes up when they change. Core skips a release whoseabiit does not support, and the active build is the newest installed one with a supportedabi.assets— one SDK zip per platform,win-arm64only for now. Core selects byplatform, never by parsingname.urlis explicit and must sit on the S3 mirror or undergithub.com/qualcomm/GenieX/releases/download/; the core refuses any other host.
Besides the schema (which already rejects an asset without size or
sha256, a URL on another host, an unknown platform and an unknown field),
CI rejects a duplicate version, a duplicate or missing platform and a
duplicate asset name within a release, releases out of published_at order,
and a published release whose content changed.
Once a release entry is on main, its fields do not change: the core keeps an
installed build under its version, and a different zip under the same version
would fail every install's sha256 check. CI compares every release with the
same version on the base branch and fails when the content differs. A fix is
a new release at the top; a broken one is removed (new installs stop
within the hour), not edited.
Take the URL, size and release time from the mirror's manifest-<tag>.json,
then download the zip and count sha256 yourself: the hash in the manifest is
the only check on what core loads into its own process, so the mirror's
number is a cross-check, not the source.
curl -fsS https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-geniex/manifest-v0.9.3.json | jq '{published_at: .released_at, assets: [.assets[] | select(.kind == "sdk" and .platform == "windows") | {name, url, size, sha256}]}'
curl -fLO "<url>" && shasum -a 256 "<name>"Set published_at to released_at, abi to the number core's binding
supports for it (a new number when the C API changed), and
min_core_version to the first core release that supports this one. Insert
the entry at the top of releases, run make validate, and open a PR with
the shasum -a 256 output in its description.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/geniex-models.json tells the app and
atc which GenieX models Atomic Chat has checked and how to fill the list
from Hugging Face. Schema:
models/schema.geniex-models.json;
integrity checks:
.github/scripts/geniex-models-check.mjs.
{
"$schema": "./schema.geniex-models.json",
"schema_version": 1,
"updated_at": "2026-10-27T00:00:00Z",
"huggingface": {
"quantizations": ["Q4_0"],
"backends": { "win-arm64": ["npu", "gpu", "cpu", "hybrid"] }
},
"models": [
{
"id": "gemma-4-e2b", "name": "Gemma 4 E2B", "description": "…", "task": "chat", "license": "gemma",
"context_length": 32768, "tools": true, "reasoning": true, "vision": true,
"kind": "gguf", "repo": "google/gemma-4-E2B-it-qat-q4_0-gguf", "revision": "…", "gated": true,
"file": { "path": "gemma-4-E2B_q4_0-it.gguf", "size": 0, "sha256": "…" },
"mmproj": { "path": "gemma-4-E2B-it-mmproj.gguf", "size": 0, "sha256": "…" },
"devices": ["npu", "gpu", "cpu", "hybrid"], "platforms": ["win-arm64"]
},
{
"id": "qwen3-4b-qairt", "name": "Qwen3 4B (AI Hub)", "description": "…", "task": "chat", "license": "apache-2.0",
"context_length": 4096, "tools": true, "reasoning": true, "vision": false,
"kind": "qairt",
"variants": [
{ "id": "qwen3-4b-x-elite", "chip": "x-elite", "precision": "w4a16", "min_runtime_version": "0.9.3",
"bundle": { "url": "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/…/snapdragon-x-elite/….zip", "size": 0, "sha256": "…" } }
]
}
]
}The models above show the two shapes only (the published file carries the
real names, sizes and checksums). The first curated set, from core's spike on a
Snapdragon X2 Elite (2026-10-28): Qwen3 4B, Gemma 4 E2B and E4B as GGUF
(Q4_0; Q4_K_M runs on the NPU too, so Hugging Face offers both), and the
Qwen3 4B AI Hub bundle for x-elite and x2-elite. Gemma 4 E4B has no
hybrid device (GenieX 0.9.3's OpenCL backend asserts), and the bundle has
tools: false (the qairt plugin passes no tools to the model). AI Hub v0.65.0
ships no GenieX bundle for Gemma 4 or a VLM.
Two kinds of model:
gguf— a GGUF file the GenieXllama_cppplugin runs on the Hexagon NPU, the Adreno GPU, the CPU, orhybrid(prefill on the NPU, decode on the CPU). One file serves every device: the device is a setting of the downloaded model, changed without a new download.qairt— a bundle Qualcomm AI Hub compiled for one chip, run by theqairtplugin on the NPU only. A model lists one variant per chip; the client shows only the variant for the machine's chip.
The core never downloads GenieX models. The client downloads a GGUF (and its
mmproj) from https://huggingface.co/<repo>/resolve/<revision>/<path> into
<data>/geniex/models/<model id>/, or a bundle zip from its url into
<data>/geniex/models/<variant id>/ (unpacked there, the zip deleted), checks
size and sha256, asks the core to check the model
(POST /atomic/v1/models/geniex/check) and writes model.yml last. For a
gated repository it sends the user's HF token, and only to Hugging Face
hosts. VITE_GENIEX_MODELS_URL (app, dev builds) and ATC_GENIEX_MODELS_URL
(atc) point a client at another copy during development.
schema_version—1; a client keeps the last list it accepted when this is higher than it knows.updated_at— when the list last changed.huggingface— how GGUF models beyond the curated ones are offered:quantizations— the GGUF quantizations the client offers from a Hugging Face repository (Q4_0,Q8_0,F16,Q4_K_M,Q5_K_M); other files are not offered.Q4_0only until the NPU is measured with K-quants.backends— for each platform, the devices the client may offer for Hugging Face models there. Onlywin-arm64, where all four run.
models— curated models, shown first in the order listed; may be empty. Each hasid(unique across the list together with variant ids: it names the download task and the folder on disk),name,description,task(chat),license, the defaultcontext_length, thetools,reasoningandvisionflags, andkind:gguf— the Hugging Facerepoand the full commitrevisionits files are pinned to,gated,file(pathinside the repository,size,sha256),mmprojin the same shape (required whenvisionis true),devicesthe model is offered on andplatforms.qairt—variants, each withid,chip(x-eliteorx2-elite),bundle(urlon AI Hub's S3qai-hub-models,size,sha256),precisionas AI Hub names it (w4a16), and optionalmin_runtime_version, the oldest GenieX the bundle loads in when known before the download; the core reads the real one from the bundle'sgeniex.json.
A client hides a model of a kind, a variant of a chip and a device it does
not know, and a model left with nothing to offer, instead of dropping the
list. Besides the schema (which also rejects a bundle variant without chip,
a GGUF without devices, a vision GGUF without mmproj, a bundle URL off
AI Hub's S3 and any file or bundle without sha256), CI rejects duplicate
ids across models and variants, two curated GGUFs for one repo, unsafe file
paths, a device on a platform where it does not run, two bundle variants for
one chip, and an unknown platform or device in huggingface.backends.
The client runs the same GGUF repository search as the llama.cpp provider,
shows the results after the curated ones marked "Hugging Face, not checked
by Atomic Chat", and uses the curated entry instead for a repo the list
already has. From a repository it offers only the files whose quantization is
in huggingface.quantizations, finds mmproj when the repository has one,
takes size and sha256 from the LFS metadata of the repository tree, pins
revision to the commit of the listing, and offers the devices
huggingface.backends allows on the host platform. Bundles never come from
Hugging Face: their only source is this list. When Hugging Face is down the
client shows the curated list alone and says so.
A device that turns out bad is closed without a release of the app or atc,
within the hour of the merge: remove it from the devices of the curated
GGUF models and from the platform in huggingface.backends for Hugging Face
models. A bad bundle is removed from variants; installed copies keep
working.
For a GGUF, pin revision to the repo's current commit
(curl -fsS https://huggingface.co/api/models/<repo> | jq -r .sha), pick the
Q4_0 file and the mmproj for a vision model, and download each one from
its resolve/<revision> URL. For a bundle, take download_url for the chip
from the model's release-assets.json on AI Hub's S3
(qai-hub-models/releases/latest/manifest.json lists the models) and
download the zip. Count sha256 and size yourself (shasum -a 256,
stat): Hugging Face numbers are a cross-check and AI Hub publishes none.
Read each GGUF with core's geniex-host inspect for its context and
modalities, and each bundle's geniex.json for its chip, context, precision
and minimum GenieX version; set tools only where the host parses the
model's tool calls reliably. Open a device on a model only after the same
greedy prompt was checked on it against the CPU. Then run make validate,
and open a PR with the shasum -a 256 table in its description.
A runtime descriptor tells atomic-chat-core which container image a
managed engine (TensorRT-LLM, vLLM, SGLang) runs, pinned by digest, what host
it needs, and what that release supports. There is one descriptor per
engine, named after it: runtimes/<engine_id>.json (tensorrt-llm.json,
vllm.json, sglang.json), all validated by the one shared
runtimes/schema.json. The file
name is the engine: a descriptor whose engine_id differs from its file
name fails make validate and CI, because core fetches
runtimes/<engine_id>.json for the engine it has an adapter for and refuses a
descriptor carrying another engine's id. CI and make validate discover every
runtimes/*.json except schema.json, so a new engine's descriptor is
checked without editing either. It carries data only — no
command, script or argv lives in it — and it describes the engine alone.
Where core may set up the foundation every engine runs on (which Linux
distributions it can install a GPU container runtime on) is environment data,
shared by all engines; it lives in the environment
manifest, not here. The schema
rejects a descriptor that carries environment install data, and so does core.
No released atomic-chat-core reads runtimes/: core 0.7.0–0.7.4 and every
already-released Atomic Chat app and CLI never fetch or parse this directory,
so publishing or changing a document here has no effect on them. The
environment manifests require core 0.7.5 or later; the current descriptor
tensorrt-llm-1.3.0rc29-r3 requires core 0.7.6 (its
minimum_core_version): 0.7.5 refuses its architecture names with an
underscore and cannot read mixed-precision checkpoints, so it keeps whatever
descriptor it accepted before.
Every released core up to 0.9.9 reads only runtimes/tensorrt-llm.json.
runtimes/vllm.json is read only by a core built with the vllm adapter
(the core release of change add-vllm-runtime), and such a core treats each
engine's descriptor on its own: a missing or invalid vllm.json makes vLLM
unavailable and leaves TensorRT-LLM as it was. The same holds for
runtimes/sglang.json: only a core built with the sglang adapter (the core
release of change add-sglang-runtime) reads it, and a missing or invalid
file makes SGLang unavailable without touching the other engines.
core fetches each engine's descriptor from this repository's main branch.
For development, the source of each engine can be overridden with
ATOMIC_RUNTIME_DESCRIPTOR_URL_<ENGINE> — the engine id upper-cased, -
replaced by _ — set to a file:// path or a URL:
ATOMIC_RUNTIME_DESCRIPTOR_URL_VLLM=file://$PWD/runtimes/vllm.json
ATOMIC_RUNTIME_DESCRIPTOR_URL_SGLANG=file://$PWD/runtimes/sglang.json
ATOMIC_RUNTIME_DESCRIPTOR_URL_TENSORRT_LLM=file://$PWD/runtimes/tensorrt-llm.jsonThe older ATOMIC_RUNTIME_DESCRIPTOR_URL keeps overriding tensorrt-llm only.
Publishing runtimes/vllm.json on main is the switch that turns vLLM on:
a core with the vllm adapter shows the engine only once the file is there
(a 404 means "unavailable", with no release and no restart needed when it
appears). So the descriptor lives on the change branch and is merged into
main only after the live acceptance on Linux and Windows has passed, and
after the app release that ships vLLM is out. CI and README changes can reach
main earlier: they are safe for every released client. Until the file is
merged its descriptor_id is not published, so acceptance findings are
fixed in place on the branch; from the merge on, the immutability rule below
applies to it like to any other descriptor. Removing vllm.json from main
switches vLLM off for everyone without a release.
The same rule holds for SGLang, for the same reason: publishing
runtimes/sglang.json on main turns SGLang on for every core with the
sglang adapter, within the hour and without a release. The descriptor lives
on the branch of change add-sglang-runtime and is merged into main only
after the live acceptance on Linux and Windows has passed and after the app
release that ships SGLang is out; README changes may reach main earlier.
Until the merge, sglang-0.5.21-r1 is unpublished and acceptance findings are
fixed in place on the branch; from the merge on it is immutable like every
other descriptor. Removing sglang.json from main switches SGLang off for
everyone without a release; vLLM and TensorRT-LLM are not affected.
The content published under a given descriptor_id never changes. core
caches an accepted descriptor by this id and pins an installation to it, so
editing a published descriptor's fields in place would silently change what
an already-installed engine is compared against. Any change — the image, the
compute-capability/quantization/architecture matrices, model_families, the
curated model list, or the notices — ships under a new descriptor_id
instead of editing this one. Adding or removing a distribution is not a
descriptor change: it ships as a new manifest_id of the environment
manifest, and the descriptor_id stays as it is.
The new id follows the form and order below:
bump the engine version when the underlying engine release changes
(tensorrt-llm-1.2.1-r2 → tensorrt-llm-1.3.0-r1), or bump n when the
version stays the same but a data-only field changes (a new curated model, a
corrected notice, …). Each descriptor file is compared with its own
version on main, so editing vllm.json under a descriptor_id already on
main fails CI exactly as it does for tensorrt-llm.json.
tensorrt-llm-1.2.1-r2 is r1 with its distribution list moved out to the
environment manifest; r1 was never published to main, and installs set
up against it on development machines are removed and set up again. The same
holds for r2: tensorrt-llm-1.3.0rc29-r1 replaced it before either reached
main, and an engine installed from r2 is removed and set up again (there
is no update operation yet). tensorrt-llm-1.3.0rc29-r2 is rc29-r1 without
its two dense Nemotron-H checkpoints (NVIDIA-Nemotron-3-Nano-4B-FP8 and
-BF16): in the Windows live acceptance (2026-10-02) trtllm-serve 1.3.0rc29
failed to load Nemotron-3-Nano-4B-FP8 with KeyError: '-'. The image bundles
transformers 5.5.4, whose NemotronHConfig maps hybrid_override_pattern
through {"M": "mamba", "E": "moe", "*": "attention"} only, so any checkpoint
with dense MLP layers (-) fails before TensorRT-LLM's own model code, which
does handle -, is reached. Mamba/MoE checkpoints (M, E, *) and those
that already ship layers_block_type are not affected, so
NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4 stays listed. The NemotronH
architectures stay listed; the dense checkpoints come back once an image's
transformers parses -.
tensorrt-llm-1.3.0rc29-r3 is rc29-r2 with minimum_driver_version
lowered from 615.65.02 to 615.0, the start of the R615 branch. 615.65.02
is the image's CUDA_DRIVER_VERSION label — the driver the CUDA 13.4.1 build
was made with, not a requirement: CUDA 13.4's release notes map the toolkit to
a driver branch (R615), and every R615 driver runs CUDA 13.4. The patch-level
floor blocked the first NVIDIA Windows on Arm machines (2026-10-06), whose
Windows driver 616 hands WSL the R615 libraries 615.41.
A descriptor_id has the form <engine_id>-<engine version>-r<n>:
- the engine version is numbers separated by dots, with an optional
pre-release suffix
a<k>,b<k>orrc<k>(1.3.0rc29,0.31.0); nis the edition of that engine release in conf, starting at1.
runtimes/schema.json checks the shape with a pattern. The integrity
check in CI adds what the schema cannot see: the id starts with this
descriptor's own engine_id, and what follows <engine_id>- is exactly
<engine version>-r<n>. So vllm-latest and a tensorrt-llm-… id in
vllm.json both fail make validate and CI.
A new descriptor of an engine MUST have a strictly greater
descriptor_id than the one it replaces: a newer engine version, or the
same version with a greater n (vllm-0.31.0-r1 → vllm-0.31.0-r2 for a
new curated list on the same image). atomic-chat-core decides whether to
offer an installed engine an update by this order, comparing the installed
descriptor_id with the one on main:
- the version's numeric parts, left to right;
- a pre-release is older than the same version without a suffix
(
1.3.0rc29<1.3.0), and pre-releases ordera<b<rc, then byk; - for an equal version, by
n.
An id that does not parse, or belongs to another engine, is never newer. So
publishing an older or equal id is not offered to installed engines at all,
and rolling a descriptor back does not make every installation "update"
backwards. CI does not compare an id with the one it replaces; keeping it
greater is the maintainer's job. The order is specified in the
engine-lifecycle capability of atomic-chat-spec
(openspec/specs/engine-lifecycle/spec.md,
requirement "Порядок дескрипторов managed-движка"), and core implements it.
An installation records the descriptor_id it was set up with and keeps
using it. Publishing a new descriptor here therefore only affects new
installs and never changes, re-downloads or breaks an existing one.
A core release of change unify-engine-lifecycle and later also reports
that main holds a descriptor newer than the installed one (by the order
above), and updates the engine only when a client asks it to. The update is a
reinstall: core removes the installation and keeps the models, then starts
setup with the new descriptor, which waits for the user's consent. Core never
starts it by itself. Older cores offer nothing: the user removes the engine
and sets it up again, which picks up whatever descriptor is current then.
The steps below are written for TensorRT-LLM; vLLM follows the same steps
with its own sources (the vLLM source at the image's VLLM_BUILD_COMMIT, see
vLLM descriptor), and so does SGLang (the SGLang
source at the image's SGLANG_BUILD_COMMIT, see SGLang
descriptor).
- Confirm the candidate tag is the latest non-rc release with the
platform/hardware support you need — check NVIDIA's own release notes and
hardware-support docs at that tag, not just the tag list. Exception, by
owner decision of 2026-10-02: the
tensorrt-llm-1.3.0rc29-*descriptors pin the pre-release1.3.0rc29, because the model families the Hub offers (Qwen3.5 and later, Gemma 4, Nemotron 3.5) do not load on 1.2.1 and 1.3.0 had no final release yet. The next descriptor moves to the1.3.0final release once NVIDIA publishes it; it does not move to a later rc. - Get the per-platform manifest digest for both the engine image and the probe image (see Reproducing runtime descriptor digests below) — never a multi-arch index digest.
- Re-derive
supported_architectures,quantization(including every format'sexcluded_compute_capabilities),model_familiesandminimum_compute_capabilityfrom that tag's own source (its parser registries, its hardware-support matrix), rather than carrying over the previous descriptor's values. Re-deriveminimum_driver_versionas the first version of the driver branch that the probe image's own CUDA version needs (from itsNVIDIA_REQUIRE_CUDAconstraint and that CUDA Toolkit version's release notes, "CUDA Toolkit and Corresponding Driver Branch": CUDA 13.4 → R615 →615.0). The engine image'sCUDA_DRIVER_VERSIONlabel is the driver its CUDA build was made with, not a floor; since CUDA 13.4 the toolkit no longer bundles a driver. - Re-derive
curated_models: re-check each repo is still ungated, re-resolverevisionto the commit itsmainbranch currently points at, and recomputeinventory_digest(below). - Recompute
download_bytesandrequired_disk_bytesfrom the new image's registry manifests (below). - Update
noticesif the image's license terms changed, andexclusionsif the release's support gaps changed. - Assign a new
descriptor_id,<engine_id>-<new version>-r1, strictly greater than the current one (see form and order). - Run
make validatebefore opening a PR — it runs the schema and every integrity check below against what you just wrote.
-
The descriptor has no
$schemakey, unlike the other manifests in this repository. atomic-chat-core's ported parser rejects every unknown top-level key, and$schemais not otherwise part of the descriptor's data — adding it would only be an editor affordance, at the cost of core refusing every descriptor that carries it.runtimes/schema.jsondoes not list$schemaamong the allowed top-level properties, soajv --strictrejects it too (see theinvalid-schema-field.jsonfixture). -
image/probe_imagedigests are the platform-specific manifest digest, not the multi-arch index digest — sodocker pull repo@digestfetches exactly the bytes for that platform, and core can compare what it actually pulled against what the descriptor promised. Pulling by the index digest would let the registry hand back either platform. -
minimum_driver_versionis the lowest NVIDIA display driver version theimageandprobe_imagerun on. Core checks it in the probe, before the user has consented to anything: a host below it getsprerequisite-blockedwith both the required and the actual driver version, and no Docker install or image pull is offered (design D16). Core reads the host's driver version fromnvidia-smi --query-gpu=driver_version, splits both that value and this field on., parses each component as a base-10 integer, pads whichever of the two has fewer components with zeros, and compares them as integer tuples; the host is blocked iff its tuple is lower than this field's. On Windows core compares the version of the NVIDIA libraries Windows hands WSL (/usr/lib/wsl/lib, Linux numbering: Windows driver 616 →615.41), not the Windows driver number. The value itself is the first version of the driver branch theprobe_image's own CUDA version needs, read from that image'sNVIDIA_REQUIRE_CUDAconstraint and that CUDA Toolkit version's release notes ("CUDA Toolkit and Corresponding Driver Branch": CUDA 13.4 → R615 →615.0). It is not the engine image'sCUDA_DRIVER_VERSIONlabel: that is the driver its CUDA build was made with, and a patch-level floor from it blocks drivers of the same branch that run the image. This is the non-datacenter (GeForce/consumer) floor, sinceNVIDIA_REQUIRE_CUDA's own brand exceptions only relax it for datacenter/vGPU brands. This is deliberately stricter than some hosts need:probe_image's ownNVIDIA_REQUIRE_CUDAcarries CUDA-minor-version-compatibility exceptions that let specific datacenter/vGPU card brands (Tesla, Quadro, GRID, vGPU profiles, …) run on several driver branches older than this floor.minimum_driver_versionis one number, not a brand-conditional table, so it also blocks those datacenter hosts on an older driver that forward compatibility would otherwise have let through — a deliberate simplification favoring one clear blocker message over modeling every brand exception. To update it for a new engine tag: read the new probe image's CUDA version (NVIDIA_REQUIRE_CUDA), find its driver branch in that CUDA Toolkit version's release notes, and write the branch's first version (<branch>.0). -
quantization[].excluded_compute_capabilitieslists compute capabilities where this engine release does not support the format, even though the capability is numerically above the format's ownmin_compute_capability— because the engine's hardware support matrix is not monotone in compute capability (see thequantization[].formatbullet below): a newer architecture can lack a format that an older one has. Together withmin_compute_capability, this field fully encodes the tag's matrix for that format: a card is compatible with the format iff its compute capability is>= min_compute_capabilityand not in this list. The list is a deny-list, not an allow-list, so a compute capability the tag's matrix simply has no row for counts as supported once it clears the minimum — unless the controller has an independent reason to infer an exclusion anyway.12.1(sm121, NVIDIA DGX Spark) is one such case: TensorRT-LLM 1.2.1's release notes say it added sm121 support, but its hardware-support matrix has no sm121 row to read a verdict from, and sm121 is a consumer Blackwell part in the same family as sm120 (12.0) — sow4a16_awq,w4a8_awq,fp8_block_scalesandfp8_per_channel_per_token, which all already deny sm120, also list12.1here even though the matrix never names it. Core's model-compatibility check treats a match here asMODEL_INCOMPATIBLEat check time, distinct from (and in addition to) the plain minimum-CC check (design D17). Empty when the matrix shows no such gap for that format. To update it for a new engine tag: re-read that tag's hardware support matrix and, for every format, list every row above itsmin_compute_capabilitywhere the matrix does not mark the format supported — the integrity check (below) then enforces that every entry here is strictly above that format's own minimum. -
curated_models[].vram_tier_bytesis the tier's nominal size in decimal GB (× 10^9), not binary GiB. Real cards report a little under their nominal binary size (an RTX 4090 reports 24,564 MiB; an H100 reports 81,559 MiB) but still above the decimal-GB figure, so the decimal value works as a safe floor for "does this model fit the tier" without overshooting the VRAM any card in that tier actually has. On unified-memory systems (NVIDIA GB10 / DGX Spark)nvidia-smireports no dedicated card memory at all, so there the tier is instead compared against the host'sMemAvailable(design D13). -
quantization[].formatnames follow one fixed checkpoint-metadata → format-name rule, shared by every engine and documented here as the conf↔core contract (atomic-chat-core implements it once, for all managed engines). A name says how the weights are encoded on disk, not just their arithmetic: checkpoints that loaders read differently get different names even when the bit widths match (ModelOptw4a16_awq≠ AutoAWQautoawq_w4a16; ModelOptfp8≠ Hugging Facehf_fp8≠ block-scaledfp8_block_scales). The rule only names a checkpoint; whether an engine loads it is decided by that engine's descriptor: an engine loads a format iff its pinned descriptor has aquantizationrow with that name. A checkpoint the rule does not recognize is rejected by every engine as unsupported (naming itsquant_methodwhen there is one) — it never falls through to the unquantized step 4.The inputs are the checkpoint's
config.jsoncontent, and — when the checkpoint carries the file — itshf_quant_config.jsoncontent: a checkpoint can have noquantization_configinconfig.jsonat all and still be quantized (e.g.nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8andnvidia/Llama-3.3-70B-Instruct-NVFP4both classify entirely fromhf_quant_config.json), sodtype/torch_dtypemust never be trusted beforehf_quant_config.jsonhas been checked.quant_methodand the string values below are compared lower-cased. Apply these steps in order, stopping at the first that matches:- If
hf_quant_config.jsonis present (NVIDIA ModelOpt), the format is itsquantization.quant_algolower-cased, withfp8_pb_worenamed tofp8_block_scales(matching what TensorRT-LLM itself calls it internally). ModelOpt names therefore includefp8,fp8_per_channel_per_token,fp8_block_scales,nvfp4,w4a16_nvfp4,mxfp8,w4a16_awqandw4a8_awq. - Otherwise, if
config.json'squantization_config.quant_methodis set:modelopt→ the format isquantization_config.quant_algolower-cased, with the samefp8_pb_wo→fp8_block_scalesrename as step 1.fp8withquantization_config.weight_block_sizeequal to[128,128]→fp8_block_scales.fp8withoutweight_block_size(absent ornull) →hf_fp8: the Hugging Face / AutoFP8 encoding with per-tensor or per-channel scales.fp8with any other block size is not recognized.mxfp4→mxfp4.awq(AutoAWQ) withbits(orw_bit) equal to 4 andversionabsent orgemm→autoawq_w4a16. Any other bit width, or another packingversion(gemv,gemv_fast,exllama,marlin, …), is not recognized: the packed bytes on disk differ.gptqwithbits4 or 8,sym: true, andcheckpoint_formatabsent orgptq→gptq_w4a16orgptq_w8a16. Other bit widths, asymmetric quantization (sym: false) and other checkpoint formats (gptq_v2,marlin) are not recognized.compressed-tensors→ named by its scheme (below).bitsandbytesis deliberately not recognized: engines load it slowly and only partially, so it is not offered at all.- anything else is not recognized.
- Otherwise, if
config.jsonhas a top-levelquantizationobject (the MLX convention:bits,group_size, e.g.prism-ml/Bonsai-27B-mlx-1bit), the checkpoint is not recognized: its weights are MLX-packed while itsdtypestill names the unquantized model, so it must not fall through to step 4 and be reported asbf16/fp16. - Otherwise the checkpoint is unquantized: read
dtype— the field TensorRT-LLM itself reads (model_config.py:471) — falling back to the legacytorch_dtypekey only whendtypeis absent, and then totext_config.dtype/text_config.torch_dtype(a VLM-style config such as Qwen3.5's declares its dtype only there, and TensorRT-LLM 1.3 falls back the same way).bfloat16→bf16;float16→fp16; anything else, includingfloat32or a missing/unrecognized value, is not recognized.
A compressed-tensors checkpoint (llm-compressor) is named by its
quantization_config.config_groups. Each group is classified by itsweights(type,num_bits) andinput_activations(absent ornullmeans weight-only):weightsinput_activationsformat int, 4 bitsnone ct_w4a16int, 8 bitsnone ct_w8a16float, 8 bitsfloat, 8 bitsct_w8a8_fp8int, 8 bitsint, 8 bitsct_w8a8_int8float, 4 bits,group_size16float, 4 bitsct_nvfp4Every group must give the same name, and that name is the format. A group that matches no row, groups that give different names, no groups at all, or a
sparsity_configwhoseformatis anything butdense(an empty{}ornullmeans no sparsity) make the checkpoint not recognized.The rule never changes a TensorRT-LLM verdict. Every name added for vLLM (
hf_fp8,autoawq_w4a16,gptq_w4a16,gptq_w8a16, the fivect_*names) names a checkpoint that the rule used to call "not loadable", and notensorrt-llmdescriptor has a row for any of them — so for every checkpoint, every published TensorRT-LLM descriptor gives the sameokorMODEL_INCOMPATIBLEas before; only the reason text can change (it now names the format). atomic-chat-core proves this with a verdict test over its TensorRT-LLM checkpoint corpus. Already-released cores are unaffected: they read onlytensorrt-llm.json, which carries none of the new names. The same constraint binds every future edit: a new name may only be given to a checkpoint the rule did not recognize before; renaming or reclassifying a checkpoint that already has a name changes the verdict of published descriptors and is not allowed.A format of
mixed_precision(ModelOptquant_algo: MIXED_PRECISION, e.g.nvidia/Qwen3.8-27B-NVFP4) is never a row of its own. Itshf_quant_config.jsonlists aquant_algoper layer inquantization.quantized_layers; each distinct per-layer value is named by step 1's rule (FP8→fp8,NVFP4→nvfp4,W4A16_NVFP4→w4a16_nvfp4, …), every one of those names must have aquantizationrow, and a card must clear all of them: the highestmin_compute_capabilityand every listed exclusion. A mixed checkpoint whose layers name a format without a row, or that names none, is not loadable.w4a16_nvfp4has no row in NVIDIA's hardware-support matrix at1.3.0rc29; its row copiesnvfp4(10.0, no exclusions) as the conservative choice, although the engine also has a Marlin path for it on 8.9–9.x and 12.x that nobody has run here yet.Each format also carries exactly one
min_compute_capabilityand its ownexcluded_compute_capabilities(above) — together the two fields are the complete compatibility rule for that format, not merely a conservative floor: the engine's real hardware-support matrix is not monotone in compute capability (a format can be marked supported on a newer architecture while unlisted on one immediately below it), andexcluded_compute_capabilitiesis exactly the set of gaps thatmin_compute_capabilityalone would miss. Core's check rejects an incompatible checkpoint for either reason at check time, so no format's matrix gap can let a checkpoint through to a load that then fails on that specific card. The descriptor's overallminimum_compute_capabilityis always a lower bound on every format's own minimum (enforced by CI, see below). - If
-
curated_models[].inventory_digestis computed with the same algorithm as atomic-chat-core, over every file in the Hugging Face repository at the pinnedrevision— not a filtered subset; an engine's own file-type selection happens later and is not part of a checkpoint's identity. The file list itself comes from the Hugging Face API endpointhttps://huggingface.co/api/models/<owner/name>/revision/<sha>?blobs=true&files_metadata=true, read for every file in the response, not only weights: each file's path is itsrfilename; its byte size islfs.sizewhen the file has anlfsblock, else its plainsize; its published hash islfs.sha256when present, else an empty string (a non-LFS file has no published hash). Files are then sorted by path; for each file the digest folds in${path.length}:${path}, then|${bytes}|, then the published hash (or empty string), then a NUL byte; the result issha256:<hex of the running digest>..github/scripts/inventory-digest.mjsreproduces this from the live Hugging Face API (see below). Which consumer recomputes and compares this digest (atomic-chat-core, the app, or the CLI) is for the plan to name — that is not decided here. -
download_bytes/required_disk_bytesare estimated from the image's own registry manifests:download_bytessums the compressed layer sizes (the larger of the two platforms);required_disk_bytesadds the estimated extracted size, measured by sampling each large layer's compression ratio (a capped-prefixgzip -dc) and weighting by layer size, rounded up to the next GiB.
Not live-qualified. Every value comes from the image's registry manifests,
the TensorRT-LLM source at tag v1.3.0rc29 and the Hugging Face API on
2026-10-02, and core's own algorithm reproduces every curated
inventory_digest; nothing has run on a card yet. What changed from
tensorrt-llm-1.2.1-r2:
- Driver: the image is CUDA 13.4 (
CUDA_DRIVER_VERSIONlabel 615.65.02), and CUDA 13.4 needs the R615 branch on consumer cards, sominimum_driver_versionis615.0(sincerc29-r3;r1andr2carried the label's615.65.02). Hosts on R580–R610 are blocked at the probe until they update the driver. - Architectures: re-derived from
_arch_index.py. The vision-language architectures whose text path serves chat are listed for the families the curated list carries (Qwen3.5/3.6/3.8, Gemma 4, Gemma 3, Mistral 3, Qwen4Exp); they run text-only.NemotronNASForCausalLMis gone (it was a class name, never a registered key;DeciLMForCausalLMis the key), andDeepseekV4ForCausalLMis left out because it needs sm100+ and the descriptor has no per-architecture capability. - Curated models: a new list of 15 across the 8–80 GB tiers, including three mixed-precision NVIDIA checkpoints. Mistral and gpt-oss repositories ship a second copy of their weights and are left out, since the client downloads every file of a curated repository.
- Telemetry:
trtllm-serve1.3 reports anonymous usage to NVIDIA by default; core 0.7.6 turns it off withTRTLLM_NO_USAGE_STATS=1.
tensorrt-llm-1.2.1-r1 was checked against atomic-chat-core's live tests on
2026-09-29, and nothing in it changed as a result. The rule: a curated model
leaves the list only if it actually failed on a card it fits, a distribution
or architecture leaves the install list only if it failed the install test,
and required_disk_bytes changes only if measured post-pull usage differs by
more than 10%. None of these happened. The results carry over unchanged:
tensorrt-llm-1.2.1-r2 has the same image, models and sizes, and the
environment manifest linux-r1 has the same distribution list.
- Install (core task 2.18,
test/live/managed-install.test.ts) — clean VMs with an RTX 4070 Laptop (CC 8.9) passed through. All seven x86_64 versions passed: Ubuntu 22.04, 24.04, 26.04; Debian 12, 13; Fedora 43, 44 (with SELinux enforcing). Hosts that already ran Docker were covered on Ubuntu 24.04 and Fedora 44 (restart only after consent), and Fedora 44 withmoby-enginegot a toolkit-only plan. The Arch adopt path was not run. Ubuntu 26.04 needed five runs: earlier runs failed onnvcr.io403s and once ondocker.servicestart, then every step passed. aarch64 was not tested (no arm64 host with an NVIDIA card); its entries stay because nothing failed, not because they passed. - Engine (core task 2.19,
test/live/tensorrt-llm.test.ts) — one card only (Ada, 8 GB):Qwen/Qwen3-1.7Bat the pinned revision loaded, streamed, reloaded faster from the engine cache, made a tool call through theqwen3parser and returned structured output (8 passed, 2 skipped). The other ten curated entries, FP8 and NVFP4, and Ampere/Hopper/Blackwell/GB10 cards were not run; they stay in the list because none of them failed. - Sizes — the pulled engine image was 20.88–20.90 GB on every VM, within
1.2% of
download_bytes(the difference is the probe image and layers already present). Disk space actually used after the pull was not measured, sorequired_disk_byteskeeps its estimate.
The logs live in atomic-chat-core's checkout of branch
change/add-tensorrt-llm-linux, under .superpowers/sdd/tasks/live-results/
(vm-campaign/*, managed-install-ubuntu-26.04-x86_64-run*.log,
tensorrt-llm-run2.log).
vllm-0.31.0-r1 pins the vLLM project's own image
docker.io/vllm/vllm-openai:v0.31.0 (build commit
db9527a46873454610df6dbedf79a36d6bf1a7f6, the v0.31.0 tag) for
linux/amd64 and linux/arm64, and the CUDA 13.0 base image
nvcr.io/nvidia/cuda:13.0.2-base-ubuntu24.04 for the GPU check. Not
live-qualified yet: every value below comes from the registry manifests,
the vLLM source at that commit and the Hugging Face API on 2026-10-06. The
live acceptance on an RTX 4070 Laptop (compute capability 8.9, 8 GB) under
Ubuntu and Windows, run by the maintainers of change add-vllm-runtime
with atomic-chat-core's live tests, confirms or corrects the driver floor,
the matrix rows that run on 8.9, the curated list and the memory overheads
before the file reaches main; its findings are recorded in that change's
rulings/.
- Why not the
-cu129variant. The first descriptor,vllm-0.31.0-cu129-r1, pinnedv0.31.0-cu129for its lower driver floor (R575). That image cannot start: next totorch 2.13.0+cu129it shipstorchcodec 0.17.0, built for CUDA 13, whoselibtorchcodec_image.soneedslibnvrtc.so.13; the image has onlylibnvrtc.so.12. Thevllmcommand importstorchcodecon start and does not catch thatOSError, so every model fails with "vLLM exited with code 1 before it was ready" (Windows acceptance, 2026-10-06; a barepython3 -c "import torchcodec"in the image fails the same way, without a GPU or any of core's flags). vLLM requirestorchcodec >= 0.14with no upper bound, so the-cu129build picks up whatever CUDA 13 wheel is current. The default tag is CUDA 13.0 throughout.vllm-0.31.0-cu129-r1never reachedmain; an engine installed from it on a development machine is removed and set up again. The cost is the driver floor: R580 instead of R575, still well below TensorRT-LLM's R615, which is what keeps it off many desktops and why vLLM is added. NGC'snvcr.io/nvidia/vllmis not used: newer CUDA (higher floor), later than upstream, and NGC terms on top. minimum_driver_version580.0. The image'sNVIDIA_REQUIRE_CUDAiscuda>=13.0(CUDA_VERSION13.0.2), and CUDA 13.0 needs the R580 branch on consumer cards, so the floor is that branch's first version, by the same rule as TensorRT-LLM (seeminimum_driver_versionabove). The image's datacenter brand exceptions (535, 550, 565, 570 and 575 branches) are not modelled. The probe image is CUDA 13.0 as well, so the GPU check does not raise the floor.minimum_compute_capability8.0(Ampere), the same as TensorRT-LLM. The amd64 image also carries Turing (7.5) kernels, but no Turing card is available to check it, and a floor is not lowered without a live run.quantization. vLLM's documented hardware table stops at Hopper and has no rows for NVFP4, MXFP4 or ModelOpt, so the matrix is read from the code instead: each quantization method'sget_min_capability()at the build commit, the gate vLLM itself applies at load. Every format the shared rule recognizes and vLLM loads has a gate at or below 8.0 — where a card lacks native FP8 or FP4 tensor cores, vLLM falls back to Marlin weight-only kernels (FP8, NVFP4, MXFP4) or, for compressed-tensors FP8, to W8A16 — so every row is8.0with no exclusions. Not listed: ModelOptw4a16_awqandw4a8_awq(vLLM's ModelOpt loader does not accept them), GPTQ other than 4/8-bit symmetric and AutoAWQ other than 4-bit (vLLM 0.31 refuses them), and bitsandbytes and GGUF. Only the rows that run on 8.9 are checked live (by the acceptance above). The rows that need native support on newer cards to run fast — FP8 with block scales on Hopper, NVFP4 and MXFP4 on Blackwell — and every row on 8.0/8.6, 9.0, 10.x and 12.x come from the code alone. A row that turns out wrong fails at load with the engine's own error and logs, and is fixed by a newdescriptor_idwithout a core release.supported_architectures. Every architecture of the TensorRT-LLM descriptor, all of which vLLM 0.31 serves (HunYuan, Starcoder2 and EXAONE MoE through its Transformers backend; EXAONE MoE under vLLM's and Hugging Face's spellingExaoneMoeForCausalLM), plus six text families common on small cards that TensorRT-LLM lacks:Gemma2ForCausalLM,GraniteForCausalLM,GraniteMoeHybridForCausalLM(Granite 4),Ernie4_5ForCausalLM,Ernie4_5_MoeForCausalLMandLfm2ForCausalLM. Vision-language classes run text-only.model_families. Parser names are vLLM's own registry names at the build commit (vllm/tool_parsers/__init__.py,vllm/reasoning/__init__.py), chosen per family from vLLM's tool-calling and reasoning docs and the model cards'vllm serveflags. A family gets a parser only when it works with the checkpoint's own chat template: the adapter passes no--chat-template, so families whose vLLM recipe requires one (Llama 3.x, DeepSeek V3/V3.1, Mistral in the Transformers format, Granite 3.0) have none, and so do families with more than one reasoning mode where a wrong reasoning parser would swallow the answer (EXAONE, Trinity, ERNIE). Cohere Command's parsers need thecohere_melodypackage, which only vLLM's test requirements install, not the image. These names differ from TensorRT-LLM's for the same family (Qwen3:hermes, notqwen3; Qwen3.5:qwen3_coderandqwen3, notqwen3andqwen3_5) — the descriptor of each engine names its own registry.curated_models. First the thirteen TensorRT-LLM models at the same revisions, so one copy on disk serves both engines (their tiers are those of TensorRT-LLM, exceptQwen3.6-35B-A3B-FP8, which vLLM also runs below Hopper and so drops to the 48 GB tier); then 4-bit checkpoints that TensorRT-LLM cannot load, for 8 and 12 GB cards:Qwen/Qwen3-4B-AWQ(AutoAWQ),cyankiwi/Qwen3.5-4B-AWQ-4bit(compressed-tensors W4A16, a community quantization: Qwen publishes no 4-bit Qwen3.5 below 27B) andQwen/Qwen3-8B-AWQ. Google's owngemma-4-*-qat-w4a16-ctcheckpoints are left out: their unquantized embeddings and encoders keep even E2B at 8.3 GB.download_bytesis the larger platform's compressed layers (arm64, 10.1 GB);required_disk_bytesadds the extracted size sampled the same way as for TensorRT-LLM, 28 GiB.- Privacy. core starts the container with vLLM's usage statistics off
(
VLLM_NO_USAGE_STATS=1,DO_NOT_TRACK=1) and Hugging Face offline: the image itself reports usage tostats.vllm.aiby default (VLLM_USAGE_SOURCE=production-docker-image). minimum_core_version0.9.9,minimum_app_version2.2.0are provisional:0.9.9is the version core's change branch starts from, so a development core accepts the file throughATOMIC_RUNTIME_DESCRIPTOR_URL_VLLM; both are set to the actual core and app releases that ship vLLM before the file is merged intomain.
sglang-0.5.21-r1 pins the SGLang project's own image
docker.io/lmsysorg/sglang:v0.5.21 (build commit
e00930c5489053f26d86b179cee0d087f846acbb, the v0.5.21 tag, recorded in
the image as SGLANG_BUILD_COMMIT) for linux/amd64 and linux/arm64, and
the same CUDA 13.0 base image as vLLM,
nvcr.io/nvidia/cuda:13.0.2-base-ubuntu24.04, for the GPU check. Not
live-qualified yet: every value below comes from the registry manifests,
the SGLang source at that commit and the Hugging Face API on 2026-10-13. The
live acceptance on an RTX 4070 Laptop (compute capability 8.9, 8 GB) under
Ubuntu and Windows, run by the maintainers of change add-sglang-runtime
with atomic-chat-core's live tests, confirms or corrects the driver floor,
the matrix rows that run on 8.9, the curated list and the parser names
before the file reaches main; its findings are recorded in that change's
rulings/.
-
Why the release tag. A descriptor is immutable, so it pins a release tag. SGLang also publishes
devand nightly tags, which are rebuilt in place, and day-0 tags for single new models, which are not releases. The CUDA 12 line of images ended after v0.5.19, sov0.5.21exists only as a CUDA 13 build. NGC'snvcr.io/nvidia/sglangis not used for the same reasons as NGC's vLLM: it trails upstream and adds NGC terms. -
minimum_driver_version580.0. The image'sCUDA_VERSIONis13.0.3and itsNVIDIA_REQUIRE_CUDAiscuda>=13.0; CUDA 13.0 needs the R580 branch on consumer cards, so the floor is that branch's first version, the same rule and the same value as vLLM. The image's datacenter brand exceptions (535 to 575 branches) are not modelled, and the probe image is CUDA 13.0 as well. -
minimum_compute_capability8.0(Ampere), as for vLLM and TensorRT-LLM: no older card is available to check, and a floor is not lowered without a live run. -
quantization. The matrix is read from the code, like vLLM's: for each name of the shared rule, the quantization config SGLang dispatches the checkpoint to (python/sglang/srt/configs/model_config.py, ModelOpt through_parse_modelopt_quant_config) and that config'sget_min_capability(), the gate SGLang's loader applies before loading (model_loader/loader.py). Whoever moves the descriptor to a new SGLang release re-reads both at the new image'sSGLANG_BUILD_COMMIT; the live acceptance then checks the rows it runs on 8.9. Where the result differs from vLLM:fp8(ModelOpt FP8) is8.9:ModelOptFp8Configgates at 89, while vLLM runs it through Marlin from 8.0. Core requires every per-layer format of a mixed-precision checkpoint, so the ModelOpt mixed checkpoints with FP8 layers (nvidia/Qwen3.8-27B-NVFP4,nvidia/Qwen3.6-35B-A3B-NVFP4, the Nemotron 3.5 Lightning NVFP4) need 8.9 here too, although SGLang's own mixed-precision config gates at 8.0. That blocks them on Ampere, where they might run; the opposite choice,8.0, would pass plain ModelOpt FP8 checkpoints that SGLang then refuses at load.mxfp8is10.0: SGLang reads ModelOpt MXFP8 with its ownmxfp8method, which gates at 100 on CUDA.ct_nvfp4is10.0: compressed-tensors W4A4 NVFP4 has no fallback below Blackwell, SGLang raises instead.fp8_per_channel_per_tokenhas no row: SGLang's ModelOpt dispatch has no branch for thatquant_algo. Neither does it dispatch a checkpoint whose top-levelquant_algoisFP8_PB_WO; thefp8_block_scalesrow (8.0) is there for Hugging Face FP8 with 128x128 block scales (Fp8Config) and for block-FP8 layers inside a ModelOpt mixed checkpoint. A plain ModelOptFP8_PB_WOcheckpoint therefore passes the check and fails at load with the engine's own error; none is curated.- Every other row is
8.0with no exclusions:Fp8Config(hf_fp8,fp8_block_scales) and ModelOpt NVFP4 (nvfp4,w4a16_nvfp4, and the mixed config) gate at 80 and fall back to Marlin weight-only kernels where the card lacks native FP8 or FP4;mxfp4, AWQ Marlin (autoawq_w4a16), GPTQ Marlin (gptq_w4a16,gptq_w8a16) and the compressed-tensors W4A16/W8A16, W8A8 INT8 and W8A8 FP8 schemes gate at 80 (W8A8 FP8 below 8.9 falls back to W8A16). - Not listed, as for vLLM: ModelOpt
w4a16_awqandw4a8_awq(not dispatched), bitsandbytes and GGUF.
Rows not checked live on 8.9. The acceptance runs
bf16(Qwen3.5-2B) and one 4-bit curated model (autoawq_w4a16orct_w4a16).fp16,fp8,fp8_block_scales,nvfp4,w4a16_nvfp4,hf_fp8,mxfp4,gptq_w4a16,gptq_w8a16,ct_w8a16,ct_w8a8_fp8,ct_w8a8_int8and whichever 4-bit row it does not run come from the code alone on 8.9, and so does every row on 8.0/8.6, 9.0, 10.x and 12.x (mxfp8andct_nvfp4do not run on 8.9 at all). A row that turns out wrong fails at load with the engine's own error and logs, and is fixed by a newdescriptor_idwithout a core release. -
supported_architectures. The 45 architectures ofvllm.jsonthat SGLang 0.5.21 implements natively: theEntryClassnames underpython/sglang/srt/models/, which SGLang's registry matches exactly againstconfig.json. Five vLLM architectures are left out because SGLang has no native class under the Hugging Face name:Ernie4_5ForCausalLM(SGLang registersErnie4_5_ForCausalLM),ExaoneMoeForCausalLM(SGLang:ExaoneMoEForCausalLM),NemotronForCausalLM,Qwen4ExpForCausalLM(SGLang has onlyQwen4ExpForConditionalGeneration) andSeedOssForCausalLM. SGLang would try those through its generic Transformers backend, which is not what this descriptor qualifies. Vision-language classes run text-only. SGLang 0.5.21 has a text-only switch,--language-model-only: with it the Qwen3.5 and Qwen4Exp classes never build or load their encoders, and every class serves with multimodal off, so SGLang reserves no memory for images and refuses them. The Gemma 3/4 and Mistral 3 classes ignore the switch for loading and still load their encoders (not checked live: no Gemma or Mistral model fits the 8 GB acceptance card). Which flag core passes is core's adapter decision (changeadd-sglang-runtime,rulings/core.md). -
model_families. Parser names are SGLang's own registry names at the build commit (python/sglang/srt/function_call/parser_names.py,python/sglang/srt/parser/reasoning_parser_names.py), chosen per family from the launch commands in SGLang's cookbook and SGLang's chat-template auto-detection (parser/template_detection.py). The descriptor never namesauto: core declares tools and reasoning from these names, so they are data, not a guess at start. The rule is vLLM's: a family gets a parser only when it works with the checkpoint's own chat template (the adapter passes no--chat-template) and its reasoning mode is unambiguous. Where the names differ from vLLM's:- Qwen2 and Qwen3 (
Qwen2*,Qwen3ForCausalLM,Qwen3Moe*,Qwen3Next*): tool parserqwen, SGLang's name for the Qwen 2.5/3<tool_call>JSON format; Qwen3.5 and later keepqwen3_coderandqwen3. - Granite 4 (
GraniteMoeHybridForCausalLM) and EXAONE 4:hermes; their templates emit the same<tool_call>JSON format, and SGLang has no Granite parser. - Trinity (
AfmoeForCausalLM):trinity, SGLang's parser for it, which also reads tool calls written inside the reasoning. - MiniMax-M2:
minimax-m2and reasoningminimax, the parser SGLang's auto-detection picks for that architecture. The cookbook'sminimax-append-thinkleaves the reasoning in the answer text. - Nemotron-H:
qwen3_coderandnemotron_3. - None where SGLang has no parser for the family's format: ERNIE 4.5,
Granite 3 (
<|tool_call|>), HunYuan A13B (SGLang'shunyuanparsers are for the Hunyuan 3 format). - None where one architecture spans checkpoints with different formats or
needs its own template, as for vLLM: Llama, DeepSeek V3/V3.2 (also
Kimi K2 and DeepSeek V3.1), every Mistral class, Cohere 2 (SGLang's
cohere_command4targets Command 4 and is unchecked on Command A and R7B), HunYuan dense. GLM-4.5/4.6 getglm45, but GLM-4.7 sharesGlm4MoeForCausalLMand uses theglm47format: the same compromise as vLLM.
structured_outputistruefor every family: SGLang 0.5.21 constrains output with xgrammar for any model. - Qwen2 and Qwen3 (
-
curated_models. All sixteen models ofvllm.jsonat the same revisions and inventory digests, so one copy on disk serves both engines; every one passes SGLang's architecture list and matrix, and the tiers and notes are vLLM's, except that the notes of the three mixed NVFP4 + FP8 checkpoints say their FP8 layers need compute capability 8.9 here. The live acceptance runs Qwen3.5-2B and one 4-bit model on 8 GB; a model it rejects is removed before the merge, without a newdescriptor_id. -
download_bytesis the larger platform's compressed layers (amd64, 15.2 GB);required_disk_bytesadds the extracted size sampled the same way as for TensorRT-LLM, 48 GiB (about 36 GB extracted). -
Privacy. SGLang 0.5.21 reports no usage statistics, and its OpenTelemetry tracing stays off unless it is started with
--enable-trace. core starts the container with Hugging Face offline andDO_NOT_TRACK=1regardless. -
minimum_core_version0.13.6,minimum_app_version2.2.4are provisional: they are the versions the core and app change branches start from, so a development core accepts the file throughATOMIC_RUNTIME_DESCRIPTOR_URL_SGLANG; both are set to the actual core and app releases that ship SGLang before the file is merged intomain.
Every descriptor pins each image by its per-platform manifest digest (not
the multi-arch index digest), so docker pull repo@digest gets exactly that
platform. These print the digests from the registry (no Docker
daemon needed); they match the descriptor for as long as NVIDIA does not
repoint the tags:
docker buildx imagetools inspect nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc29
docker buildx imagetools inspect nvcr.io/nvidia/cuda:13.4.1-base-ubuntu24.04
docker buildx imagetools inspect docker.io/vllm/vllm-openai:v0.31.0
docker buildx imagetools inspect nvcr.io/nvidia/cuda:13.0.2-base-ubuntu24.04
docker buildx imagetools inspect docker.io/lmsysorg/sglang:v0.5.21
# Same without Docker: anonymous registry token, then the manifest list.
for ref in nvidia/tensorrt-llm/release:1.3.0rc29 nvidia/cuda:13.4.1-base-ubuntu24.04 nvidia/cuda:13.0.2-base-ubuntu24.04; do
repo=${ref%:*} tag=${ref##*:}
T=$(curl -s "https://nvcr.io/proxy_auth?scope=repository:$repo:pull" | jq -r .token)
curl -s -H "Authorization: Bearer $T" \
-H "Accept: application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.index.v1+json" \
"https://nvcr.io/v2/$repo/manifests/$tag" |
jq -r --arg ref "$ref" '.manifests[] | "\($ref) \(.platform.os)/\(.platform.architecture) \(.digest)"'
done
# Docker Hub (vLLM, SGLang): the token comes from auth.docker.io.
for ref in vllm/vllm-openai:v0.31.0 lmsysorg/sglang:v0.5.21; do
repo=${ref%:*} tag=${ref##*:}
T=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:$repo:pull" | jq -r .token)
curl -s -H "Authorization: Bearer $T" \
-H "Accept: application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.index.v1+json" \
"https://registry-1.docker.io/v2/$repo/manifests/$tag" |
jq -r --arg ref "$ref" '.manifests[] | select(.platform.os != "unknown") | "\($ref) \(.platform.os)/\(.platform.architecture) \(.digest)"'
donelmsysorg/sglang's index also lists two unknown/unknown entries: the
build attestations of the two images, not images to pin, hence the
select. The SGLang source commit the image was built from, and the CUDA
version its driver floor comes from, are in the image config of either
platform:
T=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:lmsysorg/sglang:pull" | jq -r .token)
CFG=$(curl -s -H "Authorization: Bearer $T" -H "Accept: application/vnd.oci.image.manifest.v1+json" \
https://registry-1.docker.io/v2/lmsysorg/sglang/manifests/sha256:2dbe4c7f53230b09aaa8fa41891c13c51d9d2e253f486a70822aaf08783fff75 |
jq -r .config.digest)
curl -sL -H "Authorization: Bearer $T" "https://registry-1.docker.io/v2/lmsysorg/sglang/blobs/$CFG" |
jq -r '.config.Env[] | select(startswith("CUDA_VERSION=") or startswith("SGLANG_BUILD_COMMIT="))'A curated model's revision is the commit main resolved to when it was
curated, and its inventory_digest is computed from the Hugging Face file
list at that commit with the same algorithm as atomic-chat-core:
curl -s https://huggingface.co/api/models/nvidia/Qwen3.8-27B-NVFP4/revision/main | jq -r .sha
node .github/scripts/inventory-digest.mjs nvidia/Qwen3.8-27B-NVFP4 482ca0f3832238542f8f5295dde86b5f22711d80Note for whichever component recomputes this.
inventory_digesthashes all files at the pinned revision (/revision/<sha>), not a.gguf-filtered subset. Whichever consumer recomputes and compares it — atomic-chat-core, the app, or the CLI, to be named by the plan — must hash the full safetensors inventory at that revision the same way, or a curated entry's digest will never match.
An environment manifest describes the foundation every managed engine runs on, apart from any one engine. There is one per platform:
runtimes/environments/linux.json(schemalinux.schema.json) — on which distributions atomic-chat-core may itself install a GPU container runtime (Docker CE + the NVIDIA Container Toolkit).runtimes/environments/windows.json(schemawindows.schema.json) — the Ubuntu rootfs core imports as Atomic Chat's own WSL2 distribution, and the recipe that prepares it; see Windows manifest.
Like a descriptor a manifest carries data only and has no $schema key.
In linux.json a recipes[] entry is a recipe_id naming argv that is
compiled into core (linux.install-container-runtime) plus the distributions
{ id, version_id, arch } that recipe is qualified to run on. No command,
script or argv lives here.
Linux core reads its manifest only to decide whether it can offer to install Docker and the toolkit on this host. A host where Docker with GPU access already works for the current user is accepted on any distribution, with or without a manifest; if no manifest can be fetched or found in core's cache, only the automatic install is blocked.
Each platform has its own manifest file and its own schema (linux.json,
windows.json). core's parsers are strict — an unknown key rejects the
whole document — so a shared file with a section per platform would turn
adding a windows section into a document every already-released Linux core
refuses; a new Linux user without a cached copy would then lose automatic
install until they updated core. With a file per platform, Linux core reads
only linux.json, Windows core only windows.json, and work on one platform
never touches the other's document.
The content published under a given manifest_id never changes, for the same
reason as descriptor_id: core caches an accepted manifest by this id, and an
operation the user consented to keeps using the manifest it was planned with
until it finishes, even if a newer one is published meanwhile. Any change —
including adding a single distribution — ships under a new manifest_id
of the form <platform>-r<N> (linux-r1 → linux-r2, windows-r1 →
windows-r2). CI compares every manifest under runtimes/environments/
against main and fails when the content changed under an id that is
already there.
- Confirm both vendors publish packages for that distro/version/arch:
Docker CE (
download.docker.com) and the NVIDIA Container Toolkit (nvidia.github.io/libnvidia-container). One vendor publishing alone does not qualify it. - Only add the entry once core's live install test has actually passed on that distribution — package availability is a precondition, not proof the recipe works there.
- Append the
{ "id", "version_id", "arch" }entry to the relevantrecipes[].distributionsinruntimes/environments/linux.json. - Bump the
manifest_id(linux-r<N>→linux-r<N+1>). Do not touch the engine descriptor: itsdescriptor_idstays the same. make validate, commit, open a PR.
On Windows, TensorRT-LLM runs in a Linux environment inside WSL2: Atomic Chat's own distribution, which core imports from a pinned Ubuntu rootfs as the signed-in user, and then prepares with the same recipe Linux hosts use — run as root inside the guest, without Windows elevation. The manifest says what to import and which recipe prepares it:
| Field | Meaning |
|---|---|
manifest_id |
windows-r<N>, immutable (see above). An imported environment stays pinned to the id it was imported from. |
platform |
Always windows. |
minimum_core_version |
Lowest core that understands this manifest. |
minimum_windows_build |
Lowest Windows build (third part of the OS version) core offers the environment on. 22000 = the first Windows 11 build; Windows 10 is not supported. |
minimum_wsl_version |
Lowest WSL package version, MAJOR.MINOR.PATCH as wsl --version prints it without the trailing build part. 2.4.4 is the first WSL that handles the .wsl rootfs format. |
rootfs.url |
HTTPS URL of the rootfs image; http:// is rejected by the schema. |
rootfs.sha256 |
Lowercase hex SHA-256 of that file. Core checks it before the file is used for anything. |
rootfs.distribution |
What the rootfs is, { id, version_id, arch } in os-release terms; arch is x86_64 in windows.json; Windows on Arm has its own file, below. |
guest_recipe_id |
Recipe compiled into core that prepares the guest after import (linux.install-container-runtime). Never a command. |
Where the rootfs comes from. Canonical's official WSL image of Ubuntu
24.04 LTS, published next to the ISOs on releases.ubuntu.com
(https://releases.ubuntu.com/<point release>/ubuntu-<point release>-wsl-amd64.wsl).
Its hash is listed in the SHA256SUMS file of the same directory, which is
signed by the Ubuntu CD Image signing key (SHA256SUMS.gpg, key
843938DF228D22F7B3742BC0D94AA3F0EFE21092).
How to update the rootfs (a new Ubuntu point release, or the URL stopped resolving):
- Download
SHA256SUMSandSHA256SUMS.gpgfrom the release directory and verify the signature with the key above (gpg --verify SHA256SUMS.gpg SHA256SUMS). Take the*-wsl-amd64.wslline. - Download the
.wslfile itself and check thatshasum -a 256matches that line — the manifest must never carry a hash nobody has reproduced. - Put the new
urlandsha256(andversion_id, if the Ubuntu release changed) intowindows.jsonand bumpmanifest_id(windows-r<N>→windows-r<N+1>). A new Ubuntu release (not a point release) also needs the guest recipe qualified on it in core first. make validate, commit, open a PR.
Only new imports use the new manifest: an existing distribution stays on
the manifest_id it was imported from.
The same shape as windows.json, schema windows-arm64.schema.json:
manifest_id is windows-arm64-r<N> and rootfs.distribution.arch is
aarch64 (Ubuntu's arm64 .wsl image, published on cdimage.ubuntu.com).
An arm64 Windows core (atomic-chat-core 0.9.2 and later, branch
fix/tensorrt-llm-windows-arm64) reads this file and an x64 core reads
windows.json. It is a separate file, not a second rootfs in windows.json,
because every released core parses windows.json strictly: an unknown or
aarch64 field there would refuse the whole manifest and hide TensorRT-LLM
from every x64 user. Its rules are windows.json's: a new rootfs is a new
manifest_id, the sha256 is checked against Ubuntu's signed SHA256SUMS,
and it reaches main only after live acceptance on a Windows on Arm machine
with an NVIDIA GPU (RTX Spark N1X).
windows.json reaches main only after live acceptance on Windows.
Merging it into main is what switches TensorRT-LLM on for every Windows
client within an hour, with no release: without it, core on Windows reports
the provider as unsupported to everyone who has not imported the
distribution yet, so app and core can ship their Windows code safely ahead of
it. The manifest is therefore merged only after the Windows acceptance run on
real hardware (Windows 11 x64 with an NVIDIA GPU: enabling WSL with UAC and a
reboot, importing the rootfs, Docker and the toolkit in the guest, a model
load and chat, localhost forwarding, removing the environment) has passed.
Rolling back is removing windows.json from main: new installs stop being
offered, already-imported environments keep working on their pinned manifest.
app/latest.json is read by the atomic.chat landing page
(Webflow) on every page load: a site-wide script swaps the page's installer
links for the ones listed here. It is not read by the desktop client — the
in-app updater keeps using the latest.json asset of the GitHub release.
{
"$schema": "./schema.json",
"schema_version": 1,
"updated_at": "2026-10-02T13:00:00Z",
"version": "2.1.2",
"tag": "v2.1.2",
"release_url": "https://github.com/AtomicBot-ai/Atomic-Chat/releases/tag/v2.1.2",
"downloads": {
"macos": "https://github.com/AtomicBot-ai/Atomic-Chat/releases/download/v2.1.2/Atomic.Chat_2.1.2_universal.dmg",
"windows": "https://github.com/AtomicBot-ai/Atomic-Chat/releases/download/v2.1.2/Atomic.Chat_2.1.2_x64-setup.exe",
"linux": "https://github.com/AtomicBot-ai/Atomic-Chat/releases/download/v2.1.2/Atomic.Chat_2.1.2_amd64.AppImage"
}
}Do not edit it by hand. make release-prod in the Atomic-Chat repository
publishes the newest draft release, then commits this file straight to main
with the URLs of that release's installers. raw.githubusercontent.com caches
it for about five minutes, so the landing page follows a release within that.
.github/workflows/validate.yml runs on
every push and pull request. It performs the following checks:
ajvvalidatesproviders/registry.jsonagainstproviders/schema.json.- Every
providerid must be unique. - The job fails if any
api_keyfield is non-empty. ajvvalidatesmodels/recommended.jsonagainstmodels/schema.json.- Every
(model_name, description_key)pair in the recommended-models manifest must be unique. ajvvalidatesmodels/staff-picks.jsonagainstmodels/schema.staff-picks.json.- Every
model_nameand everyorderin the staff-picks manifest must be unique, anddescription_key, when present, must start withhub:. ajvvalidates both mobile catalogs againstmodels/schema.mobile.json..github/scripts/mobile-catalog-check.mjschecks unique ids, valid UTC dates, safe model/projector paths and engine-specific artifacts;.github/scripts/mobile-catalog.test.mjsexercises valid catalogs and rejects invalid copies, including local download state and desktop platform values.ajvvalidatesmodels/decision.jsonagainstmodels/schema.decision.json(an upstream model must begguf, name adecision_typeand pin ab<build>tag; a checkpoint model a TurboQuant tag)..github/scripts/decision-catalog-check.mjs: model ids and file paths are unique and safe, a checkpoint model lists the four checkpoint files, a GGUF model has onerole: "model"file and at most onemmproj(only whenvisionis true), at most one default per engine, and a default checkpoint model exists.ajvvalidatesmodels/embedding.jsonagainstmodels/schema.embedding.json(every model is an upstreamggufwith ab<build>tag and anicon)..github/scripts/embedding-catalog-check.mjs: model ids and file paths are unique and safe, onerole: "model"file and at most onemmproj, which a model has exactly when it reads more than text,image_max_tokensfits half the context,matryoshka_dimsshrink belowdims, and exactly one default.ajvvalidatesbackends/manifest.jsonagainstbackends/schema.json.- Every
llama-*asset name must carry the declaredtag_name, and asset names must be unique. sha256andsizemust appear together on an asset, and whendownload_baseis set everyllama-*asset must carry asha256— an archive we host but do not hash would be downloaded unverified.ajvvalidatesbackends/llamacpp-upstream-releases.jsonagainstbackends/llamacpp-upstream-releases-schema.json, and.github/scripts/upstream-releases.mjs checkrequires releases newest first and unique, archive names that carry their release's tag, and abackends/manifest.jsonthat names an approved release withmin_core_version0.0.0and the same hashes..github/scripts/upstream-verify.test.mjschecks the approval gates, for llama.cpp, sd.cpp and audio.cpp, against fixture runs in core.ajvvalidatesbackends/turboquant-manifest.jsonagainstbackends/turboquant-schema.json.- Every TurboQuant
tagmust look likeb<build>-<semver>and all entries must share one tag, everyassetmust bellama-turboquant-<id>.zipon Windows /.tar.gzelsewhere, and backend ids must be unique. - Engine descriptors are discovered, not named: every
runtimes/*.jsonexceptschema.json(.github/scripts/runtime-descriptor-files.mjs) goes through the checks below, so a new engine's descriptor is gated without editing the workflow or the Makefile. node --test .github/scripts/runtime-descriptor.test.mjsrunsajv --strictwithruntimes/schema.jsonon every descriptor and on the accept/reject fixtures; the schema'spatternholdsdescriptor_idto<engine_id>-<engine version>-r<n>.ajvvalidatesbackends/sdcpp-manifest.json(andbackends/sdcpp-manifest.staging.json, when present) againstbackends/sdcpp-schema.json, and.github/scripts/sdcpp-manifest-check.mjschecks, for both, the tag, unique backend ids and asset names, the required backends, the CUDA runtime companion, andsha256/sizepairing..github/scripts/sdcpp-approve.test.mjschecks the approval against a fixture release: the staged archives must match it by size and digest.ajvvalidatesbackends/audiocpp-manifest.staging.json(andbackends/audiocpp-manifest.json, once an approval has created it) againstbackends/audiocpp-schema.json, and.github/scripts/audiocpp-manifest-check.mjsruns sd.cpp's integrity rules on both with audio.cpp's tag form.audiocpp-manifest-check.test.mjsruns the schema and those rules on broken copies, and.github/scripts/audiocpp-approve.test.mjschecks the approval against a fixture release (.github/fixtures/audiocpp/).ajvvalidatesbackends/mlx-manifest.jsonandbackends/mlx-manifest.staging.jsonagainstbackends/mlx-schema.json, andnode --testover.github/scripts/mlx-manifest.test.mjschecks the tag pattern, theupstream_tagform, exactly onemacos-arm64asset withsha256andsize, and an RFC 3339published_at(ajv ignoresformathere) on both, plus that broken copies fail the schema..github/scripts/mlx-approve.test.mjschecks the approval against a fixture release (.github/fixtures/mlx/).ajvvalidatesbackends/foundry-local-manifest.jsonagainstbackends/foundry-local-schema.json, and.github/scripts/foundry-local-manifest-check.mjschecks unique tags, unique platforms and asset names per release, all five platforms in every release, and releases ordered newest first bypublished_at.ajvvalidatesmodels/foundry-local-models.jsonagainstmodels/schema.foundry-local-models.json, and.github/scripts/foundry-local-models-check.mjschecks unique model and variant ids and assets, unique and safe file paths, at least one variant per model, the resolve template's{region}and{asset_id}, an httpscatalog.url, platforms each execution provider runs on, and that a variantcontext_lengthis smaller than its model's.ajvvalidatesbackends/litert-lm-manifest.jsonagainstbackends/litert-lm-schema.json, and.github/scripts/litert-lm-manifest-check.mjschecks unique versions, unique platforms and asset names per release, all four platforms in every release, accelerators only onwin-x64, releases ordered newest first bypublished_at, and that no release on the base branch changed content;node --testover.github/scripts/litert-lm-manifest-check.test.mjschecks that broken copies fail.ajvvalidatesmodels/litert-lm-models.jsonagainstmodels/schema.litert-lm-models.json(which also requiresnpuon an NPU variant and forbids it on others), and.github/scripts/litert-lm-models-check.mjschecks unique model and variant ids and repos, safe file paths, that each variant's backend runs on its platforms (npuonly onwin-x64), and thathuggingface.backendsnames only the four platforms and backends that run there;node --testover.github/scripts/litert-lm-models-check.test.mjschecks that broken copies fail.ajvvalidatesbackends/geniex-manifest.jsonagainstbackends/geniex-schema.json(an asset needssizeandsha256, a URL on Qualcomm's S3 mirror or GitHub release, a known platform and no unknown field), and.github/scripts/geniex-manifest-check.mjschecks unique versions, exactly one asset per platform with unique names, releases ordered newest first bypublished_at, and that no release on the base branch changed content;node --testover.github/scripts/geniex-manifest-check.test.mjschecks that broken copies fail the schema and the integrity checks.ajvvalidatesmodels/geniex-models.jsonagainstmodels/schema.geniex-models.json(a model isgguforqairtbykind; a bundle variant needschip, a GGUF needsdevices, a vision GGUF needsmmproj, every file and bundle needssha256), and.github/scripts/geniex-models-check.mjschecks unique ids across models and variants and unique repos, safe file paths, that each device runs on the model's platforms, one bundle variant per chip, and thathuggingface.backendsnames onlywin-arm64and devices that run there;node --testover.github/scripts/geniex-models-check.test.mjschecks that broken copies fail the schema and the integrity checks.- Cross-field integrity that the schema cannot express is checked by
node --testover.github/scripts/inventory-digest.test.mjsand.github/scripts/runtime-descriptor-integrity.test.mjs, on every descriptor —engine_idequals the file name,supported_architecturesandquantization[].formatare unique, everymodel_familieskey is asupported_architecturesentry,curated_modelsare unique byrepository@revision,descriptor_idis<engine_id>-followed by exactly<engine version>-r<n>(form and order),required_disk_bytes >= download_bytes,minimum_compute_capabilityis at or below everyquantization[].min_compute_capability, and everyquantization[].excluded_compute_capabilitiesentry is strictly above that same entry's ownmin_compute_capability. .github/scripts/runtime-descriptor-immutability.test.mjsfails when a descriptor'sdescriptor_idis unchanged against its own version on the base branch but the content differs (a descriptor absent there, such as a new engine's, passes).ajvvalidatesruntimes/environments/linux.jsonagainstruntimes/environments/linux.schema.json, andruntimes/environments/windows.jsonagainstruntimes/environments/windows.schema.json.node --testover.github/scripts/environment-manifest.test.mjsand.github/scripts/environment-manifest-windows.test.mjs(fixture accept/reject against each platform's schema),.github/scripts/environment-manifest-integrity.test.mjs(on the real manifests:manifest_idstarts withplatform + "-"; inlinux.jsonrecipes[].recipe_idis unique anddistributionsare unique by(id, version_id, arch)within a recipe) and.github/scripts/environment-manifest-immutability.test.mjs(fails when a manifest'smanifest_idis unchanged against the base branch but the content differs).ajvvalidatesapp/latest.jsonagainstapp/schema.json, and every download URL must sit under the manifest's owntagandversion.
You cannot merge a PR until CI is green.
make validate is the one command that runs every gate above, including all
the node --test scripts (fixtures, cross-field integrity, descriptor_id
and manifest_id immutability) — the same checks CI runs on a PR.
If you want to run the schema checks individually before pushing:
npx ajv-cli@5 validate -s providers/schema.json -d providers/registry.json --strict=false
npx ajv-cli@5 validate -s models/schema.json -d models/recommended.json --strict=false
npx ajv-cli@5 validate -s models/schema.staff-picks.json -d models/staff-picks.json --strict=false
npx ajv-cli@5 validate -s models/schema.mobile.json -d 'models/mobile*.json' --strict=false
node .github/scripts/mobile-catalog-check.mjs
node --test .github/scripts/mobile-catalog.test.mjs
npx ajv-cli@5 validate -s models/schema.decision.json -d models/decision.json --strict=false
node .github/scripts/decision-catalog-check.mjs
npx ajv-cli@5 validate -s models/schema.embedding.json -d models/embedding.json --strict=false
node .github/scripts/embedding-catalog-check.mjs
npx ajv-cli@5 validate -s backends/schema.json -d backends/manifest.json --strict=false
npx ajv-cli@5 validate -s backends/llamacpp-upstream-releases-schema.json -d backends/llamacpp-upstream-releases.json --strict=false
node .github/scripts/upstream-releases.mjs check
npx ajv-cli@5 validate -s backends/turboquant-schema.json -d backends/turboquant-manifest.json --strict=false
npx ajv-cli@5 validate -s backends/sdcpp-schema.json -d backends/sdcpp-manifest.json --strict=false
npx ajv-cli@5 validate -s backends/audiocpp-schema.json -d backends/audiocpp-manifest.staging.json --strict=false
node .github/scripts/audiocpp-manifest-check.mjs
npx ajv-cli@5 validate -s backends/mlx-schema.json -d backends/mlx-manifest.json --strict=false
npx ajv-cli@5 validate -s backends/mlx-schema.json -d backends/mlx-manifest.staging.json --strict=false
npx ajv-cli@5 validate -s backends/foundry-local-schema.json -d backends/foundry-local-manifest.json --strict=false
node .github/scripts/foundry-local-manifest-check.mjs
npx ajv-cli@5 validate -s models/schema.foundry-local-models.json -d models/foundry-local-models.json --strict=false
node .github/scripts/foundry-local-models-check.mjs
npx ajv-cli@5 validate -s backends/litert-lm-schema.json -d backends/litert-lm-manifest.json --strict=false
node .github/scripts/litert-lm-manifest-check.mjs
npx ajv-cli@5 validate -s models/schema.litert-lm-models.json -d models/litert-lm-models.json --strict=false
node .github/scripts/litert-lm-models-check.mjs
npx ajv-cli@5 validate -s backends/geniex-schema.json -d backends/geniex-manifest.json --strict=false
node .github/scripts/geniex-manifest-check.mjs
npx ajv-cli@5 validate -s models/schema.geniex-models.json -d models/geniex-models.json --strict=false
node .github/scripts/geniex-models-check.mjs
npx ajv-cli@5 validate -s runtimes/schema.json -d runtimes/tensorrt-llm.json --strict=true
npx ajv-cli@5 validate -s runtimes/schema.json -d runtimes/vllm.json --strict=true
npx ajv-cli@5 validate -s runtimes/environments/linux.schema.json -d runtimes/environments/linux.json --strict=true
npx ajv-cli@5 validate -s runtimes/environments/windows.schema.json -d runtimes/environments/windows.json --strict=true
npx ajv-cli@5 validate -s app/schema.json -d app/latest.json --strict=false- API keys must never appear in this repository.
- The registry is served via HTTPS from
raw.githubusercontent.com. - Atomic Chat clients ignore the
api_keyfield even if a malicious commit slips through; user-supplied keys live only in the local OS keychain.
See the project's primary license in the main Atomic Chat repository.
DEPRECATED as an editable desktop catalog. This section describes a generated compatibility export for older consumers. Edit
models/catalog.jsonand regenerate; do not edit the export independently. See model catalog ownership.
models/diffusion.json accepts an optional full 40-character Hugging Face
commit SHA in transformer.revision and in each side file's revision (VAE,
audio VAE or text encoder). Each revision belongs to that entry's repository;
never reuse a transformer commit for a dependency from another repository.
Sizes and SHA-256 values must come from the same revision. Entries without a
revision retain the legacy main behavior. This is an additive schema-version-1
field: older clients ignore it and still use main; pinning takes effect only
in clients that support per-repository revisions.
Z-Image Turbo's transformer is pinned to Unsloth commit
b40f712c569ecfff42f2307dcc43399ae1d71318 (2026-10-29, "Better quants").
Its Q3_K_M, Q4_K_M, Q5_K_M and Q6_K byte counts and LFS SHA-256 values were
refreshed from that revision's Hub metadata; Q8_0 is unchanged. The catalog
metadata was checked; image generation with the replacement files has not
been validated as part of this correction.
models/catalog.json is the only editable source for desktop model definitions, recommendation references and auxiliary HF sources. models/schema.catalog.json and .github/scripts/model-catalog.mjs validate structure, references and full repository commits. Each collection references a model rather than copying its source. omit_revisions records which newly pinned fields a historical export must omit; it does not remove pins from new clients.
The existing desktop JSON files are deprecated generated compatibility exports; their supported consumers keep the same payloads and URLs. The complete list and retirement policy are in models/README.md. Run node .github/scripts/export-model-catalog.mjs after editing the catalog. CI and make validate reject exports that disagree with it. Mobile catalogs and immutable runtime descriptors remain separate contracts. Keep the old exports until support for their released consumers is explicitly ended.
To update one source deliberately, run node .github/scripts/refresh-model-catalog.mjs <model-id> <owner/repo> <full-commit>, regenerate exports and review their changes. The helper obtains file metadata from that exact HF commit. It never substitutes main. The exporter and its tests require no network. Initial migration preserves all old export values and pins historical image files to their matching commits.
Client baselines are generated copies of the same document, not additional catalogs to edit:
node .github/scripts/export-model-catalog.mjs --baseline ../Atomic-Chat/core/src/browser/modelCatalogBaseline.json --baseline ../eye-cli/src/workspace-service/models/model-catalog-baseline.json --baseline ../atomic-chat-core/src/client/model-catalog-baseline.jsonAdd --check to validate those copies offline. Publish compatible conf data, release core, then update the clients' exact core pins and lockfiles before releasing either client.
backends/fastflowlm-manifest.json describes managed native FLM builds, not
models. fastflowlm-schema.json rejects unknown fields, missing hashes,
unsupported platforms and any local_only_protocol other than 1. Empty
releases means no installable build. A release contains an immutable
version: flm-<major>.<minor>.<patch>-r<N>, full upstream_commit, matching
atomic_revision, min_core_version, published_at, provenance and exactly
one win-x64-npu and one linux-x64-npu archive. Provenance pins the core commit,
patch hash, dependency-lock hash and a size/hash-checked provenance document.
Archive and provenance URLs must use the same build tag in core's GitHub
releases. Order is descending numeric upstream semver, then numeric Atomic
revision, not timestamps or lexical order. Changing bytes requires a new
build ID; withdrawing an entry is allowed.
runtimes/environments/fastflowlm-{windows,linux}.json are separate data-only
contracts. The existing container environment documents are unchanged. Empty
recipes means no automatic setup is offered. Each qualified recipe carries
its own min_core_version; the empty bootstrap makes no core-version promise.
Documents have immutable manifest_id: fastflowlm-<os>-r<N>; a changed recipe
also needs a new recipe revision. Platform entries identify Windows 11 x64
or a specific Ubuntu 24.04/26.04 x64 kernel. Hardware IDs, package sources,
versions, hashes, signing identity, live evidence and the qualified FLM build
are explicit. Linux source suites must match the platform; system XRT requires
its NPU plugin. Permission/memlock effects are scoped by core to the runtime
account, not arbitrary commands in conf.
Windows driver sources are limited to AMD downloads and Microsoft's driver
catalog CDN; a recipe distinguishes amd-installer from windows-update-cab.
The host executor must implement and qualify that fixed package kind, verify
signatures and device matching, and never execute commands supplied by a
manifest. A CAB candidate does not establish a tested automatic-install recipe.
make validate and CI run the same FLM schema/negative-fixture, integrity,
immutability, model-file-plan and consumer-compatibility gates. Set
FASTFLOWLM_BASE_REF to the reviewed base ref when checking published content;
CI uses the PR target or pre-push tip, local validation defaults to origin/main.
Model definitions remain exclusively in models/catalog.json (see
the model contract).
The first production build is flm-1.0.11-r2, requiring core 0.22.0 or newer.
Its Windows and Linux archives and provenance are immutable assets of the
engine release.
The production model collection contains only the tested Qwen3 0.6B XDNA2 plan.
Acceptance evidence
distinguishes the exact CI archive run on Windows from the earlier native Arch run.
Qualification covers offline chat with an existing driver on Windows 11 and
manual driver setup on Arch. Clean Windows driver installation and Ubuntu
24.04/26.04 setup were excluded by the operator; service-account setup is not
qualified. Both environment manifests therefore retain empty recipes.
The nine additional chat candidates stay in staging. This scope follows the
2026-11-06 amendment to OpenSpec add-fastflowlm-runtime.
Publication on main can reach clients on their next refresh, within the existing
one-hour cache window. Released cores before 0.22.0 do not gain FLM support from
this data: their parsers ignore the new collection and existing legacy exports
remain byte-identical. The engine prerelease does not replace the latest core
application release. Eye CLI integrates the unreleased core through bun link
before its own release.
backends/strata-manifest.json uses the strict Draft-07
backends/strata-schema.json. Atomic Chat core 0.24.0 and later can install
the listed bundles. The initial variants cover Apple Silicon Metal and
x64 CUDA 13 on Windows and Ubuntu. The Linux entry uses the verified
Ubuntu 26.04 and glibc 2.43 host floors.
backends/strata-manifest.candidate.json is the separately validated input
for packaging and core development.
Candidate strata-0.1.59-r5 pins upstream release v0.2.13, all 24 selected
Control/compute assets and 16 host variants. Linux x64 uses corrected Control
0.1.59.1; other hosts use 0.1.59. Compute is 0.1.59. Documentation,
Control and compute have separate full source commits; do not substitute one
for another. Unknown Linux glibc and AMD driver floors remain explicit
pending_host_checks, not guessed compatibility bounds.
The r5 bundle applies the hash-recorded atomic-external-owner-v3 Control overlay.
Atomic-owned launches write a private receipt before creating each process and
retain its start identity after exit. A dead compute or vision process is
reported to Atomic without an automatic restart. On macOS, failure to create
the owner-death watcher ends the compute process. Standalone Strata retains
upstream behavior. The package probe requires OWNER_CONTRACT == 3.
See r5 owner ledger evidence.
Bundled CPython
3.12.15 imports the preparation/structured-output dependencies, JSON Schema
validation succeeds, and Control, Qwen and DeepSeek version probes exit
successfully on macOS 26.6.2 arm64. This is package smoke evidence, not GPU
inference, lifecycle or model-preparation qualification. See
the package evidence.
Windows/Linux/Spark native probes and runtime/model qualification remain open.
The catalog records 35 upstream-supported profiles across three recipe families;
none is marked atomic-qualified in this data. Six profiles retain the original
strata-models collection, and 29 additional CUDA profiles use the optional
strata-cuda-models collection so older Strata readers keep their known inputs.
Run with Python 3.11+ on a build host; macOS requires native codesign:
python3 .github/scripts/strata/pack.py \
--variant macos-arm64-metal \
--cache /absolute/cache/strata \
--out /absolute/output/strataThe manual Prepare Strata candidate workflow performs the same operation for one selected variant and uploads a CI artifact, without publishing a release. Build inputs come from pinned HTTPS sources and are checked against size/SHA-256, including cache hits. Allow temporary space for upstream archives, extraction, the output and its verification copy. No model weights are acquired.
The archive contains control/ (CPython, Control and local converters),
components/qwen/, optional components/deepseek/, licenses/ and bundle.json.
The latter records every payload file and source, dependency licenses and signing.
The build adds pinned gguf-py plus jsonschema, jsonschema-specifications,
referencing, rpds-py and attrs from
the dependency lock. It removes
experimental projection weights bundled by upstream; model acquisition belongs
to the catalog plan. Neither build nor runtime setup invokes pip install.
Upstream's hardened macOS Python rejects the added rpds wheel's Team ID. The candidate re-signs only the actual Python executable with the existing library validation entitlement and an ad-hoc development signature. Distribution signing and notarization remain release work. Deterministic tar metadata and provenance are tested; a rebuild refusing different bytes under the same output filename requires a new release id, not an overwrite.
Use absolute file URLs:
export ATOMIC_STRATA_MANIFEST_URL="file://<absolute-conf-path>/backends/strata-manifest.json"
export ATOMIC_MODEL_CATALOG_URL="file://<absolute-conf-path>/models/catalog.json"Core uses the published catalog and manifest by default. A local installable
manifest needs the assigned core version, a complete variant.bundle
descriptor and HTTPS archive URLs. Use the candidate inventory as the input
for assembling bundles.
Before promotion, assign minimum_core_version, finish the host checks for each
included variant, assemble/inspect the relevant bundles and obtain the required
Atomic runtime evidence. Publish assets only with separate operator authorization.
Each production variant must describe the complete repacked bundle (URL,
compressed/unpacked size, SHA-256, bundle.json hash, Python and component roots).
Its component records retain upstream provenance; they are not independent
installation targets. Never install raw upstream Control in place of this bundle.
Any change to published bytes, component selection or compatibility metadata
requires a new release_id. Changing preparation outputs also requires the
appropriate preparation ABI/recipe update. Keep old releases immutable. Record
upstream-supported for upstream claims and atomic-qualified only for actual
Atomic execution evidence. Model descriptors and resource accounting are explained
in the Strata catalog contract.
Focused checks (the aggregate make validate needs separate operator approval):
node --test .github/scripts/strata-manifest.test.mjs
node --test .github/scripts/strata-catalog.test.mjs
node --experimental-strip-types --test .github/scripts/strata-catalog-compat.test.mjs
node .github/scripts/strata-manifest-check.mjs
python3 -m unittest discover -s .github/scripts/strata -p test_package.pyFor offline schema tests, set AJV_CLI to an installed
ajv-cli@5/dist/index.js; otherwise the tests use npx --yes ajv-cli@5.