HivemindOS manual
Shared env values
Save credentials in PassBook so HivemindOS can use them for connected services and approved agent tasks. Values stay outside the Obsidian vault and chat. Notes in Operations/Secure/ may describe key names and availability, but must never contain the values.
Add a credential in HivemindOS
- Open Brain, choose Settings, then Secrets, and select Set up secure keys. A task that needs a key can also open setup where you are working.
- Choose a workspace. HivemindOS (your existing keys) secures keys already saved on a fresh installation. With an existing PassBook setup, choose its workspace or Create a HivemindOS workspace to keep these keys separate.
- Confirm with your PassBook password, or create and confirm a password for a new vault. Keep this password safe for future unlocking and recovery.
- Review Keep approved tasks running in the background, then choose Connect PassBook. Background access is selected when this device supports it; setup explains when it is unavailable. Connecting authorizes HivemindOS and its connected services. Agent operations still need their own permission.
- Under Workspace keys, choose Add key, enter the requested name and value, confirm your PassBook password, and choose Save key. Saving alone does not grant an agent access. Replace key requires an explicit replacement confirmation.
On a local browser or the desktop app, you can instead choose Authorize in PassBook app, then Prepare app authorization and Open PassBook to authorize. Match the displayed code in both windows before choosing the workspace and approving in PassBook. Your password stays in that app. If it cannot open, use the password form in HivemindOS. This handoff authorizes the displayed connection; its application label is not proof of a publisher’s identity.
Approve an agent’s work
Key requests appear under Needs your approval in the Inbox and can open in a review popup. These surfaces show the same request. Check the agent, workspace, device, requested keys, operation, destination, and expiry before choosing Review access.
- For this task is the default. Once permits one use of the displayed operation.
- Remember for … and this key keeps permission for that agent and the selected keys. It starts unchecked.
- More access options includes Allow this agent to use all keys in this workspace. This also starts unchecked and includes future keys. Service and action restrictions still apply; other agents and workspaces are excluded.
Confirm the chosen decision with your PassBook password, or an available enrolled passkey in a supported browser. Initial vault setup still needs a password. If a key is absent, Add key and review opens a secure input; Save key and allow saves it and approves the reviewed operation without sending the value to chat.
The waiting task can then resume the same operation. Denied, expired, or cancelled requests do not grant access; an expired request needs a new review. Closing a popup does not approve it, and marking a notification read does not resolve the request.
Understand a key’s state
| State | What to do |
|---|---|
| Missing | Add the requested key through secure key entry. |
| Locked | Unlock the connected workspace. The key already exists; do not add another copy. |
| Waiting for approval | Review the agent’s requested operation. |
| Refused | Review the applicable permission or policy. Re-entering the same key will not help. |
| Paused | Open Review connection and choose Resume background access when you want access to continue. |
| Disconnected | Reconnect PassBook. Saved keys remain protected; disconnecting does not restore legacy access. |
A key whose value cannot be displayed may still be usable through an approved operation. If setup offers Finish PassBook update, use that repair and retry any interrupted credential operation.
Keep approved tasks running
Background access lets this device use already approved keys while you are away, without a separate terminal sign-in for every task. It requires supported secure storage on the device and working background startup. A connection warning means startup needs attention; it is not a ready background connection.
Open Review connection to Pause background access, inspect Agent permissions, or Revoke access. Disconnect this application stops new HivemindOS access on this installation while leaving saved keys in PassBook. These controls cannot undo a completed operation or erase a value already received by another machine.
Use keys on another machine
On the receiving device, choose Use keys from another machine. Select a linked source machine and the destination workspace, then choose Review keys. The source’s connected workspace is shown for review; choosing it does not switch that machine to another workspace.
Select the keys, confirm the source and receiving PassBook passwords, and review background access. Keep these keys updated from this machine is selected by default and covers only the chosen names, never new keys added later. Confirm Connect HivemindOS to this workspace and receive these keys, then choose Connect and receive keys. Values transfer encrypted without copying credentials or transfer documents through chat.
If this device has encrypted keys but has lost the profile needed to open them, setup requires all listed recovery keys from a usable source. It reports a missing source key rather than silently creating an empty replacement workspace.
Ongoing updates have these limits:
- Updates flow one way from the chosen source, about every 10 minutes while both devices are available and their PassBook access is ready.
- Permission lasts 30 days and needs fresh approval after expiry. Connected key sources shows its status and expiry; use Review connection to approve it again or Stop updates to end updates.
- Existing usable local keys are kept during receipt. Later local edits are preserved rather than overwritten automatically.
- Removing a key at the source keeps the receiving copy. Stopping updates, expiry, or disconnecting also leaves already received keys in place. Remove an unwanted receiving copy separately through PassBook.
- Receiving a key does not approve an agent to use it. Machine updates and agent permissions are separate decisions.
Supported credential use
HivemindOS-managed agents use credential tools for approved HTTPS operations; they do not receive the shared secret as a shell variable. Supported HivemindOS launches of Hermes and JCode can also use the selected catalog model through a protected connection without inheriting its provider key. Provider account sign-in and external runtimes still follow their supported setup paths; connecting PassBook does not make every arbitrary runtime compatible.
Managed workspaces refuse plaintext exports and arbitrary commands that would hand credentials to an agent process. Do not repair a refusal by reading the store, copying keys into runtime files, or falling back to an older helper. These controls govern supported operations; they do not isolate unrestricted code running under your operating-system account.
Open the credential tools and legacy helper reference
Credential tools for managed agents
HivemindOS provides credential_request, credential_status, and credential_use. They identify the requesting agent and route approval to the owner. Resume an operation with the same idempotencyKey after approval instead of creating duplicate requests. passbook mcp uses the installed agent connection when available and exposes managed use and status tools. Neither path requires the owner to paste a key into chat.
Legacy tools such as passbook get, passbook run, run_with_credentials, and the old proxy_request are not substitutes for managed credential use. A managed refusal applies even if a legacy command worked before connection.
Storage and unconnected stores
The default store remains ~/.hivemindos/.env, or the configured HIVE_HOME location. PassBook owns encryption and access to a connected workspace. The Obsidian vault holds searchable knowledge, not plaintext credentials. Agents and app integrations should use credential tools rather than read the store file.
An installation that has not connected its store to managed PassBook retains the legacy Shared Env workflow. The following reference applies only to those unconnected stores and trusted programs:
hive-env-add OPENAI_API_KEY
hive-env-check OPENAI_API_KEY
hive-env-remove OPENAI_API_KEY
hive-env-delete OPENAI_API_KEY
hive-env-run -- pnpm dev
hive-env-add KEY prompts for a value without putting it in command history. hive-env-check KEY checks status without printing a value. hive-env-remove and its alias hive-env-delete remove a named key. hive-env-run supplies credentials to a trusted child program, subject to PassBook policy when installed. Giving a program the real value does not prevent that program from disclosing it.
In the legacy workflow, a value already set by the project or shell takes precedence over the shared default. This is not permission for a managed agent to create a plaintext project override. Legacy runtime-file integration, private AEON repository secret publishing, and Hivemind Sync do not bypass managed workspace restrictions.
Legacy sync-enabled stores retain their configured push/retry and periodic reconciliation behavior. Operators can use hive-env-add --retry-pending or hive-env-add --pull-reconcile --dry-run to inspect that workflow. For a managed workspace, use Use keys from another machine and Connected key sources instead; the legacy mutation and replication helpers refuse access.
Encrypted backup
For a managed workspace that cannot open its encrypted keys, use the verified machine recovery flow described above when a usable source is available. Legacy backup commands do not bypass managed access restrictions. In the legacy workflow, configured GPG backups may be stored as Operations/Secure/hive.env.gpg. Only the encrypted backup belongs in the vault; plaintext exports, secrets in notes, and credentials in screenshots or logs do not.