Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Environment variable reference

This reference is compiled by hand from the Go source under src/, the deployment manifests, and the top-level helper scripts. The code is authoritative: hive.yaml may also expand arbitrary ${NAME} placeholders through the config resolver, but the variables below have built-in behavior.

Core hive runtime

Generating and rotating HIVE_DASHBOARD_TOKEN

HIVE_DASHBOARD_TOKEN (and the dashboard.auth_token config key it falls back to) is an opaque shared secret. The server does not enforce any format:

• Format: any non-empty string is accepted. It is not parsed as a UUID, JWT, or hex value — it is compared byte-for-byte (in constant time) against the Authorization: ****** value on each API request.
• Validation: there is no startup validation and no minimum-length or entropy check. A weak or predictable value is accepted silently, so the burden of picking a strong value is entirely on the operator.
• What it protects: on a self-hosted (non-direct-route) hive this token is the only API credential — it gates agent logs, kick controls, and config reads/writes, and it doubles as the server-to-server X-Hive-Internal credential used by the local proxy. Treat it like a root password for the hive. On direct-route or hub-proxied spokes identity is per-user and the shared token is server-to-server.
• Transport: clients must send the shared token in the Authorization header (Bearer <token> or the raw token value for legacy API clients). ?token= query-string credentials are rejected because URLs are routinely recorded in ingress/access logs, browser history, screenshots, and shared links. Browser terminal opens first POST to /api/terminal/handoff with the caller’s normal Authorization header or session cookie, then navigate with a short-lived single-use code that cannot be replayed. If a new spoke returns 401 for an old ?token= terminal/log URL, upgrade the hub or client that generated that link.
• Empty value: leaving it unset leaves the dashboard API unauthenticated (unless direct-route per-user authorization is configured). Never deploy an internet-reachable hive without it.

Precedence: dashboard.auth_token, DASHBOARD_AUTH_TOKEN, HIVE_DASHBOARD_TOKEN

Three sources can supply the same shared token. The first non-empty value wins and the rest are ignored:

1. dashboard.auth_token in hive.yaml (note that the shipped manifests set it to the ${HIVE_DASHBOARD_TOKEN} placeholder, which the config resolver expands — so in those deployments the env var is what actually supplies it).
2. DASHBOARD_AUTH_TOKEN environment variable.
3. HIVE_DASHBOARD_TOKEN environment variable.

Both env vars hold the token value, not a Kubernetes Secret name. In src/deploy/k8s/deployment.yaml the name of the Secret is hive-secrets; the env var is populated from a key inside it via secretKeyRef. Setting either var to something like hive-secrets configures that literal string as your dashboard password.

Because both resolve to the same field, setting them to different values is never useful — the lower-precedence is silently discarded, which is a common source of “I rotated the token but the old still works” confusion. Pick variable per deployment and rotate that.

Generate a strong value with a CSPRNG; 32 bytes (256 bits) of entropy is recommended:

openssl rand -hex 32
# or
head -c 32 /dev/urandom | base64 | tr -d '=+/'

Placeholders like your-dashboard-auth-token in deployment examples must be replaced — any string “works”, but a guessable token is a full-access credential.

Rotation: the token is read at process start and compared per request, so rotating is: update the env var / Kubernetes Secret / config.env, then restart the container or pod. The old token stops being accepted as soon as the process restarts with the new value; there is no separate session invalidation step (browser device-flow sessions use their own cookies and are unaffected). Update any hivectl environments and other API clients to the new value at the same time.

Deployment entrypoint and proxy knobs

Inference, CLI backends, and agents

Linear agent integration

Part 2 of RFC #4492: the hive can join a Linear workspace as an agent (actor=app OAuth), receive AgentSessionEvent webhooks, and narrate work back as agent activities. Setup and verification steps live in linear-agent.md.

Inside an agent session (set by the hive, never by the operator): ISSUES_ONLY+ agents receive LINEAR_ACCESS_TOKEN (the connected app’s OAuth token, Authorization: Bearer) or, when no workspace is connected, LINEAR_API_KEY (the work-source key, bare Authorization). Advisory agents receive neither and have both stripped. See linear-agent.md.

Backend launch controls

Inside an agent session

