Format reference

manifest.yaml

The naming: block.

Nested under naming: rather than top-level, because manifest.yaml already has its own version: — the package's semver — and these are different numbers.

The rule the block describes: {family}[-{version}][-{variant}][-{parameters}][-{quantization}], joined by hyphens, skipping nulls, all lowercase, never a doubled, leading or trailing hyphen. architecture (dense/moe) and active_parameters (MoE only) are optional catalogue-display fields that describe the model rather than generating its id.

In practice an id is assigned once and never changes. whisper-tiny declares parameters: 39m and kokoro declares version: "1.0" and parameters: 82m, yet both ids are short — both predate the block. Read naming: as documentation of a package, not as the thing that derives its id.

manifest.yaml → ui:

The pipeline UI contract.

Required on a model_pipeline, and not read by the engine for an application. This is what Studio renders as the model's form. The engine carries it opaquely and materialises it at install time as application/manifest.json, which is what the running model server reads and serves at GET /manifest.

Two things to know first. The engine layers identity onto the block on the way out: model_id is always forced to the package id, and display_name, version, description and license are filled in from the manifest's top level only where ui: has not set them. And the block is generated — its authoring source is model.meta.yaml, from which manifest.json is produced. The field names below are the generated ones, which is what a .hutash actually carries.

Model-level fields

Capabilities

ui.capabilities.<id>. The dict key becomes the modality the backend sees and the URL fragment the asset library uses. Studio's linter restricts it to tts, voice, music, stt, clone, voice-clone, sfx; adding another is a coordinated change across the modality map, the linter's valid-id list, the feature loader and the asset library's modality tokens.

A capability must declare at least one input or one control; neither block is individually required.

Inputs

ui.capabilities.<id>.inputs.<input_id>. An input is the artefact the model operates on. The key becomes the form field name, the API request parameter, and the column in the asset's parameters JSON. Four types are valid; anything else is rejected by the linter, because no registered component means no rendering.

Controls

ui.capabilities.<id>.controls.<control_id>. A control is a dial, not an artefact. Every control needs a type, a label and a default — use null for "no default".

Two vocabularies are in play. The specification names five closed semantic types: number, enum, string, boolean, file. Studio's runtime registry — what the linter enforces — is fifteen names: dropdown, select, text, text_input, string, textarea, slider, number, toggle, boolean, multi_select, file, file_upload, audio_file, image_file. Shipped packages use the registry — whisper-tiny writes type: enum and type: boolean, which resolve through the migration table (select↔enum, toggle↔boolean). Author against the registry and the migration table together; the linter is what will actually stop you.

Outputs

ui.capabilities.<id>.outputs.<output_id>. Outputs declare what the model returns and which renderer draws it.

There is no top-level outputs: key on the package. Where a generated file lands is decided at download time by allowlist inversion, not by declaration: the shell checks the extension against a small stable list of model-weight formats (.safetensors, .ckpt, .pt, .pth, .gguf, .onnx, .bin) and routes a match into the shared blob store; everything else falls through to the user's own app output folder. A new output format needs no manifest change.

ui.improve

Controls the Improve button in the prompt textarea, which routes the prompt through a language model.

One strategy renders a plain "Improve" button; more than one renders "Improve ▾" with the default on a plain click. improve: null hides the button entirely — Whisper does this, because transcription has no prompt to improve. Omitting the key falls back to a generic "improve grammar and clarity" instruction, so ship it explicitly.

application/packages.yaml

Dependencies.

Present for any runnable package. The engine, not the package, selects a hardware variant at install time.

How the variant is chosen. With both gpu and cpu declared, gpu wins only when the host has a GPU and its VRAM meets the package's min_vram_gb; a package declaring no minimum is satisfied by GPU presence alone. Otherwise cpu is selected — deliberately, so a model whose minimum exceeds the card's actual memory installs CPU dependencies instead of GPU ones that would fail at load. With only one variant declared, that one is used regardless of hardware. With none, only common is installed.

