Skip to content
helmstudio
Contents

Documentation

helmstudio runs studios: repositories that each wrap an open-weight model — video, image or speech — behind a web page of their own. It installs a studio from a manifest, fetches its weights, runs its processes, keeps one heavy model in memory at a time, and gives every studio the same storage, gallery and timeline, so what one makes is there for the next.

These pages are for someone writing a studio, or wrapping a repository someone else wrote. If you only want to run studios, the repository's README is the shorter road; if you want to work on helmstudio itself, start with CONTRIBUTING.

What runs where when you use helmstudio A vertical flow. At the top, you, opening the launcher — a Mac app window or a browser page on the loopback address. The launcher talks to the helmstudio daemon, which installs, supervises and stores. The daemon reaches three things: a studio, which is its own repository on its own port and is the only place a model ever runs; a helmstudio directory in your home directory, holding the database, the assets, the browsable library and the models; and the network — GitHub and Hugging Face — only when you ask for something that needs it. Below, separated, the same picture for someone writing a studio: the author runs helm dev, which runs their studio from its own manifest and keeps its data in a .helm directory beside it. running a studio you the launcher a window, or a browser the helmstudio daemon installs · supervises · stores a studio its own repo, its own port the model runs here ~/.helmstudio helm.db, assets, library, models, logs the network GitHub and Hugging Face, only when you ask writing one instead a studio author helm dev ./.helm
Everything here runs on your own Mac. A model only ever runs inside a studio, and the only outbound calls are the ones you ask for.

Where to start

If you want to Read
Get something running in a few minutes Quickstart, after installing helm
Understand what runs where How a studio fits together
Describe a studio to helmstudio The manifest
Wrap a repository whose author wrote no manifest Wrap a repository
Look something up The reference — every operation, manifest field and command, generated from the contract and the code

What exists today

helm is released on GitHub, the runtime SDK on PyPI, npm and the Go module proxy, and @helmstudio/css and @helmstudio/ui on npm, so writing a studio needs no clone of this repository. helmstudio itself — the launcher and its daemon — ships as an unsigned Mac app, and also runs from a clone.

A page that would otherwise use one of these says so where it would have.

Not built yet

  • helm studio init — scaffold a studio, which the quickstart's example stands in for
  • helm test — run the smoke harness that certification needs (03 §12)
  • helm doctor — score the criteria against a working tree, and say which provider a studio would get and why (01 §R6c, 05 §4)
  • helm adopt — import a studio's standalone data into the daemon, hardlinking blobs and replaying rows (01 §R6b)
  • helm dev --fixtures — serve canned data in place of a provider
  • helm dev --fail — make an operation fail on purpose, to see what a studio does
  • the launcher's Gallery screen — show every studio's items in one place
  • the launcher's Timeline screen — open a sequence in an editor, which is why :open answers 501

Three packages, one direction

A studio takes as much of helmstudio as it wants. None of it is required: a studio that uses no package at all still installs, launches and runs.

Package Gives a studio Depends on
helm-css Tokens, and classes for layout and components, in both themes. No JavaScript. Nothing.
helm-runtime-sdk A client for the platform API — settings, sessions, records, assets, the gallery, jobs, the timeline and events — in Go, Python and JavaScript, generated from one contract. The API contract.
helm-ui-sdk helm-gallery, helm-player, helm-terminal and helm-timeline, as custom elements. helm-css, and the browser build of the runtime SDK.

Only the runtime SDK knows the wire format. A component is given a client and calls its methods, and helm-css assumes no component's markup, so nothing points back up the chain.

What no package will ever contain: prompt builders, parameter panels, model pickers and scheduler controls. Those are where studios differ, and where their authors' judgement lives.