Operate

Secrets

The plane can vend run-bound connector sessions. It should not become a second vault UI. Pattern: secrets in your store → env / files / Vault → ${VAR} or secret_ref in config.

What it is

Config and connector YAML support ${ENV} substitution at load. Connectors can also use auth.secret_ref so the credential is resolved at GetSession time (env, file mount, or HashiCorp Vault KV v2 / v1). Helm charts mount Secrets into env or files. Runners receive short-lived session material — not long-lived third-party tokens in agent env forever.

Why it is here

Enterprise reviews ask “where do API keys live?” Answer: your secret manager; Runkite references them. Admin does not CRUD secrets.

How to implement

Keep raw tokens in Vault / cloud SM / sealed K8s Secrets — never commit them.
Mount or inject as env vars / files into the control plane (and runners only if unavoidable).
Reference with ${NAME} in langgraph.json / connector YAML, or set auth.secret_ref (do not set both for the same field).
Prefer connectors for outbound SaaS calls so grants, HITL, and audit apply.
Rotate by updating the secret + rolling pods; revoke old Admin/client keys in config.

`${ENV}` at load

# connector snippet — expanded when the registry loads
auth:
  type: bearer
  bearer_token: ${GITHUB_TOKEN}

`secret_ref` at GetSession

Use when you want the plane to fetch the credential only when minting a session (not bake it into the in-memory config at startup). Schemes: env:VAR, file:/path, vault:secret/data/runkite/…#field. Supported auth types: api_key, bearer, oauth2_client_credentials, oauth2_token_exchange (fills client_secret). The ref string itself is not ${ENV}-expanded.

auth:
  type: api_key
  secret_ref: vault:secret/data/runkite/connectors/github#token
# or: secret_ref: file:/var/run/secrets/github_token
# or: secret_ref: env:GITHUB_TOKEN

Vault env on the control plane

Var	Role
`VAULT_ADDR`	Vault base URL (required for `vault:`)
`VAULT_TOKEN` or `VAULT_TOKEN_FILE`	Token; prefer Agent-injected file
`VAULT_NAMESPACE`	Optional Enterprise namespace header
`VAULT_ALLOWED_PREFIX`	Default `secret/data/runkite/`; paths outside fail closed

KV v2 paths include the /data/ segment Vault expects on the HTTP API (default allowlist secret/data/runkite/). KV v1 paths omit /data/ — set VAULT_ALLOWED_PREFIX accordingly (e.g. secret/runkite/). Paths are cleaned before the prefix check; .. is rejected.

Kubernetes / OpenShift patterns

Secret → env — envFrom / valueFrom.secretKeyRef, then ${VAR} or secret_ref: env:VAR.
Secret → file — volume mount (or projected service account token beside it); secret_ref: file:/var/run/secrets/….
Vault Agent Injector — annotate the CP pod; Agent writes a token file + optional rendered secrets; set VAULT_TOKEN_FILE and/or file: refs. Runkite does not run Vault CSI itself.
OpenShift — same as K8s Secrets / projected volumes; keep long-lived IdP secrets out of the runner Deployment.

In the product

What to expect

Missing env — ${VAR} substitution fails closed at load; env: refs fail at GetSession if unset.
Not in Redis — do not park long-lived third-party tokens in the queue payload.
Next — credentials map, connectors, production day-0.