frozen: true is specific. It is the dependency-graph equivalent of pinning a commit: capture once at test time, install as a locked set, never re-resolve. Re-freezing happens only when testing a new pinned commit. It is meaningless for the other source types — a self-bootstrapping app resolves nothing of ours, a PyPI source resolves fresh by design, and a local source is hand-written code.

application/launch.yaml

Starting a pipeline.

Model pipelines only. No shipped application package carries one.

The proven launch, identical in every shipped pipeline, runs the shared inference server rather than an entry point of the model's own.

Environment the shared server and inference.py read

application/config/app.yaml

Starting an external application.

Applications only. Holds everything a pipeline splits across launch.yaml, plus the provenance a pipeline has no need for.

resources/weights.yaml

What to download.

Model pipelines only. Not used by applications, which manage any downloads of their own.

application/vertical.yaml

A whole interface as data.

Verticals only. This file is the frontend: the shared renderer reads it and draws navigation, page layouts, every widget, the Models marketplace and the Settings form. The vertical's own source holds a single <VerticalApp /> call and nothing else. A widget named here that the catalogue does not have renders an "unknown widget" note rather than silently nothing — which is the point: a vertical cannot quietly grow bespoke interface code.

Top level

A page

A widget

confirm_leave behaviour. Exactly one dialog, and it never changes shape while it is up. Nothing unsaved means no dialog at all, because a prompt on a departure that loses nothing is one users learn to dismiss without reading. Unsaved work with a project open offers Save and leave / Leave without saving / Cancel, where Save and leave navigates only if the write succeeded. Unsaved work with no project offers the warning and Leave / Cancel — there is no third button because there is nowhere to put the work. The auto-save debounce is held while the dialog is open, and the dialog freezes its decision when it opens, so a write landing mid-decision cannot rewrite the question under the button the user was reaching for.

A settings field

Settings save per field. A single whole-form submit would send every field's last-rendered value, so editing one setting could quietly revert another.

A workflow registration, and the setup gate

vertical.yaml refines the gate; it never extends it. What the gate requires is derived from manifest.yaml's capabilities_needed, and an entry here for a capability the manifest does not declare is dropped rather than honoured — gating an app on something it never said it needed is a gate nobody can open. What counts as satisfied is at least one installed model declaring the capability: not a configured one, because settings can name a model since removed, and not a catalogue entry, because a thing you could install is not a thing you have. Two cases deliberately open the app rather than blocking it: no declared capabilities at all, and an unreachable engine.

application/workflows/*.yaml

What an app can do.

One file per workflow. The same YAML generates the web form, the CLI, and the tool surface — add an input here and it appears in all three.

Inputs

Steps

Values interpolate: ${inputs.<id>} reads a run input, ${settings.<id>} reads a settings value, ${<step_id>.output} reads an earlier step's result, and ${<step_id>.outputs.<id>} reads a named output of a sub-workflow step.

Outputs

index.json

The catalogue.

One discovery surface over every package that exists. The engine fetches it once at startup and caches it in SQLite; every consumer filters the one cached copy by type rather than fetching its own. Studio filters pipeline; OS filters application.

The spec describes four fields per entry, on the principle that everything else lives in the package's own manifest. The shipped builder emits considerably more, and for a stated reason: a consumer building a full catalogue row from the index alone would otherwise have to fetch every package's zip, and the extra fields are read from the manifest the builder has already opened — so omitting them would not shrink the index, it would move the zip fetch downstream to break invisibly.

The derived display summary, also per entry: name, description, version, license, min_vram_gb, disk_size_gb, quality_score, speed, modality, hardware_label ("GPU (4GB+)" or "CPU", derived from gpu and min_vram_gb), internal, hf_repo, hf_revision, allow_patterns, weights_external. Four more appear only when the manifest declares them, because a default would be a claim: low_vram_capable, language, languages, min_os_version.

Both blocks ride alongside packages because they describe the generation system rather than any one package. The builder never regenerates their content; it carries them forward verbatim across a rebuild. Never hand-edit the packages list — run python scripts/build_index.py and --check it.

Next

Keep going.

• Widget catalogueWhat a declared type renders as, on both sides of the format.
• WalkthroughPackage a model from scratch, install it, and run it.