Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,32 @@ The dashboard API can update this field through [`POST /api/effort/{agent}/{effo

The dashboard shows a reasoning-effort dropdown next to the model picker for every method that has an effort control (`codex`, `agy`, `claude`, and `omp`). The value is validated at set time against the method's own set, so a `codex`-only level such as `minimal` is refused for a `claude` agent rather than stored and dropped at launch. For `omp`, the dropdown is per selected model: Hive reads `omp models --json` and uses that model's `thinking` levels, hiding the control for models that report no thinking support. Picking `default` clears the stored value; for `claude` and `omp` that means no effort flag at all and the CLI's own default. The dropdown persists through the same path as the model picker (`hive.yaml` plus the per-agent overlay under `agents_dir`), which is the durable path on a hosted spoke: a hand edit of the agent's file is reverted by the next sync, the dashboard write is not. Each dropdown change is recorded in the audit trail as `set_reasoning_effort` with the new value, like the other per-agent setting changes. The effort the agent was actually launched with is what the run rows and the `- hive:` PR trailer report, so a `claude` agent at `xhigh` shows `effort=xhigh` there and an agent with no stored effort shows none.

#### Claude setup-token

For `backend: claude`, an operator can use a long-lived token instead of the
dashboard sign-in. Run `claude setup-token` interactively as the licensed
operator and complete the prompts. The resulting token lasts about a year and
is inference-only; it is not a general-purpose account credential. See
[Claude Code authentication](https://code.claude.com/docs/en/authentication).

Supply it to the Hive process as the secret `HIVE_CLAUDE_OAUTH_TOKEN`, or mount
it in a secret file readable by Hive. Set `HIVE_CLAUDE_OAUTH_TOKEN_FILE` to
that file's path, or use the default `/secrets/claude-oauth-token`. The
non-empty environment variable wins over the file. Do not put the token in
`hive.yaml`, shell history, logs, issues, or agent panes.

Hive passes the token to Claude agents as `CLAUDE_CODE_OAUTH_TOKEN` at launch,
even when a credentials file exists. It takes precedence over dashboard sign-in;
signing in again on the dashboard does not replace it. Each agent retains its
own Claude home and private state; sharing the token does not require sharing
the whole home. Without an operator token, dashboard sign-in works as before.

To replace an expired or revoked token, run `claude setup-token` again, update
the configured secret source, then recreate or restart Hive to load the new
token and restart the affected Claude agents so their new sessions receive
the replacement. Verify an agent completes a turn. See the
[backend auth recovery runbook](backend-auth-recovery-runbook.md).

#### Oh My Pi (`omp`) hub agents

`backend: omp` launches the OMP CLI as a first-class dashboard method. Hive gives each agent its own durable HOME under `/data/home/agents/<name>`, so `~/.omp/agent/agent.db` can hold several provider sign-ins for that one agent (for example `openai-codex` for the primary model and `anthropic` for an advisor) without sharing refresh-token writers across agents. Select models with their provider prefix (`provider/model`). The dashboard model probe runs `omp models --json` once per omp agent, with `HOME` set to that agent's home, and unions the results; omp lists only models whose provider has a credential in the HOME it runs under, so an agent that is not signed in contributes nothing. When no agent has a sign-in, the dropdown serves a static fallback list, flagged `fallback: true` in the models API and logged at `WARN` with the HOME probed; sign an agent in to see its real models. Each model's `thinking` list drives the effort dropdown. At launch Hive passes `--approval-mode ${HIVE_OMP_APPROVAL_MODE:-yolo}`, `--model <id>`, and `--thinking <effort>` when set.
Expand Down
18 changes: 17 additions & 1 deletion src/docs/backend-auth-recovery-runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,27 @@ recovered and no action is needed.
| `backendAuthStatus` | First action |
|---|---|
| `unlicensed` | Check the seat at <https://github.com/settings/copilot>. If it is active, the hive is presenting a token the account no longer owns: follow the `/login` recovery in [troubleshooting.md](troubleshooting.md). |
| `token-expired` | If `backendAuthRefreshable` is `true` (provider `auth_state: refreshable`), restart the affected agents: Claude Code redeems the refresh grant on start and no login is needed. Otherwise run `/login` in any agent's Terminal with a licensed identity and wait about 30 seconds for the reconciler; affected agents relaunch onto the new token. |
| `token-expired` | For Claude with an operator setup token, replace it as described below; dashboard `/login` does not override it. Otherwise, if `backendAuthRefreshable` is `true` (provider `auth_state: refreshable`), restart the affected agents so Claude Code redeems the refresh grant. If not, run `/login` in any agent's Terminal with a licensed identity and wait about 30 seconds for the reconciler. |
| `forbidden` | Cause is undetermined (bare 403). Read which credential was refused (dashboard model dropdown hover, or the `copilot model discovery rejected by upstream` log line's `credential` field) before re-logging in; an org policy denial is not fixed by a new login. |
| `unreachable` | The inference backend is down or unroutable. Check the backend's own health and network path from the pod; re-login will not help. |
| `quota` | The provider is refusing calls on quota. Wait for the window to reset, add quota, or switch the agents to another backend. Do not restart agents in a loop. |

### Replace a Claude operator token

If `HIVE_CLAUDE_OAUTH_TOKEN` or its secret file is configured, a rejected
token may have expired or been revoked. Run `claude setup-token` interactively
as the licensed operator and complete its prompts. The replacement lasts about
a year and is inference-only. Store it securely in the same Hive environment
secret or in the file named by `HIVE_CLAUDE_OAUTH_TOKEN_FILE` (default
`/secrets/claude-oauth-token`); the non-empty environment variable takes
precedence over the file. Never paste the token into a pane, log, or report.

Recreate or restart Hive to load the changed secret, then restart affected
Claude agents to give their new sessions the replacement. Follow the
verification steps below. A dashboard sign-in does not supersede the configured
operator token. See [Claude setup-token](agent-configuration.md#claude-setup-token)
for initial setup.

## 3. Verify recovery

1. Within one reconciler tick (about 30 seconds) the affected agents drop
Expand Down
4 changes: 3 additions & 1 deletion src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,8 @@ and [network/credential controls](security-model.md#5-network-and-credentials).
| `HIVE_BOB_API_URL` | No | `https://api.us-east.bob.ibm.com` | Bob key-test endpoint base URL override. |
| `BOBSHELL_API_KEY` | Required by Bob CLI when Hive injects or contributor mode uses Bob | none | API key name read by bobshell itself. |
| `COPILOT_GITHUB_TOKEN` | No | dashboard device-flow token file, if present | Copilot completion/model-discovery token and explicit agent injection. |
| `HIVE_CLAUDE_OAUTH_TOKEN` | No | none | Hive-side secret from `claude setup-token`; takes precedence over the secret file and dashboard sign-in for Claude agents. See [Claude setup-token](agent-configuration.md#claude-setup-token). |
| `HIVE_CLAUDE_OAUTH_TOKEN_FILE` | No | `/secrets/claude-oauth-token` | Path to a file containing the setup token, used when `HIVE_CLAUDE_OAUTH_TOKEN` is empty. Keep the file readable by Hive and restricted as a secret. |
| `ANTHROPIC_API_KEY` | Required by `cmd/apiproxy` to inject an upstream key; agent inference backends receive a synthetic value | none | Anthropic-compatible **upstream** API key. Never used to authenticate callers of `cmd/apiproxy`. |
| `PROXY_AUTH_TOKEN` | **Required** by `cmd/apiproxy`; the binary exits at startup when unset and the proxy handler returns `503` | none | **Client auth token** callers must present to `cmd/apiproxy` via `Authorization: Bearer` or `X-Api-Key`. Validated in constant time and stripped before the upstream request. Mandatory because an unauthenticated proxy would let any co-resident loopback caller spend the host `ANTHROPIC_API_KEY`. |
| `CONTEXT7_API_KEY` | No | none | Optional key for Context7 knowledge API integration. |
Expand Down Expand Up @@ -390,7 +392,7 @@ Set conditionally:
| `COPILOT_GITHUB_TOKEN` | When the hive holds a Copilot auth token | Copilot OAuth token (authenticates the AI model, not GitHub writes). **Secret.** |
| `GITHUB_TOKEN` | Only when App-authored PRs are enabled (`AppAuthoredPRs`), an App is configured, and the agent's mode can push | The per-agent tier-scoped App installation token, so the built-in GitHub MCP server writes as the App bot. Advisory agents have `GITHUB_TOKEN` deliberately stripped. **Secret.** |
| `LINEAR_ACCESS_TOKEN` / `LINEAR_API_KEY` | ISSUES_ONLY+ agents on Linear-connected hives | See the [Linear agent integration](#linear-agent-integration) note above. |
| `CLAUDE_CODE_OAUTH_TOKEN` | Last resort: claude backend **and** no readable credential file | Dashboard-obtained access token; never injected when the agent can read (and refresh) `~/.claude/.credentials.json` itself. **Secret.** |
| `CLAUDE_CODE_OAUTH_TOKEN` | Claude backend with an operator token, or as a last resort when no credential file is readable | Hive injects the operator's setup token when configured, even if a credential file exists. Otherwise the fallback is the dashboard-obtained access token only when no credential file is readable. **Secret.** |
| `BOBSHELL_API_KEY`, `BOB_API_KEY`, `BOBSHELL_DEFAULT_AUTH_TYPE` | bob backend only | The resolved Bob API key for Bob 1.x / 2.x (**secret**) and the literal `api-key` auth-type selector (non-secret by design - see the #2228 relaunch note in code). |
| `HIVE_BOB_SESSION_LABEL` | bob backend only when `governor.bob.session_prefix` or `agents.<name>.bob.session_label` is set | The Bob session label also passed to Bob as `--instance-id`. A label only: `HIVE_AGENT` and all functional Hive identity are unchanged. See [agent-configuration.md](agent-configuration.md). |
| `HIVE_BOB_DISPLAY_NAME` | bob backend only | Legacy alias for the Bob session label, falling back to the agent name for older scripts. Prefer `HIVE_BOB_SESSION_LABEL` when present. |
Expand Down
Loading