Everything in this section is set by the hive, never by the operator - the same convention as the Linear note above. The source of truth is agentEnvPairs in src/pkg/agent/manager.go (the Linear pairs are injected alongside it by the same manager); this table is the contract that agent policies, custom agent definitions, and helper scripts may rely on. Variables marked secret are delivered via tmux set-environment and never appear on a command line, in ps, or in pane scrollback.

Always set:

Set conditionally:

This table documents injected values, not operator knobs - setting any of these in hive.env does not configure the hive, and several (the secrets above) are overwritten or stripped per agent regardless. When agentEnvPairs gains, renames, or removes an injection, update this section in the same PR, exactly as the Keeping this reference current section requires for lookups.

Hub, SaaS, alerts, and backups

Spoke-side derived keys

A hub-hosted spoke is provisioned with the derived sub-keys it needs and never receives the master HIVE_HUB_SECRET. When of these is unset, the spoke derives the same domain-separated sub-key from HIVE_HUB_SECRET, so a spoke still rolling on an older Deployment keeps working. Both sources yield the identical key, so hub verification succeeds either way; a lookup fails closed when neither is configured.

Hub login providers

HIVE_HUB_OAUTH_CLIENT_ID/_CLIENT_SECRET enable GitHub login. Additional human-login providers are OIDC-based and each is enabled by setting its client id (#3664). Per provider <P> in GOOGLE, IBMID, REDHAT, MICROSOFT, CUSTOM:

With two or more providers configured, /login renders a provider picker; with exactly it redirects straight into it. A provider with a client id but missing/invalid issuer is silently skipped so it cannot take down login for the others — check the hub login enabled providers= startup log line when a button is missing.

Kubernetes downward API and platform variables

Contributor relay and top-level helper scripts

Issue triage

Credly badge integration (proposed — not implemented)

No code reads these variables. The Credly integration is a design (Credly badges); Hive ships the contributor-card placeholder and the milestone mapping. There are no live Credly API calls, credentials, or badge issuance. Setting these today has no effect.

They are listed here so the central reference does not appear to contradict credly-badges.md, and so the names are reserved. Treat the table as a design record until the feature ships — at which point these rows move into the sections above and gain real defaults.

Keeping this reference current

The code is authoritative and this table is hand-maintained, so it drifts unless PRs update it. If your change adds, renames, or removes an environment variable lookup, update this file in the same PR.

A CI guard (TestEnvVarsDocDocumentsOnlyRealVariables, in src/pkg/config/env_vars_doc_parity_test.go) enforces one direction of this: every variable given a table row here must actually appear in the implementation, so the reference cannot document something nothing reads. It is-directional on purpose — env var names reach os.Getenv through package constants, config-resolved struct fields, injected getenv parameters, and local wrapper helpers, so no static check can enumerate the full set of variables the code reads.

The converse is therefore not enforced: adding a lookup without adding a row here will not fail CI. Keeping this file complete remains a human responsibility, which is what the rest of this section is for.

What counts as a change that needs an entry:

• A new os.Getenv or os.LookupEnv call in src/ — most live in src/pkg/hub, src/pkg/dashboard, src/pkg/agent, and src/pkg/config.
• A new variable referenced from a deployment manifest under src/deploy/, or from a top-level helper script in bin/.
• A change to an existing variable’s default, or to whether it is required.

What each column means:

Add the row to the section matching the component that reads the variable, and run the searches below to confirm nothing else was missed. exception to “the code is authoritative”: a proposed variable that no code reads yet may be listed, but in a section explicitly marked as such (see Credly badge integration). The marking is the whole point — an operator must never set a variable from this file and have it silently do nothing. When the feature ships, move those rows into the section for the component that reads them.

Verification commands

The table above was cross-checked with these mechanical searches from the repository root:

rg 'os\.(Getenv|LookupEnv)\(' src --glob '*.go'
rg '\bHIVE_[A-Z0-9_]+\b|\bBD_DIR\b|\bGH_APP_KEY_FILE\b|\bAGENT_BACKEND\b' src bin config Justfile
rg '\b(ANTHROPIC|COPILOT|GOOSE|BOBSHELL|OCI|KUBERNETES|POD|NAMESPACE|DASHBOARD|PROXY|SLACK|DISCORD|NTFY)_[A-Z0-9_]+\b' src bin config Justfile
rg 'HIVE_[A-Z0-9_]+|BD_DIR|GH_APP_KEY_FILE|AGENT_BACKEND' src/deploy