# Auth And Providers This is the locked runtime contract for credentials, provider selection, repair, and hatch bootstrap. The short version: each agent owns one vault. Provider/model choice lives in the agent bundle. The daemon loads credentials into memory and reuses them. Humans own browser login, MFA, provider dashboards, vault unlock secrets, and raw secret entry. Agents can diagnose, refresh, verify, and explain without ever seeing raw secrets. The mental model is simple: an agent needs a password manager in the same way a human does. The agent vault is that password manager. Most items are just the agent's stored credentials for tools and services; a few well-known items are harness-readable because Ouro must use them on the agent's behalf, such as model providers, Perplexity search, Teams, and local sense attachments. ## Sources Of Truth | Concept | Source Of Truth | Notes | | --- | --- | --- | | Agent identity, phrases, senses, context, vault coordinates | `~/AgentBundles/.ouro/agent.json` | Vault coordinates are not secrets. | | Provider/model selection | `~/AgentBundles/.ouro/agent.json` | Two lanes: `outward` and `inner`. Legacy `humanFacing`/`agentFacing` fields are compatibility aliases only. There is no silent fallback between lanes; an agent can opt in to logged automatic fallback with `providerFallback` (see Automatic provider fallback). | | Provider credentials | The agent's Bitwarden/Vaultwarden vault item `providers/` | One vault per agent. No shared machine credential pool. | | Portable runtime/integration credentials | The agent's Bitwarden/Vaultwarden vault item `runtime/config` | Teams, OAuth connection names, Perplexity, embeddings, ElevenLabs TTS, and similar credentials that should travel with the agent. | | Local sense attachments on this machine | The agent's Bitwarden/Vaultwarden vault item `runtime/machines//config` | BlueBubbles server URL/password/listener config, Whisper.cpp CLI/model paths, and other local-only attachments. Missing local attachments are `not_attached`, not broken. | | Travel/tool credentials | Ordinary items in the agent's Bitwarden/Vaultwarden vault | Examples: `duffel.com`, `stripe.com`, or other service domains. | | Vault unlock material on this machine | Local unlock store | Prefer macOS Keychain, Windows DPAPI, or Linux Secret Service. Plaintext fallback is allowed only by explicit human choice. | | Hot runtime | Process memory | Loaded from vault at defined refresh points, never fetched from the remote vault per request. | The only Ouro-owned durable credential locations are the bundle and the agent vault. Local unlock material is a machine-local cache, not a credential source of truth. Do not introduce a second credential source of truth. Raw credentials belong in the owning agent's vault. Bundle files may contain references, configuration, state, and vault coordinates, but not raw credentials. ### GitHub issue authorization and blocked reports `file_ouroboros_bug` uses the current Teams user's GitHub OAuth token, supplied by the configured GitHub Bot Framework connection (see [OAuth setup](OAUTH-SETUP.md)). The portable vault configuration stores the Teams/OAuth connection configuration, not a general-purpose issue-filing token. `ouro auth --provider github-copilot` authorizes the model provider; it does not authorize this issue tool. The tool never borrows provider, app or host `gh` tokens. An adapter declares `oauthAvailable` only for logical services whose sign-in it can start this turn. A no-op `signin` callback is not evidence of capability. `AUTH_REQUIRED` is emitted only for a declared available service; missing or unavailable routes return `AUTH_UNAVAILABLE` with the reason. Outside a configured Teams channel, **human-required** recovery is to sign in and submit a sanitized issue at , or configure the Teams connection and consent there. **Agent-runnable** recovery is `report_failure`: valid real reports remain in the owning bundle's `state/reports/.json` even when no friend holds a root-owned escalation grant. The result then says `filed: false`, `saved: true`, `delivery: "pending_authorization"`, with the local path and report id. This is not delivery to engineers and is not a GitHub issue. Repeating the same failure from the same origin folds into that pending report and retries against current grants; the A2A server also retries pending reports at startup and on its existing confirmation interval. An authorized delivery queues an idempotent peer outbox entry; it does not prove the peer has read it. Minimal durable enqueue/acknowledgment receipts prevent a retry from duplicating an acknowledged delivery after interrupted report persistence. They are removed when the closed report is pruned. Replay reports remain isolated and are not put in this real queue. Rate limits and runtime-derived owner attribution apply to local saves as well as deliveries. **Human-required** escalation setup uses a verified peer and the existing root-owned grant procedure (`ouro a2a escalation grant --friend --did --agent `, run as root). No missing grant is created automatically. Keep reports private until a human or authorized agent has sanitized them for an external tracker; local reports can contain the owner's words and conversation coordinates. ### Agent display identity `agent.json` may include `displayName`, the agent's human-facing name. It does not rename its bundle, change the `--agent` identifier, select providers or grant authority. For example, the bundle `orchid-runtime.ouro` can have `"displayName": "Orchid One"`. Add that field to the existing document; do not replace the rest of its configuration. An explicit display name must contain 1–80 characters, without surrounding whitespace, markup delimiters, control or invisible formatting characters. Both runtime config readers validate it. Existing bundles without the field use their configured agent identifier; the runtime never guesses a name from psyche prose or maps every agent to "Ouro". Shepherd's session entry, composer, attribution and feedback acknowledgements use this explicit identity. **Ouro Shepherd** remains the product name. ### Shepherd periodic check-in cadence The owning bundle's existing `agent.json` may set `senses.shepherd.checkInMinutes`. Omitted means `60` (hourly); `0` disables periodic checks; otherwise it must be an integer from `30` through `1440`. Invalid values are explicit configuration errors, not silent defaults. Restart the Shepherd sense after editing this setting. It is portable agent policy, not a machine credential or provider setting; add it without replacing other fields. The timer only initiates fresh triage of returned-control sessions. It is not agent pacing, a provider retry promise, recovered-connectivity evidence or permission to bypass human decisions, drafts, unknown input state or background work. The existing provider lanes and retry policy are unchanged. Unchanged periodic blockers do not repeat owner notices or private wakes. See [Shepherd Sense](shepherd-sense.md#periodic-fresh-check-ins) for host limits, guarded input and shared durable uncertain-send custody. ## Provider Selection Every agent has two provider lanes in `agent.json`: - `outward`: CLI, Teams, BlueBubbles, Mail, Voice, and other human-facing senses. - `inner`: private agent-facing turns and agent-facing model calls. Both lanes must be complete on each machine: ```bash ouro use --agent --lane outward --provider --model ouro use --agent --lane inner --provider --model ``` ### Image understanding Inbound attachment descriptions (including Teams screenshots) and `describe_image` use the owning agent's configured `outward` provider and model. Vision-capable models receive normalized image bytes through the existing provider adapter: Copilot handles its vision header and Responses conversion, and Anthropic handles native image blocks. No additional provider's key is required. Description requests have no tools and do not receive the conversation history. When the selected provider is MiniMax and its chat model lacks native vision, its existing VLM endpoint uses that same agent's MiniMax credential. Other non-vision models return an explicit unsupported-model error with **human-choice** guidance to select a vision-capable outward model. Authentication, provider and incomplete-response failures remain visible; image understanding never silently switches providers. `ouro use` changes the provider/model choice in `agent.json`. It does not create or update credentials. ### Automatic provider fallback An agent can opt in to automatic fallback by listing backup providers in `agent.json`: ```json "providerFallback": [{ "provider": "minimax", "model": "MiniMax-M3" }] ``` With that set, each lane's chain is its own provider and model, then the other lane's, then each `providerFallback` entry in order. When a provider call fails with an error the agent cannot fix (auth failure, spent credit or a usage limit, a 429, an overload or outage, a network error) after the retry ladder below, the entry is benched and the same turn carries on with the next entry that is not benched and has credentials in the vault. Nobody is asked to switch. Spent credit is not retried on the same account first, and its 400 does not get the corrected-history retry. Unknown errors, such as a malformed request, do not fall back. Benches last until the provider's `Retry-After`, otherwise an hour for spent credit or a rejected key and five minutes for a throttle, an outage or the network. Credit and keys belong to the account, so those bench every model on that provider; throttles and outages bench one model. While the primary is benched, turns start on the first entry that is not; after the bench ends, the next turn tries the primary again and moves back by itself. This is not silent. Every switch is an `engine.provider_fallback` nerves event, every bench is `engine.provider_cooldown`, every answered turn records the provider that served it as `engine.provider_served`, and the move back is `engine.provider_fallback_recovered`. The owner gets one plain notice when a backup takes over (Telegram, or the private runtime queue when Telegram is absent), at most once a day. The friend-facing "switch to " text appears only when every entry in the chain failed. Without `providerFallback`, nothing falls back automatically. ## Credentials Provider credentials are stored with: ```bash ouro auth --agent --provider ``` `ouro auth` stores credentials in that agent's vault. It does not switch a provider lane. In a human terminal it keeps a visible checklist for the auth attempt, vault write, refresh, and verification steps so browser login or vault IO never looks like a dead cursor. `github-copilot` takes its GitHub token from `GH_TOKEN` or `GITHUB_TOKEN`, then from `gh auth token`, and otherwise logs in with `gh auth login`. On a host without `gh` (an appliance, a container), it runs GitHub's device flow itself: it shows a code to enter at `https://github.com/login/device` on any device, waits for approval, and stores the token in the vault. The flow uses the GitHub CLI's public OAuth app and default scopes, so the token is the same kind `gh auth login` would have produced. The two generic Chat Completions identities are deliberately separate vault items and provider identities: - `minimax` uses `providers/minimax` and MiniMax models (`MiniMax-M3` by default). - `openai-compatible` uses `providers/openai-compatible`, the canonical base URL `https://api.z.ai/api/paas/v4/`, and GLM models (`glm-5.3-flash` by default; `glm-4.5-flash` is an explicit zero-cost bootstrap probe; `glm-4.7-flash` remains an explicit same-lane probe; `glm-5.2` and `glm-5-turbo` remain explicit same-lane alternatives). - `openai-compatible-gemini` uses `providers/openai-compatible-gemini`, the canonical base URL `https://generativelanguage.googleapis.com/v1beta/openai/`, and `gemini-3.6-flash`. Both items store `apiKey` as credential material and `baseUrl` as provider configuration. The base URL is exact after trailing-slash normalization; arbitrary compatible hosts are rejected. API keys are collected through hidden input only. Neither provider is a silent fallback for the other or for another lane. ### GitHub Copilot account pool An agent can bill `github-copilot` across several of the human's Copilot accounts instead of one. It opts in with `accountPool` in `agent.json`: ```json "accountPool": { "eligible": "work", "fleet": { "gistId": "", "user": "", "machine": "laptop" } } ``` - `eligible` is `"work"` (Microsoft accounts: GitHub Enterprise `*.ghe.com` hosts and the EMU `_microsoft` login), `"personal"` (everything else), or a list of `login@host` globs. It defaults to `"work"`. - `fleet` is optional. With it the agent reads the fleet's quota readings from that gist and publishes its own as `..quota.txt` (`{machine, agent, at, readings: [{key, leftPct, burnPerH, dryAt, overageOk, at, remaining, entitlement, reset}]}`, the shape the Copilot app balancer reads) when it has changed, at most every 30 minutes and at least every 5 hours, once its readings have loaded. GitHub allows 100 gist writes an hour per user, shared by the whole fleet, and the balancer trusts a reading for 6 hours. Switching accounts never waits on the gist. `burnPerH` is the agent's requests in the last hour summed across all its processes, which share their request times through `state/account-burn/.json` on every request. `machine` has no dots. It defaults to the name this Mac's own quota balancer uses (`last.machine` in `~/.config/mac-fleet/quota-balance.json`, e.g. `laptop`), else its `LocalHostName`, else the host name, lowercased, so a generic host name such as "Mac" never makes two machines share one file. Leave it out for an agent present on several machines: `ouro auth` stores it in the agent's vault, which every presence shares. With `accountPool` set, `ouro auth --agent --provider github-copilot` discovers the pool instead of reading one token. The accounts are the ones signed in to the Copilot app (its own database, in its order: default first, then sign-in order); without the app, the GitHub CLI's signed-in accounts. Nothing is hard-coded. Each eligible account is checked on its own host: `gh auth token --hostname --user `, then `https://api./copilot_internal/user` (`api.github.com` for github.com) for its `endpoints.api`. A token whose `login` differs is refused. The pool (tokens included) is stored in `providers/github-copilot` as `accountPool`, with the fleet token as `fleetGistToken`; `githubToken` and `baseUrl` hold the first account, so the record also works as a single-account credential. Auth prints each skipped account and why. At runtime the pool moves between accounts by quota tranche, the same rule the Copilot app balancer uses: fill each account to 30% used before moving to the next, then 60%, then 90%, then the last 10%; only after that, enterprise overage. Readings come from `~/.config/mac-fleet/quota-balance.json`, the fleet gist, and each account's own `/copilot_internal/user`, refreshed in the background every five minutes. The account is chosen when a turn's runtime is built, so a tranche move never happens mid-turn. A 401, 402 or 429 is different: the account is marked refused (until `Retry-After`; for a 402 or a quota or billing error, until the quota reset; for a 401, a rejected or revoked credential, one hour, so it costs one request an hour and a re-stored credential comes back on its own; otherwise five minutes, so a plain rate limit stays short), the pool moves to the next account at once, and that request is retried once. If no other account can serve, the original error stands. This is account selection inside one provider, not provider fallback. Every move is one JSON line in `state/account-switches.jsonl` (`at`, `agent`, `from`, `to`, `reason`: `start`, `tranche`, `401`, `402` or `429`, and the readings at the time) and a `engine.account_switched` nerves event. Pool state is kept per agent. Refusals are shared by the agent's processes through `state/account-refusals.json`, and so is the gist write cadence (`state/account-burn-published.json`, so the 30-minute floor holds for the agent, not per process), so one 402 or 429 benches an account for all of them until it can serve again. A runtime built without an owning agent, such as a daemon-side provider ping, still moves to the next account on a 402 or 429 but keeps no state, writes no switch log and publishes nothing. Run `ouro auth --agent --provider github-copilot` again (agent-runnable) after an account is added to or removed from the Copilot app. Credential verification is explicit: ```bash ouro auth verify --agent ouro auth verify --agent --provider ``` Provider credential refresh is explicit and also participates in retry: ```bash ouro provider refresh --agent ``` Refresh means: read the latest provider credential records from the agent vault, update the daemon's in-memory credential cache, and rebuild provider runtime objects only when the credential revision or provider/model binding changed. Guided integration and local-sense setup starts with: ```bash ouro connect --agent ouro connect providers --agent ouro connect perplexity --agent ouro connect embeddings --agent ouro connect teams --agent ouro connect bluebubbles --agent ouro connect voice --agent ``` `ouro connect` opens the connect bay as a shared wizard: one recommended next step, separate sections for providers, portable capabilities, and machine-local attachments, and a prompt that lets the human choose by number or name instead of remembering subcommands first. Every time the root connect bay opens, Ouro uses the shared provider credential read and live ping machinery, but with an orientation policy: one live attempt, a short hard timeout, and no provider-lane mutation. That keeps the menu truthful without spending the full startup retry budget before the human can choose a setup task. `ouro up`, `ouro check`, `ouro auth verify`, and chat startup still own full provider retry behavior. Portable capabilities with saved keys, such as Perplexity search and memory embeddings, are live-checked there too. Before the menu appears, Ouro prints a short `checking current connections` progress step while it verifies providers and reads portable and machine-local runtime settings. If a provider is slow, that step says which provider/model is being checked and then routes the quick failure into the menu as `needs attention` instead of leaving the terminal looking dead. Guided connectors open with a short capability guide that answers three questions up front: what this unlocks, what the human needs, and where the credential will live. They close with the same shared outcome guide language used by auth, vault, and hatch: a calm title, `What changed`, and `Next moves`. When a human runs bare `ouro` in a TTY, Ouro opens the same command family from the home deck instead of silently behaving like `ouro up`. The home deck routes into `ouro up`, `ouro connect`, `ouro repair`, `ouro chat`, `ouro hatch`, and help without requiring the human to remember exact command names first. `ouro connect providers` routes into the same provider auth flow as `ouro auth`, but from the connect bay instead of making the human remember the auth command first. `ouro connect perplexity` connects Perplexity search. It prompts for the API key without echoing it, stores `integrations.perplexityApiKey` in `runtime/config`, and runs a live Perplexity probe before claiming the capability is ready. `ouro connect embeddings` connects memory embeddings. It prompts for the OpenAI embeddings API key without echoing it, stores `integrations.openaiEmbeddingsApiKey` in `runtime/config`, and runs a live embeddings probe before claiming the capability is ready. `ouro connect teams` connects the Teams sense. It prompts for `teams.clientId`, `teams.clientSecret`, `teams.tenantId`, and optional `teams.managedIdentityClientId`, stores them in `runtime/config`, and enables `senses.teams.enabled` in `agent.json`. Bot credentials and proactive delivery do not prove conversational ingress. Verify the bot registration's endpoint separately from the local receiver and its public route. For an existing supervised local quick tunnel, use the controller described in `scripts/teams-sense/README.md`; a living Cloudflare process or a printed hostname can conceal a permanently rejected tunnel. Conversational diagnostics correlate `inboundActivityId`, conversation, bot and tenant identifiers through received, admitted, running and reply/failure stages, without logging message bodies. `reply_emitted` is explicitly unconfirmed stream output; `replied` requires a returned outgoing activity ID. Neither is a substitute for operator-led live acceptance of a new request in the actual Teams conversation. `ouro connect bluebubbles` is the standard setup for this machine's BlueBubbles attachment. It prompts for the local server URL, app password, webhook listener settings, stores them in `runtime/machines//config`, enables `senses.bluebubbles.enabled` in `agent.json`, and sets up host continuity. For a same-user bridge, Ouro installs or verifies the native-compatible `com.bluebubbles.server` LaunchAgent. For a bridge in another logged-in macOS account, Ouro installs a generic helper and returns one nonce-bound `human-required` Terminal command plus a matching `ouro bluebubbles host collect --request-id ` command; it never requests, stores, or logs that account's login password. BlueBubbles sends iMessages as whichever Apple ID is signed in to the macOS account its server runs under, so each agent declares that account in `agent.json` as `senses.bluebubbles.hostUsername` (for example `"bluebubbles": { "enabled": true, "hostUsername": "clawdbot" }`). Ouro itself may run in that account or in another one. Before anything that acts as the Apple ID (sending, editing, typing indicators, read receipts, and the sense health check), the BlueBubbles client asks the server which account it runs under (`computer_id` in `/api/v1/server/info`) and refuses unless it is the declared host; every send asks again rather than reusing an earlier answer. Listening is gated the same way: the sense registers its webhook only on a server running under the declared host, rechecks before taking in each incoming webhook event and drops it (HTTP 403) when that cannot be confirmed, and reading messages from the server (catch-up, queued recovery, message lookups, `ouro bluebubbles replay` and `context-smoke`) is refused the same way, so the agent never takes in another account's iMessages. Queued messages stay queued until the account is confirmed. This applies to the BlueBubbles sense, the agent's `send_message` tool and RSVP sends alike. The daemon does not start the sense, and the agent does not see BlueBubbles as ready, until a host account is declared. `ouro connect bluebubbles` asks for the account by name, never defaults it to whoever runs the command, refuses an account that differs from an already declared host, and records it before installing anything. `ouro bluebubbles host install|repair` refuses any account that no BlueBubbles-enabled agent declares; `status` and `remove` stay available so a wrong account can be inspected and cleaned up. `ouro doctor` fails when the host account is missing, and its webhook check fails when the server runs under another account. Choosing `hostUsername` is a human decision, because it chooses whose Apple ID the agent speaks as. ### Sanctuary Jellyfin catalog access The Sanctuary media-optimization read uses one dedicated Jellyfin user, not an administrator API key and not a Jellyfin database scrape. In Jellyfin's Users dashboard, create a user for your Butler, leave administrator access off, disable access to all libraries, and grant exactly the Movies and TV libraries. Disable all devices and allow only the Butler's device id: its name from `house/house.json` as a lowercase slug followed by `-sanctuary` (for example `the-butler-sanctuary` for "the Butler"). Keep playback, transcoding, remuxing, conversion, remote access/control, live TV, public sharing, deletion, download, and management permissions off. Signing in or issuing a token is `human-required` because it can involve the Jellyfin dashboard and secret entry. Store the dedicated user's ID, exact two library IDs, and access token in Sanctuary's existing machine-scoped vault config from inside the canonical Butler container. The nonsecret IDs may use `--value`; omit `--value` for the token so the CLI reads it through its hidden prompt instead of command history: ```sh docker exec -it ouro-butler node /opt/ouro/dist/heart/daemon/ouro-entry.js vault config set --agent sanctuary --scope machine --key jellyfin.userId --value '' docker exec -it ouro-butler node /opt/ouro/dist/heart/daemon/ouro-entry.js vault config set --agent sanctuary --scope machine --key jellyfin.folderIds --value ',' docker exec -it ouro-butler node /opt/ouro/dist/heart/daemon/ouro-entry.js vault config set --agent sanctuary --scope machine --key jellyfin.accessToken ``` Run `docker exec -it ouro-butler node /opt/ouro/dist/heart/daemon/ouro-entry.js vault config status --agent sanctuary --scope machine` and verify that it reports the field names `jellyfin.userId`, `jellyfin.folderIds`, and `jellyfin.accessToken` without printing their values, then use the existing `ouro-butler` container/runtime refresh or restart path. Do not run a separate host-native `ouro up`. Ask the butler to inspect media storage after the container is healthy. A successful read verifies live that the configured Jellyfin identity is enabled, non-administrative, restricted to the exact configured libraries and Butler device, and unable to use the disabled capabilities before reading the catalog. Jellyfin uses only fixed GET endpoints and omits `userId` from `/Items` so the token's own scope applies. If the optional `jellyfin` attachment is absent, Sanctuary still starts and the read returns Unmanic evidence with Jellyfin marked unavailable. Unmanic uses fixed read endpoints plus its one read-shaped `POST /unmanic/api/v2/pending/tasks`, with a fixed bounded body. The result labels every upstream string as untrusted metadata, tells the agent never to follow instructions embedded in it, and never returns tokens, user IDs, item IDs, source IDs, or filesystem paths. To rotate the credential, issue a replacement token for the same restricted user, replace `jellyfin.accessToken` through the hidden container vault prompt, refresh the existing container runtime, verify the media read, and then revoke the old token. For immediate rollback, disable or delete the dedicated Jellyfin user and revoke its token; the Butler will retain Unmanic evidence and report Jellyfin as unavailable. Never put either token in a committed file, shell argument, log, or chat message. After the listener binds, connect reconciles exactly one machine-and-agent-owned BlueBubbles `[*]` webhook. The running sense repeats the bounded, single-flight reconciliation every 180 seconds, preserves unrelated callbacks, and creates the desired callback before deleting a stale owned one. If the listener or BlueBubbles API is unavailable, the connector reports saved-but-incomplete instead of claiming success. `ouro doctor` reports whether the owned webhook is exact, missing, drifted, API-unreachable, or auth-failed without printing the secret-bearing callback URL. `ouro bluebubbles host status --json` reports app, plist/service, process, and HTTP health separately; cross-user launchd receipts are point-in-time evidence, not current serving proof. An exact webhook plus a healthy upstream proves configuration and reachability, not that a person recently wrote. With no recent inbound event, doctor reports quiet/unverified and does not synthesize an inbound message. Repair actual host or webhook faults through the standard `ouro connect bluebubbles --agent ` path; do not create a fake message merely to turn quiet evidence green. If Ouro is already running, the connector recycles the daemon once so the local listener starts with the freshly saved machine attachment; if Ouro is not running, the next `ouro up` loads it. The attachment and host setup are machine-local and do not make that Mac Messages bridge portable to every machine. `ouro connect voice` describes the current voice foundation and the required config fields. Voice is one sense with multiple transports. Spoken voice belongs to the agent's identity, but the product should expose one coherent current phone voice rather than asking people to reconcile multiple provider voices. `voice.openaiRealtimeVoice` is the current native Realtime phone voice, `voice.openaiRealtimeVoiceStyle` is the spoken identity target applied from the first audible greeting, and `voice.openaiRealtimeVoiceSpeed` is a small cadence nudge. ElevenLabs TTS credentials (`integrations.elevenLabsApiKey` and `integrations.elevenLabsVoiceId`) remain portable runtime config for the legacy cascade path, not a second canonical phone identity. Whisper.cpp STT uses this machine's `voice.whisperCliPath` and `voice.whisperModelPath` in `runtime/machines//config`. Enabling `senses.voice.enabled` gives the agent first-class `voice` sessions; those sessions are transcript-first and appear in Ouro Mailbox as text. Meeting links have URL intake plus BlackHole/Multi-Output readiness checks. The managed Twilio phone transport attaches to the Voice entrypoint when this machine has `voice.twilioPublicUrl`; its default managed route is `/voice/agents//twilio/incoming`. `voice.twilioTransportMode=record-play` keeps the conservative Twilio Record -> Whisper.cpp -> voice session -> tool-delivered `speak`/`settle` text -> ElevenLabs -> Twilio Play path. `voice.twilioTransportMode=media-stream` can run the cascade stream path or `voice.twilioConversationEngine=openai-realtime`. Native Realtime paths route Twilio audio through OpenAI Realtime speech-to-speech, use a compact voice-native identity prompt with recent transcript instead of the full general prompt, expose action tools plus `voice_end_call` and `voice_play_audio`, and keep turn detection separate from permission to speak by using Ouro floor-control over manual `response.create`. That floor-control contract is replayable: trace fixtures can assert floor-state and speech-policy events before a transport change reaches a live call. `voice.twilioConversationEngine=openai-sip` is the preferred low-latency inbound phone path when a phone-number transport can speak SIP: Twilio answers the existing number and returns `` to OpenAI's project SIP endpoint, OpenAI sends `realtime.call.incoming` webhooks to Ouro at `/voice/agents//sip/openai`, and Ouro verifies, accepts, monitors, transcripts, tools, and hangs up the call while keeping the same stable voice session. When SIP is paired with `media-stream`, outbound defaults to native OpenAI Realtime Media Streams to avoid the current Twilio outbound `` post-pickup ringback; `voice.twilioOutboundConversationEngine` may override that default. Voice phone transports resolve known callers through the canonical friend record, preferring an existing explicit friend id and otherwise matching normalized phone numbers with `imessage-handle`, so trust and tool permissions stay consistent with text and mail. SIP exposes `voice_end_call` and model-rendered `voice_play_audio` tone cues; arbitrary URL/file clip bytes still need a media bridge such as a Twilio Conference/SIP mixer before the transport can inject raw audio while keeping the Realtime leg alive. Twilio phone sessions are keyed to the stable phone voice channel (friend/caller plus dialed line when available), while CallSid/OpenAI call id stay transport metadata for per-call artifacts. `voice.twilioPlaybackMode=buffered` remains available for local Record/Play compatibility testing. Live browser join/injection remains a handoff edge until provider automation lands. Ouro Workbench is a local machine sense for terminal/TUI agents, but it is not enabled by a synced `agent.json` entry. When the native Workbench app launches a boss agent, it starts `ouro acp-serve --agent --workbench-mcp`, which injects the `ouro_workbench` tools for that served turn without writing `senses.workbench.enabled` or `mcpServers.ouro_workbench` into the bundle. The native app supplies the exact Bun executable, bundled cmux CLI, live control socket, and inherited cmux socket capability as turn-local MCP environment; the daemon forwards only those four values to the MCP child and does not journal them. The authoritative active signal is the presence of `workbench_*` tools in that turn. `ouro connect workbench --agent ` verifies the installed `OuroWorkbenchMCP` binary and removes stale Workbench bundle entries left by old setups; it does not persist a Workbench server or sense. A leftover `senses.workbench: { enabled: false }` reads as disabled, not stale. Workbench setup does not require provider secrets beyond the selected boss agent's existing vault-backed provider lanes; browser login, MFA, raw secret entry, and Apple Developer notarization remain human-required when they are actually needed. When a CLI auth/connect/vault repair command mutates the bundle, such as writing vault coordinates or enabling BlueBubbles in `agent.json`, Ouro runs the existing bundle sync path if `sync.enabled` is true. A successful command stays successful even if the bundle push fails, but the output includes a compact `bundle sync` line so the human and agent know whether the bundle change reached the remote. Low-level runtime fields can still be stored directly: ```bash ouro vault config set --agent --key teams.clientSecret ouro vault config set --agent --key integrations.perplexityApiKey ouro vault config set --agent --key bluebubbles.password --scope machine ouro vault config set --agent --key integrations.elevenLabsApiKey ouro vault config set --agent --key integrations.elevenLabsVoiceId ouro vault config set --agent --key voice.openaiRealtimeVoice ouro vault config set --agent --key voice.openaiRealtimeVoiceStyle ouro vault config set --agent --key voice.openaiRealtimeVoiceSpeed ouro vault config set --agent --scope machine --key voice.openaiRealtimeVadSilenceDurationMs ouro vault config set --agent --key voice.whisperCliPath --scope machine ouro vault config set --agent --key voice.whisperModelPath --scope machine ouro vault config set --agent --key voice.twilioAccountSid ouro vault config set --agent --key voice.twilioAuthToken ouro vault config set --agent --key voice.twilioPublicUrl --scope machine ouro vault config set --agent --key voice.twilioBasePath --value /voice/agents//twilio --scope machine ouro vault config set --agent --key voice.twilioPort --value 18910 --scope machine ouro vault config set --agent --key voice.twilioTransportMode --value media-stream --scope machine ouro vault config set --agent --key voice.twilioPlaybackMode --value stream --scope machine ouro vault config set --agent --key voice.twilioGreetingPrebufferMs --value 12000 --scope machine ouro vault config set --agent --key voice.twilioConversationEngine --value openai-sip --scope machine ouro vault config set --agent --key voice.twilioOutboundConversationEngine --value openai-realtime --scope machine ouro vault config set --agent --key voice.openaiSipProjectId ouro vault config set --agent --key voice.openaiSipWebhookSecret ouro vault config set --agent --key voice.openaiSipWebhookPath --value /voice/agents//sip/openai --scope machine ``` The values are written into the selected vault item and are not printed back. Prefer `ouro connect` for guided setup when it exists; use `vault config set` for fields that do not have a guided connector yet. ## Vault Items, Managed Workflows, And Bindings The primitive is a vault item / credential: a private record in the owning agent vault with a stable item name/path, hidden secret material, optional public fields, freeform notes, folder-ish organization, timestamps/provenance, and no assumed use. Everything else lives outside that item. ### Managed workflow `ouro connect` is not a generic password-manager entry tool. It is reserved for harness-managed workflows whose runtime behavior Ouro owns: model providers, portable integrations, local sense attachments, and Agent Mail. A credential should get an `ouro connect ` flow only when the harness can explain the capability, store it in a known runtime location, verify it, repair it, and apply the resulting runtime state. ### Freeform vault item Use freeform vault items when an agent or human needs to store a credential or secret without teaching Ouro a new capability: ```bash ouro vault item set --agent --item --secret-field [--public-field ] [--note ] ouro vault item set --agent --item --template porkbun-api ouro vault item status --agent --item ouro vault item list --agent [--prefix ] ``` Templates are convenience only. A template may shape hidden prompts and field names, but it does not create a new credential species. `--template porkbun-api` stores an ordinary vault item with hidden `apiKey` and `secretApiKey` fields. Notes are for humans and agents. Code must not parse meaning out of notes. Notes can explain what the item is, what not to assume, how it was obtained, who can rotate it, and recovery hints. If a workflow needs machine-readable facts, put them in explicit workflow binding fields or committed non-secret run config, not prose. ### Binding / run config A binding is non-secret configuration that says a workflow should use a specific vault item for a specific task. For example, a DNS workflow binding may say: ```yaml domain: ouro.bot driver: porkbun credentialItem: ops/registrars/porkbun/accounts/you@example.com resourceAllowlist: - ouro.bot ``` That binding does not make the referenced vault item a DNS credential, provider credential, ops credential, or authority. It only says this workflow plans to use that ordinary item through this driver and allowlist. The older Porkbun helper remains as a deprecated compatibility alias: ```bash ouro vault ops porkbun set --agent --account ouro vault ops porkbun status --agent --account ``` It should store and report an ordinary vault item, then point humans and agents toward `ouro vault item set --template porkbun-api`. ## Human CLI Progress Human-facing commands must not turn into a wall of text or a silent blinking cursor. Any command that may wait on browser login, vault IO, daemon startup, daemon restart, provider live checks, or guided connector setup should use the shared checklist progress surface. The checklist contract is: - start with the fewest words that orient a non-terminal user - print or animate the active step when work may take more than about three seconds - show changed substeps such as `reading vault items`, `storing openai-codex credentials`, or `opening credential vault` - for daemon replacement, say that Ouro is replacing the running background service and keep the step unresolved until the replacement is actually answering - complete with a compact success/failure summary, `What changed`, and a `Next moves` landing - never print raw secrets, OAuth tokens, provider API keys, vault unlock secrets, or machine-local passwords TTY help/readiness surfaces should share one visual language instead of every command inventing its own transcript. The shared board layer is the intended human surface for `ouro`, `ouro up`, `ouro connect`, `ouro auth verify`, `ouro repair`, `ouro help`, `ouro whoami`, `ouro versions`, and the `ouro hatch` welcome shell. Non-TTY and automation paths should stay compact plain text. Agent-runnable shortcuts may stay compact when they are intended for automation and already return structured results. Human-choice and human-required flows should choose friendliness over terseness. ## Runtime Caching The remote vault is not in the hot path. Normal model calls use this path: ```text LLM request -> in-memory provider runtime -> provider API ``` They must not use this path: ```text LLM request -> Bitwarden/Vaultwarden -> provider API ``` The daemon may read the vault at these boundaries: - daemon startup - `ouro vault unlock` - `ouro auth` - `ouro auth verify` - `ouro provider refresh` - `ouro use` provider/model checks - `ouro connect` - one bounded refresh attempt during provider failure retry The daemon should keep provider and runtime credentials only in process memory after loading them. There is no local provider-key or runtime-secret cache on disk. The vault remains the credential source of truth. The daemon reads the vault once at startup (`runtime/config`, this machine's `runtime/machines//config` and the selected providers, all from one vault listing) and hands its managed agent workers and senses a bootstrap over IPC: the items it loaded, plus `absent` for the items the vault said don't exist. A child asks the vault itself only for an item the bootstrap didn't settle (never read, or the vault was unreachable). Each vault ask spawns the vault CLI, which costs seconds and over 100 MB on a small machine, so a child normally starts without one. ## Failure And Repair Provider failure handling should use the same shared repair model everywhere: CLI errors, `ouro up`, `ouro status`, start-of-turn provider visibility, and prompt guidance. The retry ladder is: 1. A provider request fails. 2. Classify the failure, but still treat it as eligible for bounded retry because failures can be misleading. 3. Clear the provider runtime cache for the affected lane. 4. Refresh provider credentials from the agent vault into the daemon's in-memory credential cache. 5. If the credential revision or provider/model binding changed, rebuild the provider runtime. 6. Retry the request within the bounded retry policy. 7. If it still fails, mark the lane degraded and surface exact repair guidance. ### Vault outage at daemon startup If the vault does not answer at all (a network timeout, refused or reset connection, DNS failure) when the daemon starts, the daemon stays up instead of exiting. That agent is marked degraded as `vault:` in the daemon health file (so `ouro status`, Housesitter and Shepherd see it), and the daemon retries the vault with capped exponential backoff (5 s doubling to 5 min), clearing the state when the vault answers. No credential is cached on disk to bridge the outage: a fresh daemon process holds none, so anything that needs a secret (provider calls, runtime-config senses) stays down until the vault returns, while the rest of the daemon (process management, health, habits that need no secret) keeps running. Any other vault or local unlock-store error that is not a rejection (for example a locked macOS login keychain before first login, or a bw or server hiccup) is treated the same way and never asks a human to unlock. A vault that answers with a rejection of the saved unlock secret, a missing saved secret, or a missing or invalid credential is still fatal and human-directed. Destructive commands such as `ouro mail sweep-orphans` keep requiring a fresh vault read and never use cached credentials. Repair guidance must include an actor: - `agent-runnable`: safe for the agent to run when it has tool access, such as status, verify, and refresh commands. - `human-required`: requires browser login, MFA, provider dashboard access, API token creation, or secret entry. - `human-choice`: requires the human to decide which provider/model this machine should use. Agents may run agent-runnable checks and refreshes. Agents must not ask the user to paste secrets into chat. When repair requires a human, the agent should say why and direct the human to the terminal, browser auth flow, or provider console. Example human-required repair: ```text openai-codex / gpt-5.5 failed after refresh retry. Why I cannot fix this automatically: OpenAI Codex auth requires a human browser login or refreshed OAuth credentials. Do this in your terminal: ouro auth --agent --provider openai-codex Then verify: ouro auth verify --agent --provider openai-codex ``` Example manual API-key repair: ```text anthropic / claude-opus-5-5 has no valid credentials. Why I cannot fix this automatically: Anthropic API keys must be created or rotated by a human in the provider console. Do this: 1. Create a new Anthropic API key in the Anthropic console. 2. Run: ouro auth --agent --provider anthropic 3. Paste the key into the terminal prompt, not into chat. ``` ## Agent-Facing Knowledge Agents need compact live operational truth, not a long tutorial in every prompt. The system prompt should render a small provider section from current runtime state: ```text runtime uses provider bindings from agent.json: - outward: minimax / MiniMax-M2.5 [ready; credentials: vault] - inner: openai-codex / gpt-5.5 [failed: auth; repair: ouro auth --agent --provider openai-codex] ``` When provider readiness is degraded, prompt guidance should include: ```text If my provider is degraded, I can run agent-runnable repair commands when I have tool access. I cannot complete browser login, MFA, provider dashboard token creation, or secret entry. I never ask the user to paste secrets into chat; I direct them to the terminal/browser/provider console. ``` The full mental model lives in this doc. Runtime behavior and repair strings should be generated by shared code, not copied into prompt text, CLI text, and docs separately. ## SerpentGuide And Hatch SerpentGuide needs provider credentials to run the adoption conversation. Interactive hatch should bootstrap SerpentGuide like this: 1. Discover usable provider credentials from already installed agents whose vaults are unlockable on this machine. 2. Show where each option came from, such as `minimax from ` or `anthropic from `. 3. If no usable credentials are found, prompt the human: "No credentials found. What should your new agent use?" 4. Guide the human through provider-specific auth without asking for secrets in chat. 5. Ping-check the selected provider credentials. 6. Use the selected credentials to run SerpentGuide in memory. 7. Prompt the human outside model context for a human-chosen hatchling vault unlock secret, confirm it, and enforce the same strength rules used by `ouro vault create`. 8. Create/configure the hatchling bundle and hatchling vault. 9. Store the selected provider credentials into the hatchling vault. The hatchling vault unlock secret is not generated, printed, included in tool arguments, or sent through chat. The terminal secret prompt does not echo it and asks for confirmation. The human must save the hatchling vault unlock secret outside Ouro if they want to unlock that new agent on another machine. Interactive hatch must not create, mutate, or persist a SerpentGuide vault. Persistent SerpentGuide provider credentials are not a supported state: there is no durable human-custody path for a SerpentGuide vault unlock secret, and a packaged bootstrap specialist should not become a hidden credential owner. Direct/noninteractive hatch may accept explicit provider credentials to run the flow, but must store them in the hatchling vault only. If the flow needs to create a hatchling vault, the human provides the unlock secret: either at a non-echoing prompt with confirmation, or, for an unattended setup with no terminal, in a file the human wrote. Ouro never generates or prints one. An unattended hatch reads everything from files, so no secret appears in argv or shell history: ```bash ouro hatch --answers ./hatch.json --secret-file /dev/fd/3 --no-chat 3< ./unlock-secret ``` `hatch.json` holds `{"agentName", "humanName", "provider", "credentials": {...}}` (the same credential fields as the hatch flags). The secret file is read once and must meet the `ouro vault create` strength rules. The hatch creates the hatchling's vault and saves its local unlock before storing credentials, then starts the daemon. With `--answers`, nothing is prompted: anything missing is a usage error. `--no-chat` skips the first chat. `ouro vault unlock|create|replace|recover --secret-file ` work the same way. ### Vault account registration Hatch and `ouro vault create` register the vault account with the current Bitwarden/Vaultwarden flow: `POST /identity/accounts/register/send-verification-email` with `{ email, name, receiveMarketingEmails: false }` returns a verification token, and `POST /identity/accounts/register/finish` creates the account with that `emailVerificationToken`. Vaultwarden 2026.x removed the old single-step `POST /identity/accounts/register`; Ouro uses it only when a server returns 404 for the verification step. - If the server has signups closed, it answers "Registration not allowed or user already exists" unless the address was invited. The fix is human-required: the server admin invites the agent's email (Vaultwarden admin panel → Invite User), then the human re-runs hatch or `ouro vault create`. - If the server has mail and signup verification on, it emails a link instead of returning a token. Ouro can't finish that unattended and says so; the admin creates or invites the account with verification off, or the human finishes signup from the email. ## Continue An Existing Agent Bundle When a bundle is copied, pulled, or cloned onto a machine, the durable Ouro-owned story is bundle plus vault: 1. The bundle brings identity, vault coordinates, sync settings, and local-state templates. 2. The remote vault brings raw provider, portable runtime/integration, local machine attachment, travel, and tool credentials. 3. The remote vault does not live inside the bundle, and raw credentials do not live in the bundle. 4. Local unlock material is recreated per machine by unlocking the agent vault once. Start from the bundle remote: ```bash ouro clone ``` If the bundle already exists at `~/AgentBundles/.ouro`, start at unlock: ```bash ouro vault unlock --agent ``` Then refresh and verify what this machine can use: ```bash ouro repair --agent ouro provider refresh --agent ouro auth verify --agent ouro vault config status --agent ``` Start the daemon when the vault and provider lanes are ready: ```bash ouro up ``` Local attachments are per machine. If BlueBubbles is enabled for the agent but this computer is not attached, run: ```bash ouro connect bluebubbles --agent ``` Windows DPAPI means a CurrentUser-protected encrypted local unlock file. Windows keeps the protection keys; Ouro stores only the encrypted blob. This fits local unlock caching because the blob is usable by the same Windows user on the same machine, not as a portable credential source. Linux Secret Service is the freedesktop desktop-secret API usually backed by GNOME Keyring, KWallet, or another `libsecret` provider. It is often unavailable on headless servers, minimal Linux installs, and WSL. If the machine has no usable local secret store, the harness may offer an explicit plaintext unlock fallback in ignored local state. That fallback must be opt-in, clearly labeled, and never selected silently. A headless appliance can choose that fallback once for the whole machine: set `OURO_VAULT_UNLOCK_STORE=plaintext-file` in the environment of the ouro service and of every ouro command run there. Any store name `--store` accepts works (`auto`, `macos-keychain`, `windows-dpapi`, `linux-secret-service`, `plaintext-file`, `sealed-file`). `sealed-file` (Linux and macOS) keeps the secret in a chmod 0600 file under `~/.ouro-cli/vault-unlock-sealed`, encrypted with AES-256-GCM under a key derived from this machine's hardware identity (the device-tree serial or DMI UUID, then `/etc/machine-id` or `/var/lib/dbus/machine-id`; IOPlatformUUID on macOS), the user and the vault. A copy of the file is useless on another machine. Anyone who can run code as this user on this machine can still unseal it, so it guards against a copied file, not a compromised account. An explicit `--store` still wins, and reads and writes both follow the choice. This is a deliberate exception to the no-environment-variable policy: the store is a property of the machine, not the bundle, and hatch has no `--store` flag. Hatch, `ouro vault create`, `ouro vault replace` and `ouro vault recover` resolve the local unlock store before they create a vault account. On a machine with no usable store they stop with the store guidance and create nothing, so no orphaned vault account blocks the next attempt with "user already exists". ## Existing Agents There is no hidden recovery path for a lost vault unlock secret. For an existing agent with no vault locator, run `ouro vault create --agent `. The command prompts twice for a human-chosen vault unlock secret without echoing it, writes vault coordinates to `agent.json`, and stores local unlock material for this machine. New unlock secrets must be at least 8 characters and include uppercase and lowercase letters, one number, and one special character. The human must keep that unlock secret outside Ouro; Ouro will not print it, write a portable copy into the bundle, or store it inside the vault. For an existing agent with a vault locator and a saved unlock secret, run `ouro vault unlock --agent ` on each new machine and enter the saved agent vault unlock secret from the human/operator who controls that vault. Ouro stores only local unlock material for that machine. `ouro vault unlock` verifies the typed unlock secret against the agent vault before replacing this machine's saved local unlock material. A failed validation must not overwrite a previously working Keychain/DPAPI/Secret Service/plaintext entry. Ouro reads and writes the vault without the `bw` CLI: its own client (`src/repertoire/bitwarden-native.ts`) does the Bitwarden prelogin, a PBKDF2-SHA256 password login, `/api/sync` and the AES-256-CBC + HMAC-SHA256 encryption and decryption with Node's crypto. So a daemon reading its runtime config and provider credentials, and `ouro auth` or `ouro vault config set` writing them, start no `bw` process (each one a full Node.js process), and keep working when an endpoint security product quarantines files inside `bw`. Every store in a process shares one login and one sync; reads within 30 seconds of a sync are served from it. A write creates or updates the login item named for the credential, keeping an existing item's own key, folder, custom fields, password history and other login data exactly as stored; the server refuses it if the item changed since this process read it. Ouro then reads the item back to check it, and a delete moves the item to the trash, as `bw delete item` does. A vault this client does not support (Argon2id KDF, two-step login, new-device verification) goes through `bw` instead, and `OURO_VAULT_NATIVE_READS=0` sends reads and writes through `bw`. `@bitwarden/cli` is an optional package: an install without it (`npm config set omit optional`) finds `bw` on PATH, or installs the pinned version, only when a vault needs it. The saved unlock secret is the only durable local credential. Each agent's folder under `~/.ouro-cli/bitwarden/` holds one disposable `bw` profile per installed `bw` version (`bw-/`), so a machine with several `bw` installs (one per Node version) never shares or migrates one profile between them. When a local step fails on an authenticated profile (an unlock that fails because the profile is corrupt or half-migrated, or because its session is missing), Ouro moves the profile aside and logs in fresh once with the saved unlock secret, without asking the human. Server steps (login, sync), network errors, rate limits, gateway errors, lock contention and rejected secrets never discard a profile, so a bad secret or a flaky server costs at most one server login. When the vault rejects the saved unlock secret, Ouro keeps the saved entry and writes a private rejection record (`.ouro-unlock-rejected`, mode 0600) in the agent's `bw` folder. Every process honors the record and stops logging in with that secret, and reports `ouro vault unlock --agent ` as the repair. Saving a secret with `ouro vault unlock` (even the same one) or any successful login clears the record. Ouro never deletes saved unlock material automatically, because a misclassified error would otherwise turn into a human prompt. Legacy local unlock entries may be read for compatibility, but they are copied to canonical vault coordinates only after a successful vault login. For an existing agent whose `agent.json` already has vault coordinates but whose unlock secret was not saved or is lost, Ouro cannot recover it from the remote vault or expose it from Keychain, DPAPI, Secret Service, or plaintext fallback. The repair is to create a replacement agent vault and re-auth/re-enter credentials into it. Use `ouro vault replace --agent ` only when the bundle already has vault coordinates and there is no local credential export to import. By default it uses the stable agent vault email, `@ouro.bot`; it does not invent timestamped `+replaced` addresses. It creates an empty vault, writes vault coordinates to `agent.json`, stores local unlock material on this machine, and imports nothing. Use `ouro vault recover --agent --from ` only when the human still has a local JSON credential export from an earlier alpha. By default it uses the stable agent vault email and imports the JSON once without printing credential values. If the stable vault account already exists, the command stops. If the human has the unlock secret, run `ouro vault unlock --agent `. If the unlock secret is truly lost and the operator intentionally wants a different vault account, only use `--email ` when intentionally moving the agent; rerun `replace` or `recover` with that explicit address. ## Old Auth-Style Agents Use this checklist for any existing agent that predates the vault-backed credential model. 1. Pull the latest bundle and harness. ```bash ouro clone ``` If the bundle is already present, pull it with normal git sync or run `ouro up` once so bundle update hooks can run. 2. Check whether the bundle has vault coordinates. ```bash ouro vault status --agent ``` If the status says `vault locator: not configured in agent.json`, the agent has not set up its vault yet. Create one: ```bash ouro vault create --agent ``` Enter and confirm a human-chosen unlock secret when prompted. The prompt does not echo the secret. Save that unlock secret outside Ouro immediately. Another machine cannot unlock this agent vault without it. After this, re-enter provider/runtime credentials with the auth and vault config commands below. 3. If the bundle has vault coordinates but nobody saved an unlock secret, choose the repair path that matches what actually exists. If there is no local credential export, create an empty agent vault: ```bash ouro vault replace --agent ``` This is the expected path for agents that already existed before provider credentials moved into per-agent vaults. Enter and confirm a human-chosen unlock secret when prompted, and save it outside Ouro immediately. The prompt does not echo the secret. The command stores vault coordinates in `agent.json` and imports no credentials. If the human does have a local JSON credential export, recover into the agent vault and import it: ```bash ouro vault recover --agent --from ``` Repeat `--from ` for each local JSON export that should be imported. Enter and confirm a human-chosen unlock secret when prompted, and save it outside Ouro immediately. The prompt does not echo the secret. The command stores vault coordinates in `agent.json`, imports provider credentials into `providers/*`, imports portable runtime/integration credentials into `runtime/config`, imports BlueBubbles local attachment fields into `runtime/machines//config`, and prints only field/provider summaries. 4. Unlock the vault on this machine. Reads and writes never need `bw` (see the vault section above), so this only affects vaults that go through `bw`. When the bundled pinned `bw` fails to load one of its own modules (an endpoint security product can quarantine a file inside it), Ouro logs `repertoire.bw_cli_bundled_broken` once and uses the `bw` on PATH for the rest of the process, with that version's own profile directory. If readiness still reports that the local Bitwarden CLI installation is incomplete, no working `bw` was found: repair the CLI selected by Ouro (the bundled copy, or install one on PATH), then run `ouro doctor` before retrying `ouro up`. A working `bw --version` on PATH does not validate Ouro's bundled copy. A missing Node.js module is a local installation failure, not evidence that the vault is locked or provider credentials are invalid. Do not replace the vault or reauthenticate providers to repair missing CLI files. Startup remains blocked until the normal credential and provider checks pass. ```bash ouro vault unlock --agent ``` If you just ran `ouro vault replace` or `ouro vault recover`, this machine is already unlocked for the agent vault; run `ouro vault status --agent ` to confirm. 5. Re-enter provider credentials into the agent vault if recovery did not import them or if they are stale. ```bash ouro auth --agent --provider ``` Repeat for every provider the agent should be able to use. Do not copy old local credential files into the bundle. Do not paste raw secrets into chat. 6. Re-enter runtime, sense, integration, travel, and tool credentials into vault items if recovery did not import them or if they are stale. ```bash ouro connect --agent ouro connect perplexity --agent ouro connect embeddings --agent ouro connect teams --agent ouro connect bluebubbles --agent ouro connect voice --agent ``` Use `ouro connect` when a guided connector exists. Use `vault config set` only for fields that do not have a guided connector yet. BlueBubbles and Voice transports are local attachments; run their connectors separately on each machine that should bridge iMessage, local audio, Twilio phone calls, or browser meeting audio. 7. Choose this machine's provider/model lanes. ```bash ouro use --agent --lane outward --provider --model ouro use --agent --lane inner --provider --model ``` 8. Refresh, verify, and start. ```bash ouro repair --agent ouro provider refresh --agent ouro auth verify --agent ouro vault config status --agent ouro up ``` 9. After vault-backed auth verifies, remove obsolete local credential artifacts by hand. They are not a supported fallback and must not be committed. ## Command Vocabulary Keep the core auth/provider vocabulary small: ```bash ouro vault unlock --agent ouro vault status --agent ouro vault replace --agent ouro vault recover --agent --from [--from ...] ouro vault config set --agent --key ouro vault config set --agent --key --scope machine ouro vault config status --agent [--scope agent|machine|all] ouro vault item set --agent --item --secret-field [--public-field ] [--note ] ouro vault item set --agent --item --template porkbun-api ouro vault item status --agent --item ouro vault item list --agent [--prefix ] ouro vault ops porkbun set --agent --account ouro vault ops porkbun status --agent [--account ] ouro connect --agent ouro connect providers --agent ouro connect perplexity --agent ouro connect embeddings --agent ouro connect teams --agent ouro connect bluebubbles --agent ouro connect voice --agent ouro auth --agent --provider ouro auth verify --agent [--provider ] ouro repair --agent ouro provider refresh --agent ouro use --agent --lane outward|inner --provider --model ``` Deprecated or compatibility command paths should not become new architecture. This harness is still alpha; prefer the simple contract over legacy shims. The `inner` lane is a provider/model lane, not the private-runtime system name. Provider/model selection belongs to `agent.json` lanes; `privateRuntime` cannot select providers or models.