Skip to main content
Meerkat separates where a provider request goes from how that request is authorized. Sessions refer to a binding, and the binding joins one backend profile to one auth profile.
This lets one process use several provider accounts or tenants, give mob members different credentials, and re-resolve credentials on resume without putting secret material in the session transcript or metadata.

​
The Five Identities

The backend profile and auth profile must name the same provider, and that provider must support the selected backend_kind and auth_method pair. Meerkat validates the combination before constructing the provider client. Without credential_account, the binding itself remains the credential identity. With it, route selection still uses the binding while token storage, refresh locking, login state, status, and logout use the realm-scoped account. This is how the three GitHub Copilot provider-family routes share one sign-in, or one operator-supplied GitHub token (github_copilot_token); an account holds one of the two methods at a time. [realm.<realm>.copilot] declares such an account once, with its credential source, and the realm gets the account’s three routes as if their tables were written out (see GitHub Copilot configured once). For self-hosted models, the backend profile can also identify the specific self_hosted.servers.<id> entry it authenticates. This prevents a credential for one OpenAI-compatible server from being selected for another server merely because both use the self_hosted provider class.

​
Binding Selection

A realm can declare one default_binding, and a binding can set provider_default = true to become the default for its provider. An explicit auth_binding always names the intended configured binding directly. When the model is omitted, session creation resolves in this order:
  1. An explicit binding’s default_model, if present.
  2. A configured model compatible with the explicit provider or binding.
  3. That provider’s catalog default.
  4. With no provider/binding constraint, the configured global model and then catalog defaults.
An explicit model still wins, but a known provider/model mismatch fails before agent construction.

​
Structural References

Public JSON surfaces use an object:
The CLI accepts prod:openai or prod:openai:optional-profile as an input convenience and converts it to the structural form at the CLI boundary. Runtime and persistence contracts do not carry the joined string. Configured references have origin = "configured" (the serialized default). The environment-variable fast path uses a typed origin = "synthetic_env_default"; it is ephemeral and is not a durable realm that can be configured or inherited.

​
Sessions Keep Intent, Not Secrets

SessionMetadata.auth_binding persists the binding reference used by a session. On resume or a model hot-swap, the factory re-resolves that reference against the effective realm config and obtains a fresh credential lease. Access tokens and API keys are never stored in session metadata. If a turn changes provider, supply a matching model and binding together. Leaving the binding unchanged preserves the existing account intent and will fail closed if it is incompatible with the new provider.

​
Inheritance And Ownership

Realm config is resolved through its configured parent chain and an optional global tail:
  • Binding reads inherit. A workspace realm can use a binding defined in a parent or in global.
  • HostAuthService and RPC/REST credential writes are strict-owner and explicitly addressed. A child-addressed inherited write is rejected with the owner; those services do not forward it automatically.
  • A resolved inherited binding retains its owning realm as provenance. That realm keys managed credentials and auth leases.
Current CLI logout exception: when the loaded config resolves child:<binding> to an inherited owner, rkat auth logout child:<binding> can clear that owner’s stored credential, including a shared credential account used by other routes. Explicitly address the true owner instead. A bare logout binding means global; --realm does not retarget logout. HostAuthService/RPC/REST strict ownership and the raw-head config get / set / patch read/write split are unchanged.
Interactive rkat auth login provisions global, whose credentials are readable from workspace realms without copying them into each workspace config.

​
Credential Sources

An auth profile can resolve credentials from environment variables, the managed token store, an inline secret, a platform default chain, a host resolver, a command, or a host-supplied file descriptor. Availability depends on the auth method and build features. Use environment variables for the simplest local path. Use managed-store OAuth or an explicit host resolver when account identity, refresh, or tenant isolation matters.

​
See Also