Skip to content

2026-04 — Station → App migration

TL;DR

If your hadron-client config still has a clientKey: line, rename it to appKey:. If the rename alone doesn't connect, your old key was deleted in the cutover — recreate the App in the Hadron portal and copy the new key into appKey:.

What changed

Hadron used to have two overlapping caller-identity entities — Station (a connection point with an API key) and App (an organization-scoped install). They were doing the same job, and the duplication was leaking into every layer of the platform: the database had two tables, the GraphQL surface had two parallel mutation trees, the portal had two separate UIs, the docs had two parallel concept paragraphs.

In 2026-04 these were unified into a single entity, App, that absorbs everything that used to be on Station. The legacy Station tables, GraphQL types, portal routes, and config field names were removed.

The unification is tracked in spec 003-station-to-app; the why-is-this-worth-the-churn argument is in the brainstorming summary.

Why

Hadron's constitution1 requires that each external caller maps to exactly one entity that carries the auth credential, the org-membership role, and the AI-config envelope. Two parallel entities meant the constitution was unsatisfiable in practice — every change had to be done twice and stay in sync, and the two surfaces were drifting (different fields, different defaults, different deletion semantics). Picking one and consolidating onto it was the only path that doesn't force every future feature to re-pay the duplication cost.

Action required (hadron-client users)

1. Rename the config field

The hadron-client config file (.hadron/config.json in your project root, or wherever you keep it) used to look like this:

{
  "clientKey": "hk_xxxxxxxxxxxxxxxxxxxx",
  "defaultLevel": "guided"
}

It now looks like this:

{
  "appKey": "hk_xxxxxxxxxxxxxxxxxxxx",
  "defaultLevel": "guided"
}

Just rename the field. The credential value itself does not change format — the prefix and length are the same. The hard rename was a deliberate choice: a silent shim that translated clientKey: → appKey: would have been a permanent surface, and the migration's whole point was to stop carrying the old terminology.

If you start hadron-client with a config that still uses clientKey:, it exits immediately with a LegacyConfigKeyError whose message points at this page.

2. If the rename alone doesn't connect

Your previous Station's API key may have been deleted during the cutover. To get a fresh key:

  1. Sign in at https://hadronmemory.com/account.
  2. Open the App that corresponds to your install (or create a new one — under the new model the App you used to call a Station is still there with the same name).
  3. On the Client tab, create a new key.
  4. Paste the new key as the value of appKey: in your config file.

3. Both fields present

If your config file ends up with both appKey: and clientKey: (e.g. you started the rename and stopped halfway), hadron-client still rejects it. Remove the clientKey: line — there is no precedence rule, no fallback, no warn-and-continue. The rename is hard.

Action required (portal / GraphQL API users)

If you call the Hadron GraphQL API directly, the Station, StationKey, and related types/mutations were removed. Use the corresponding App, AppKey, etc. names — the field shapes are identical. The legacy names produce a GraphQL "unknown type" error.

If you used the portal's /app/stations/... routes, they have been moved to /app/apps/.... Old links 404; bookmarks need updating.

  1. Constitution Invariant #6: App is the unified caller-identity entity. ↩