Manifest reference
One file per studio, at the root of the studio's own repository as helmstudio.yaml. The registry holds pointers to these, never copies. This schema is the whole extension surface: if supporting a studio needs a change to the daemon rather than a change here, the schema is wrong.
A studio's helmstudio.yaml, field by field. Generated from schema/manifest.json; helm validate checks a manifest against the same file, and adds rules a schema cannot state, such as a process's working directory staying inside the studio.
Required at the top: id, kinds, name, processes, requires, runtime.
/build
type array of object
Executed in declared order, each in its own cwd. Non-zero exit stops the sequence; Retry resumes at the first step that has not succeeded.
/build/*/cwd
type string
Relative to the studio root. Must not escape it.
/build/*/name
type string
Shown in the install checklist. Defaults to the command.
/build/*/optional
type boolean · default false
A non-zero exit marks the step skipped rather than failing the install.
/build/*/run required
type string · minLength 1
The schema gives this field no description.
/build/*/shell
type one of "sh", "bash", "powershell", "cmd" · default "sh"
Declared now so a later Windows port does not invalidate every manifest ever written.
/build/*/timeout_s
type integer · minimum 1 · default 3600
The schema gives this field no description.
/capabilities
type array of one of "kv", "records", "assets", "gallery", "timeline", "jobs", "gallery.read_all", "kv.shared", "handoff.send"
Least privilege, shown to the user before install as sentences rather than identifiers. No capabilities means no token is issued at all.
/description
type string · maxLength 140
One line for the card. Clamped to a single line in the UI.
/hue
type object
Identity colour, used only as a 3px stripe, a dot and a timeline clip — never as a button fill. Also injected as --helm-studio-accent. A studio without one is assigned from a generated ramp.
/hue/dark required
type #/$defs/hex
/hue/light required
type #/$defs/hex
/id required
type string · pattern "^[a-z][a-z0-9-]{1,38}[a-z0-9]$"
Stable slug. Used for paths, routes, token scope and the local override filename. Immutable once published.
/import
type object
A one-time, idempotent importer run on first launch under helmstudio, adopting data the studio already has. Never moves or deletes the originals.
/import/cwd
type string
The schema gives this field no description.
/import/run required
type string
The schema gives this field no description.
/import/shell
type one of "sh", "bash", "powershell", "cmd" · default "sh"
The schema gives this field no description.
/kinds required
type array of one of "video", "image", "audio", "text" · minItems 1
A list, not an enum: ltx and h3 are video AND audio.
/license
type string
SPDX identifier where possible.
/license_url
type string · format "uri"
The schema gives this field no description.
/local_path
type string
Absolute path to an existing checkout. When set, cloning is skipped. Development only — a registry manifest never sets this.
/name required
type string · minLength 1 · maxLength 60
Display name, lowercase as the studio names itself (e.g. 'h3 studio').
/network
type array of string
Hostnames this studio is expected to contact at build or run time. The smoke harness flags anything else.
/peak_ram_gb
type integer · minimum 1
What the model actually occupies once loaded. Drives the switch dialog's arithmetic, so an estimate is better than nothing.
/processes required
type array of #/$defs/process · minItems 1
The supervised process group. Started in dependency order, each health-gated before its dependents; stopped in reverse.
/python
type object
Presence makes the daemon create a per-studio uv environment pinned to this version before any build step. Environments are never shared between studios.
/python/extras
type array of string
The schema gives this field no description.
/python/version required
type string · pattern "^3\\.(9|1[0-9])$"
The schema gives this field no description.
/ref
type string
Branch, tag or commit. A registry entry always pins one.
/repo
type string · format "uri"
git clone URL. Required unless local_path is set.
/requires required
type object
os and arch mismatches block Install. Memory and disk shortfalls warn with the real number and let the user proceed.
/requires/arch required
type array of one of "arm64", "amd64" · minItems 1
The schema gives this field no description.
/requires/disk_gb
type integer · minimum 1
Checkout, build output and weights together.
/requires/os required
type array of one of "darwin", "linux", "windows" · minItems 1
The schema gives this field no description.
/requires/ram_gb
type integer · minimum 1
Minimum to install. A shortfall warns; it does not block.
/requires/tools
type array of string
Probed before the first build step. Failing fast here beats failing inside make.
/run
type #/$defs/process
Sugar for a single process with role 'main' and name 'studio'. Mutually exclusive with processes[].
/runtime required
type object
framework and backends are separate because PyTorch-on-cuda and PyTorch-on-mps are entirely different answers for a given machine.
/runtime/backends required
type array of one of "metal", "mps", "cuda", "rocm", "cpu", "vulkan" · minItems 1
Device backends this studio can actually use. The host check runs against THIS, not arch — a studio whose backends the host cannot provide is blocked, not warned.
/runtime/framework required
type one of "native-kernel", "mlx", "pytorch", "ggml", "onnx", "jax", "other"
How inference is implemented. 'native-kernel' means hand-written Metal/CUDA/C with no Python framework in the loop.
/runtime/language
type string
The engine's own stack, shown as prose (e.g. 'c', 'go', 'python').
/runtime/precision
type array of one of "fp32", "bf16", "fp16", "fp8", "int8", "int4"
The schema gives this field no description.
/schema_version
type integer
Manifest schema major. Omitted means 1.
/sdk
type object
Majors pinned separately. The daemon injects matching bundle URLs at launch so a helmstudio update never jumps a studio across a major.
/sdk/css
type #/$defs/semverRange
/sdk/runtime
type #/$defs/semverRange
/sdk/ui
type #/$defs/semverRange
/storage
type object
The schema gives this field no description.
/storage/collections
type array of object
The schema gives this field no description.
/storage/collections/*/fts
type array of string
The schema gives this field no description.
/storage/collections/*/index
type array of string
Top-level JSON fields to build scoped expression indexes on at install time.
/storage/collections/*/name required
type string · pattern "^[a-z][a-z0-9_]*$"
The schema gives this field no description.
/storage/quota
type object
Per-studio caps enforced on write. A studio in a retry loop must not be able to fill a disk.
/storage/quota/kv_bytes
type integer · minimum 1024
The schema gives this field no description.
/storage/quota/records
type integer · minimum 1
The schema gives this field no description.
/submodules
type boolean · default false
The schema gives this field no description.
/test
type object
The schema gives this field no description.
/test/profile
type string
A reduced configuration — smaller model, fewer steps, shorter clip — so the smoke test exercises the real code path in under two minutes. Without one, nothing generative is testable in CI.
/test/smoke
type string
Path to the smoke test definition, relative to the studio root.
/weights
type array of object
The schema gives this field no description.
/weights/*/dest required
type string
The folder it is kept in, under the models directory helmstudio shares between studios. Weights from the same repository and revision use the same folder.
/weights/*/files
type array of string
Which files to take from the repository, as paths or patterns such as vae/*.safetensors. Nothing else is downloaded. It is also what a folder must hold when this weight is linked from one instead of downloaded.
/weights/*/local_path
type string
A folder on this Mac that already holds this weight, with the files above at those same paths inside it. Install links them out of that folder instead of downloading, never writes to it, and refuses by name if one is missing rather than downloading part of the weight. Development only — a registry manifest never names a folder on someone's machine.
/weights/*/name required
type string · pattern "^[a-z][a-z0-9_]*$"
What this weight is called here. A process command writes {models.<name>} where its path should go, and helmstudio substitutes the real path at launch.
/weights/*/optional
type boolean · default false
Not needed to launch. It is left out of the install and fetched later if it is wanted, so an install is not held up by a weight the studio can run without.
/weights/*/repo required
type string
The model's repository on Hugging Face, as owner/name — for example Lightricks/LTX-2.5.
/weights/*/revision
type string · default "main"
Which revision of that repository to take: a branch, a tag or a commit. Defaults to main. This is the model's revision, not the studio's own ref. helmstudio keeps one copy per repository and revision, so two weights naming the same pair share it, and changing it is a different copy.
/weights/*/selectable
type boolean · default false
One of several checkpoints to choose between, rather than one the studio always needs. The chosen one is written into a command as {models.selected}, and it is the only one downloaded; the others are fetched later if the choice changes. Pick before installing, change it while the studio is stopped, and a launch with nothing chosen is refused. Use it where a studio runs one checkpoint at a time, as iris does.
/weights/*/size_gb
type number · minimum 0
Roughly how many gigabytes it is, so the disk can be checked before anything is downloaded. An estimate is better than nothing.
$defs/hex
type string · pattern "^#[0-9a-fA-F]{6}$"
The schema gives this field no description.
$defs/portNumber
type integer · minimum 1024 · maximum 65535
The schema gives this field no description.
$defs/process
type object
The schema gives this field no description.
#/$defs/process/autostart
type boolean · default true
False lets a user start a worker on demand from the studio page.
#/$defs/process/busy
type object
Liveness is not occupancy. A studio may be running and holding nothing, or running and holding 21 GB. Without this the switch dialog is guessing. Asked only when a heavy launch would stop this studio; an answer never changes process or health state.
#/$defs/process/busy/path
type string · pattern "^/"
HTTP GET on the process's assigned port. Answers 200 with a JSON object: {"busy": boolean (required) — work in flight, "loaded": boolean — holds a model, "message": string, "progress": number 0.1}. Any other status, a body without a boolean busy, a progress outside 0.1, or no answer within 2 s reads as unknown, which is never shown as idle.
#/$defs/process/cmd required
type string · minLength 1
Template. Substitutes {port}, {ports.<name>}, {models.<name>}, {models.selected}, {root}, {data}, {venv}.
#/$defs/process/cwd
type string
Relative to the studio root.
#/$defs/process/depends_on
type array of string
Names of sibling processes that must be healthy first. The validator rejects unknown names and cycles.
#/$defs/process/env
type object
The schema gives this field no description.
#/$defs/process/health
type object
Exactly one probe shape. A failed health check never restarts a main process — an eight-minute generation must survive a slow probe.
#/$defs/process/health/exec
type string
A command whose zero exit means healthy. For a worker with no endpoint.
#/$defs/process/health/interval_s
type integer · minimum 1 · default 2
The schema gives this field no description.
#/$defs/process/health/path
type string · pattern "^/"
HTTP GET expected to return 200.
#/$defs/process/health/tcp
type boolean
A successful connect to the assigned port is enough.
#/$defs/process/health/timeout_s
type integer · minimum 1 · default 180
The budget, shown to the user as elapsed against it. A studio that loads 20 GB before answering needs a large one; a thin wrapper needs a small one so a dead process is reported quickly.
#/$defs/process/heavy
type boolean · default false
Marks the process that holds the model. The one-heavy-group-at-a-time rule is evaluated on this member.
#/$defs/process/name required
type string · pattern "^[a-z][a-z0-9_-]*$"
Unique within the studio. Exposed to siblings as {ports.<name>}.
#/$defs/process/port
type object
Omit entirely for a process that listens on nothing.
#/$defs/process/port/fixed
type #/$defs/portNumber
Refuses to start when taken, naming the occupant. For a process that cannot accept a port flag.
#/$defs/process/port/prefer
type #/$defs/portNumber
Advisory. Used when free, otherwise the daemon assigns from its range.
#/$defs/process/restart
type one of "never", "on-failure" · default "never"
A main process is never auto-restarted. A sidecar with on-failure retries with backoff, at most three times in ten minutes, then the group fails.
#/$defs/process/role
type one of "main", "sidecar", "worker", "oneshot" · default "main"
main owns the UI and the Launch button. oneshot runs to completion before dependents start.
#/$defs/process/shell
type one of "sh", "bash", "powershell", "cmd" · default "sh"
The schema gives this field no description.
#/$defs/process/ui
type string · pattern "^/"
Path the Open button targets. Meaningful on a main process.
$defs/semverRange
type string · pattern "^[\\^~]?[0-9]+(\\.[0-9]+){0,2}$"
The schema gives this field no description.