GitHub
Menu

Quickstart

Run it locally,
then add a cluster.

A checkout runs the control plane, the console, and a fake fleet with no configuration and no GPUs. Serving a model needs a cluster with NVIDIA GPUs and the NVIDIA Dynamo platform.

01 / Requirements

What you need installed.

  • just
  • Docker
  • uv
  • pnpm
  • Go
  • Python 3.12

kind, kubectl, and helm are only needed for the cluster recipes. Running just on its own lists every recipe. The full guides live in the documentation ↗.

Pre-release

The source is coming soon to GitHub. These are the commands in the pre-release code, which still uses its original names: hgr, HANGAR_*, and hangar-operator.

02 / Local

Run the control plane.

Four commands from the repository root. The fake fleet serves no models.

  1. Install dependencies

    Console packages, Python virtualenvs, and Go modules.

    just setup

  2. Start the control plane

    Postgres, migrations, the API, and the hub in Compose, plus the console dev server.

    just dev

  3. Add example tenants

    Into a fresh database. Pass --demo for a whole worked example, or create tenants from the console instead.

    just seed

  4. Start a fake fleet

    Three fake clusters that enroll themselves once you register them in the console.

    just fleet

What is running

ProcessAddress
APIhttp://localhost:8000
Hubws://localhost:8001/v1/hub/sync
Consolehttp://localhost:5273
Postgreslocalhost:5442 (hangar / hangar)
Local only

Compose runs with HANGAR_APP_ENV=local, which turns admin auth off and relaxes the credentials the plane requires at boot. It exists so a fresh checkout runs with no configuration.

just dev-up starts the same stack without the console, just logs follows it, just dev-down stops it, and just reseed drops the database and starts over. The console also has a fixtures mode (VITE_API_MODE=fixtures) that runs against an in-browser offline plane with no backend at all.

03 / CLI

The CLI works offline.

hgr talks to the same HTTP API as the console, with stable JSON output and a built-in fake backend.

cd libs/cli && go build -o bin/hgr ./cmd/hgr
./bin/hgr --fake cluster ls
./bin/hgr --fake device ls --all -o json
Build it, then explore with the offline fake.
./bin/hgr config set context.server http://localhost:8000
Point it at the local control plane instead.

04 / Checks

Checks, from formatting to interop.

RecipeWhat it runs
just fmtruff, gofmt, prettier. --check verifies without writing.
just lintruff, go vet, eslint, tsc.
just testpytest, go test, vitest. No database or cluster needed.
just test-dbThe database-backed plane tests, against the Postgres in Compose.
just interopThe real Go operator client against the real Python hub.
just checkAll of the above, in order.

just chart-lint renders the chart offline and checks that each required value is refused when empty. just transit, just bench-suite, and just conformance run the three measurement tools.

05 / Clusters

Deploying to a real cluster.

No images or charts are published yet, so you build them into a registry you control.

  1. Build and push the images and chart

    export HANGAR_REGISTRY=registry.example.com/hangar
just push plane && just push gateway && just push operator && just push agent
HANGAR_CHART_OCI=oci://registry.example.com/hangar/charts just chart-push

  2. Run the plane and the gateway

    Against a Postgres you operate and back up. There is no Helm chart for the control plane yet; the project's operations guide covers running the images yourself.

  3. Register each cluster in the console

    Registration mints the cluster's enrollment token and renders its values file.

  4. Install the cluster-setup chart

    In each cluster, with those values. The cluster needs schedulable NVIDIA GPUs; the chart installs the NVIDIA Dynamo platform, the DCGM exporter, the operator, and the agent.

For a real operator against a local Kubernetes cluster, just cluster-up creates a kind cluster. A kind cluster can run the operator but not a model. Wingsmith is built for one organization running its own clusters; there are no per-user roles or SSO yet.

Status

Open source,
under Apache 2.0.

Wingsmith is pre-release. The first public release, and everything after it, will be under Apache 2.0.

View on GitHubRead the docs Run it locally

Built and not built

Built

Multi-cluster placement and routing, Dynamo deployments, device inventory, endpoints and quotas, the console, the CLI, and three measurement tools.

Not built

Published images and charts, per-user roles and SSO, batch and training workloads, and a Helm chart for the control plane.

Pre-release. No tagged release, images, or charts yet, and APIs and protocols can change.