Plane Configuration

Plane environment variables: database, auth, hub, reactor, metrics, setup chart.

The plane is configured entirely through environment variables typed by app/config/settings.py. Each field reads HANGAR_<NAME> and nothing else; a bare DATABASE_URL or APP_ENV is ignored.

Both processes (API and hub) read the same environment and the same database. The reactor runs under its own process.

Environment and mode

APP_ENV defaults to production, so a plane started with no environment fails closed. Under APP_ENV=local, which has to be asked for:

• ADMIN_AUTH defaults to disabled: a request with no credential resolves to the admin principal
• The API binds 127.0.0.1
• The process logs a warning at startup

Outside local, the plane refuses to boot with ADMIN_AUTH=disabled, without SESSION_SIGNING_SECRET, or without ADMIN_PASSWORD_HASH.

Database

Requires Postgres 15 or later.

API process

The API process serves its own Prometheus metrics at GET /metrics, unauthenticated.

Hub process

Hub scaling

The hub scales by shedding session state instead of sharing it. SessionState (cursors and replay buffer) stays in one pod’s memory, never in Postgres. Reconnecting to the pod you left resumes exactly; reconnecting to a different one costs a full_resync.

What is shared in Postgres is one fact: exactly one hub session may be the writer for a given cluster_id at a time. hello claims that cluster with one atomic INSERT ... ON CONFLICT DO UPDATE. The session it displaces discovers the loss by polling its own claim row on HUB_OWNERSHIP_CHECK_SECONDS and closes the connection the moment the row names someone else.

A session whose cluster never reconnects is reaped after HUB_SESSION_TTL_SECONDS of no attached connection, so an abandoned replay buffer does not sit in memory for the life of the process.

Reactor process

The reactor derives alerts on its own loop under a lease. It is a separate process from the API and hub.

Authentication

Wingsmith is single-operator software: there is one admin identity, and every person signed in as admin can do everything. There are no per-user accounts, roles, or scopes.

Four principal kinds

There is no shared operator token. Each cluster’s enrolment token is stored as a hash and resolves to an operator principal bound to that cluster.

Sessions

Login returns a short-lived access token (hgrs1., SESSION_TTL_SECONDS) and a refresh token (hgrr1.). Refreshing rotates both atomically. A session lasts at most REFRESH_TTL_SECONDS from sign-in, however often it is refreshed.

The guard checks the session on every request, so POST /v1/auth/logout, a revoked tenant token, or a disabled tenant ends access on the next request. Changing ADMIN_PASSWORD_HASH ends every admin session.

Failed sign-ins

Failed sign-ins are budgeted per caller address and account. Behind a proxy, set TRUSTED_PROXIES or every caller shares the proxy’s budget.

Cross-site writes

A POST, PUT, PATCH, or DELETE whose Origin is neither the plane’s own nor in ALLOWED_ORIGINS is 403, and a request body that is not JSON is 415. While admin auth is off, any request whose Host is not loopback, PUBLIC_HOST, or a host in ALLOWED_ORIGINS is 403 too.

Every response carries frame-ancestors 'none' and X-Frame-Options: DENY, so no other site can frame the console.

Generate password hash

uv run python -m app.auth hash          # prompts twice
uv run python -m app.auth hash --stdin  # reads one line from a pipe

Gateway integration

The gateway’s service credential for the plane, accepted on GET /v1/endpoints/resolved, GET /v1/gateway/tenants, and POST /v1/clusters/tunnel-auth only.

Metrics and observability

Remote write authentication

Setup chart and images

The plane renders setup values for each cluster on the register screen. These variables control the chart reference and image overrides.

Benchmarks

These images are passed to the operator for benchmark runs.

Integrations

Running the plane

Both processes read the same environment:

uv sync
export HANGAR_APP_ENV=local
uv run python -m app.api            # HTTP API on :8000
uv run python -m app.api --reload   # with autoreload
uv run python -m app.hub            # operator hub on :8001
uv run python -m app.reactor        # reactor

--check on any process builds it, runs its lifecycle, and exits, which proves wiring without binding a long-lived listener.