Self-hosting overview
What you run and where, what it needs, which connections go which way, and the order to install it in.
Wingsmith is pre-release. There is no tagged release, no published image and no published chart. You build every image yourself and push it to a registry you control. See Build images.
There is no Helm chart for the control plane yet. These pages describe the processes, what each needs and the decisions you make, so you can run them with Kubernetes manifests, a chart of your own, or another orchestrator.
What you run
| Where | Component | Count | Notes |
|---|---|---|---|
| Central | Plane api | one or more | HTTP API and console on :8000 |
| Central | Plane hub | one or more | WebSocket on :8001 at /v1/hub/sync. Runs the reactor unless you split it out |
| Central | Plane reactor | optional | Derives alerts. Runs inside the hub by default |
| Central | Plane migrate | one-shot | Runs before each rollout |
| Central | PostgreSQL | one | Outside the plane’s own deployment. You back it up |
| Central | Gateway | one or more replicas | The only process in the inference request path |
| Each GPU cluster | hangar-operator | one | Syncs desired state from the hub, reports observed state |
| Each GPU cluster | hangar-agent | one | Carries inference requests in over tunnels it dials out |
| Each GPU cluster | Dynamo platform | one | Installed by the cluster chart |
| Each GPU cluster | DCGM exporter | one | Installed by the cluster chart. Gives the operator device identity |
Per-process settings are in Plane configuration, Gateway configuration, Operator configuration and Agent configuration.
What talks to what
Every connection into a GPU cluster is initiated by the cluster. Neither the plane nor the gateway holds a kubeconfig or opens a connection to a cluster.
| Connection | Direction | Port | Through |
|---|---|---|---|
Console or hgr to api | into central | :8000 | HTTPS ingress |
| Operator to hub | out of the cluster | :8001 | HTTPS ingress with WebSocket support |
| Agent to gateway | out of the cluster | :8443 | TCP passthrough, TLS terminated by the gateway |
| Your edge to gateway | into central | :8080 | ClusterIP only, behind a NetworkPolicy |
| Tenants to gateway (optional) | into central | the address in HANGAR_GATEWAY_PUBLIC_LISTEN | HTTPS ingress on a wildcard host |
| Gateway to api | inside central | :8000 | Service token |
Ingress rules, TLS and NetworkPolicies are on Networking. Who is trusted on each path is on Security.
What you need
Central side
- A container registry your clusters can pull from
- PostgreSQL 15 or later. The project tests against version 17
- An ingress or load balancer for the api, the hub and the gateway tunnel
- DNS names and TLS certificates for the plane host and the gateway tunnel host
- Optional: a metrics store that accepts Prometheus
remote_write. Without one the console shows inventory only
Each GPU cluster
- Kubernetes with schedulable NVIDIA GPUs
- A ReadWriteMany storage class for the shared model cache
- Outbound access to the hub and the gateway tunnel
- Helm, and a checkout of the repository to install the cluster chart from
The database holds everything the plane has been told: clusters, enrolment token hashes, workloads, endpoints, tenants and quotas. Without a backup, losing it means re-enrolling every cluster and re-declaring every workload. Use point-in-time recovery if your platform offers it, and test a restore.
Install order
Build images
Build the plane, gateway, operator and agent images and push them to your registry. Build images.
Deploy the control plane
Run Postgres, the migration, the api and the hub. Control plane.
Deploy the gateway
Run the gateway and expose the tunnel listener. Gateway.
Enrol a cluster
Register the cluster in the plane and mint its enrolment token. Enrol a cluster.
Install the cluster chart
Install the operator, agent, Dynamo platform and DCGM exporter on the cluster. Cluster setup chart.
After the install, see Upgrades, Plane outages and Monitoring.
Wingsmith is built for one organisation operating clusters it owns. Human access is a single admin role.