Registry access and the registry document

Registry API access

Desktop's registry, inventory, cleanup, convergence and storage-reconciliation requests use one source-bound client bearer, not its Wisent account session. Configure the server's deployment profile with an exact client and only the actions that client should perform:

{
  "registry_api": {
    "clients": {
      "stado-desktop": {
        "item": "stado-desktop-registry-api",
        "actions": [
          "policy-read",
          "converge-read",
          "converge-apply",
          "storage-reconcile-read",
          "storage-reconcile-apply"
        ]
      }
    }
  },
  "secrets": {
    "skarbiec": {
      "url": "https://skarbiec.example",
      "consumer": "stado",
      "token_file": "~/.stado/stado-skarbiec-token"
    }
  }
}

The Skarbiec item must be named <client>-registry-api; its token field holds the client's raw API bearer. Stado's product grant reads that field. Do not put the Skarbiec grant bearer or an account session token in Desktop's client file. The server uses secrets.skarbiec for all its own field reads; Desktop's raw client bearer is a separate credential bound to one endpoint.

policy-read permits the projected registry and host inventory; policy-write permits policy updates. cleanup-read and cleanup-run permit the janitor's report and action. converge-read permits the Services report; converge-apply permits delivery. storage-reconcile-read permits only the storage transaction's Status request; storage-reconcile-apply independently permits Run, Resume, Rollback and Finalize. An apply-only client does not gain read permission, and a read-only client cannot deliver a release or change a storage transaction.

The storage action names and their dashboard route must be deployed together. Older Stado servers reject these names as unknown configuration instead of ignoring them. Upgrade the server before adding the two actions; before rolling back to an older server, remove them or restore that server's prior client action list. Leaving the new grants in an older profile is not a compatibility shim.

In Desktop Settings → Registry API access, save the exact source endpoint and an absolute token-file path. Desktop rereads the file on each request. The two STADO_REGISTRY_API_* environment variables override the saved fields; when either is present the settings are read-only. The default client path is ~/.stado/registry-api-desktop-token. A missing, empty or unreadable client file is reported locally; a credential assigned to another endpoint is not sent.

An absent client mapping or a missing, wrong or action-ineligible bearer returns HTTP 401. Malformed mapping or unreadable verifier state returns 503, not permission to use another credential. A completed convergence or storage reconciliation product result returns HTTP 200 with exit_code and the complete report, even when that exit code is nonzero; storage reconciliation also retains refusal. See Services and storage root authority handoff.

Registry

stado-rs/data/fleet/registry.json is an intentionally empty bundled seed. A release binary therefore knows no operator host, service, route, release key or workload until the operator creates a registry with stado config init or publishes one through the selected store. stado registry push and stado registry pull resolve that store from STADO_CONFIG, preserve generation fencing, and surface an unreachable store as failure rather than silently switching providers.

Each target entry:

{
  "name": "my-workstation",
  "kind": "local",
  "ssh": "user@host-or-ip",       // used by `wc bootstrap` to install the agent
  "gpu_type": "nvidia-tesla-t4",  // SKU label the agent broadcasts
  "vram_gb": 96,                  // total GPU VRAM
  "gpu_power_limit_watts": 300,   // persistent board power cap, reconciled by the agent
  "env_overrides": { "WISENT_DTYPE": "auto" },
  "agent_args": ["--gpu-type", "nvidia-tesla-t4"]
}

A target declares capabilities and policy, not a concurrency limit. The worker measures live CPU, RAM, disk, running jobs, and per-device VRAM every poll and admits as many compatible jobs as those resources allow. Legacy slots, max_concurrent, and WC_LOCAL_SLOTS values are discarded when a registry is read and are never written back.

gpu_power_limit_watts is valid only on local targets and must be a positive integer. Set it with stado host gpu power set TARGET WATTS and withdraw it with stado host gpu power unset TARGET: Stado writes the generation-fenced declaration, applies it immediately, and the local agent re-asserts it at startup and on every poll it declares. A declared cap that the NVIDIA driver cannot apply closes admission on that host instead of silently running new jobs outside the policy.

A coordinator entry pins the scheduling-tick driver:

{
  "name": "local-control-plane",
  "runtime": "daemon",
  "host": "https://stado.wisent.com",
  "interval_seconds": 180,
  "state_uri": "stado://system/registry",
  "active": true
}

A registry document may also carry the fleet's central enrollment and communication catalog. enrollment declares which registration paths are allowed — allow_join for machine-initiated stado fleet join/approve, allow_enroll for control-plane stado fleet enroll, and require_verified_hostname for the verified-identity contract. channels declares how machines reach the control plane. Both sections are additive: a document without them is unrestricted, which stado fleet catalog reports explicitly. The stado fleet commands enforce the catalog in their preflights, before any write.

{
  "enrollment": {
    "allow_join": true,
    "allow_enroll": true,
    "require_verified_hostname": true
  },
  "channels": {
    "control_plane": ["loopback"],
    "notes": "any address that resolves: LAN, mDNS, tailnet"
  }
}