Install

Build images

Build the plane, gateway, operator and agent images from source and push them to your own registry.

Wingsmith publishes no images. Build them from a checkout of the repository and push them to a registry your cluster nodes can pull from.

Prerequisites

Docker and just. The build refuses a dirty working tree, so commit or stash first.

Build and push

Choose a registry

export HANGAR_REGISTRY=registry.example.com/hangar

Each image is pushed as $HANGAR_REGISTRY/<name>.

Push each image

just push plane
just push gateway
just push operator
just push agent

just build <name> builds without pushing.

Setting	Default	What it does
tag (second argument)	short commit hash, 7 characters	`just push plane <tag>` overrides it
`HANGAR_PLATFORM`	`linux/amd64`	Target platform. An arm64 build on a laptop pushes cleanly and then crash-loops with `exec format error` on amd64 nodes
`HANGAR_REGISTRY`	`ghcr.io/hangar-dev`, which is not yours	Always set it

HANGAR_PLATFORM=linux/arm64 just push plane

Rules the recipes enforce:

The image is built from the committed tree at HEAD, not from your directory, so ignored local files never end up in an image.
latest is refused. Leave the tag out to use the commit.
push refuses a tag the registry already has. A tag is pushed once and never moved; a new build is a new tag.

What each image runs

Image	Runs	Command
`plane`	Control plane	`migrate upgrade head` (one-shot), `api` (default), `hub`, `reactor`, `prune-events`
`gateway`	Gateway	Default entrypoint
`operator`	Per GPU cluster	Default entrypoint
`agent`	Per GPU cluster	Default entrypoint

The plane image’s entrypoint takes the process name as its first argument. reactor is only needed when the hub runs with HANGAR_REACTOR_ENABLED=false. See Control plane.

The just recipes also accept an evalscope target, the benchmark harness image. You only need it if you restrict benchmark images. See Cluster setup chart.

Tag the cluster images to match the chart

The cluster chart defaults the operator and agent image tag to the chart’s appVersion. Either push those two images under that tag, or set the image repository and tag in the chart values.

version=$(sed -n 's/^appVersion: "\(.*\)"/\1/p' libs/chart/cluster-setup/Chart.yaml)
just push operator "$version"
just push agent "$version"

Pull secrets

If your registry needs a credential to pull, the chart can create one for the operator and agent:

imagePullSecret:
  create: true
  registry: registry.example.com
  username: your-username
  token: your-token

The chart creates a kubernetes.io/dockerconfigjson Secret in the release namespace and attaches it to the operator and agent ServiceAccounts. To use a Secret you created yourself, set only its name:

imagePullSecret:
  name: my-pull-secret

Engine and frontend images run in the workload namespace. If those come from a private registry, list the Secret name and the chart copies it there:

operator:
  engine:
    imagePullSecrets:
      - my-pull-secret

frontend:
  imagePullSecrets:
    - my-pull-secret

For the plane’s own settings for the images clusters install, see Control plane and Plane configuration.

Push the chart

No chart is published. To push cluster-setup to an OCI registry of your own:

helm registry login registry.example.com
export HANGAR_CHART_OCI=oci://registry.example.com/hangar/charts
just chart-push

The chart is packaged from the committed tree, so local changes must be committed first. The recipe also refuses a chart version the registry already has, and requires appVersion to equal version in Chart.yaml.

You can also install the chart straight from the checkout, which needs no push. See Cluster setup chart.