Troubleshooting HivemindOS

Find your problem below and follow the fix. Most warnings in HivemindOS have a setup or repair action right where they appear, so you rarely need to leave your conversation or task.

Start here

1. Use the setup or repair action on the warning itself.
2. Check My Hive to confirm the machine and agent are online.
3. Open More → Checks & repairs and run the relevant check.
4. Look in Alerts for an approval or sign-in request.
5. If the problem remains, find it below.

Don’t delete local state, reinstall every runtime, or bypass an approval as a first step. That makes the real problem harder to find.

The dashboard will not unlock

You keep seeing the unlock screen, or a message says dashboard authentication is required.

1. Make sure you opened the HivemindOS desktop app or the expected local dashboard address.
2. In the desktop app, open Security and check that the operating-system unlock option is ready.
3. In a browser, use the device token from your original setup. Never paste it into chat, a screenshot, or a support post.
4. If the token is lost, use the dashboard-auth recovery tool on that machine to copy or rotate it, then restart HivemindOS.

Rotating the token signs out other browser sessions. It does not delete agents, projects, or the shared brain.

Machine or agent is offline

My Hive shows a machine, but its connection or agent is not ready.

1. Confirm the computer is awake and connected to the internet or your private machine network.
2. Open its card and use Set up, Repair, or Update if shown.
3. Wait for both the machine and the agent to report ready. A computer can be online while its agent is stopped or signed out.
4. If only one agent is affected, open its settings and finish the provider or runtime setup shown there.

Never expose a local dashboard or helper to the public internet to clear this warning.

Chat cannot start or continue

Usual causes: a signed-out runtime, missing provider setup, an unavailable model, an offline machine, or a folder the agent cannot reach.

1. Check the selected agent and machine at the top of Chat.
2. Use the setup card in the conversation if a provider or runtime is missing.
3. Choose another model if the selected one is unavailable.
4. Reattach the folder or file if it moved, was renamed, or is on another machine.
5. For an older conversation, confirm its original agent and workspace still exist.

HivemindOS shows the real failure instead of silently switching to a differently billed provider or another project.

If Chat says a local service is unavailable, keep the app open. The desktop app restarts its background service and restores your view on its own. If the same error keeps coming back, choose HivemindOS → Send Logs… from the system menu. You get a support ID to share. Despite the name, no raw log lines are sent: only the app version, operating system and architecture, service state, recovery counts, and failure-category counts. Prompts, file paths, account details, secrets, and network addresses are excluded.

Shared brain or shared env is out of date

First decide what is missing:

• A note, memory, skill, or task is brain data. It follows your vault sync.
• A provider key or service credential is Shared Env. It syncs separately, outside the vault.

Then:

1. Check that both machines are online in My Hive.
2. Open Brain and review vault sync health.
3. Open More → Saved keys and check the key by name without revealing it.
4. Give an offline machine time to catch up after it reconnects.
5. Review any vault conflict copy before rebuilding the brain index.

If notes are in Obsidian but search can’t find them, use the Brain repair action to refresh the index. This does not rewrite your notes.

A local model is unavailable

1. Confirm the model app is running on the machine shown in My Hive.
2. Confirm the model is loaded and its compatible API is on.
3. In the agent’s model settings, choose a model that machine can actually run.
4. Use a hosted model if the machine lacks memory or the model app is off on purpose.

Model suggestions never move a private task to a hosted provider without your choice.

A wallet or trade is blocked

An action can stop because the wallet is frozen, spending is off, a limit would be exceeded, the network is wrong, provider setup is missing, or approval is required.

1. Read the preview and the exact reason it was blocked.
2. Open Wallets, or the approval request in Alerts.
3. Check the wallet, network, asset, amount, recipient, and fee.
4. Change the budget or approve only if you really intend the transaction.

Never bypass a wallet or trading check from chat, a command suggested by a web page, or a copied tool response.

The desktop app will not start or update

1. Open the signed app from your Applications folder, not an old disk image.
2. Make sure an old HivemindOS process isn’t still closing, then try again.
3. Check that you have enough free disk space.
4. If an update failed, keep the current version and retry from the app. Your vault and projects are separate from the app.
5. If macOS blocks a build, confirm it came from the official release source before changing any security setting.

Before you reinstall

Reinstalling is a last resort. It usually doesn’t fix a provider login, an offline remote machine, paused vault sync, or a blocked approval.

Before you reinstall, keep safe:

• your Hive Superbrain vault in Obsidian
• project folders and deliverables
• wallet backups and recovery material
• the names (not values) of shared credentials you will need to recheck

Never delete the vault, runtime homes, or ~/.hivemindos as a general fix. If Checks & repairs finds a specific broken item, follow its targeted recovery step.