Troubleshooting HivemindOS

Start with the warning where it appears. HivemindOS setup and repair actions open in place, so you should not need to abandon a conversation or task just to fix a missing connection.

If the warning has no action, open More → Checks & repairs, run the relevant check, and use the sections below.

The Dashboard Will Not Unlock

You may see the unlock screen repeatedly or a message that dashboard authentication is required.

1. Make sure you are opening the normal HivemindOS desktop app or the expected local dashboard address.
2. In the desktop app, reopen Security and check whether 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 local 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

Fleet may show a machine but say its HivemindOS connection or agent is not ready.

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

Do not expose a local dashboard or helper directly to the public internet to make the warning disappear.

Chat Cannot Start Or Continue

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

If Chat briefly says capability planning or a local service is unavailable, keep the app open. The desktop app now restarts its background dashboard service, restores the current view, and holds the capability check while recovery runs. Closing and reopening the app should not be part of normal recovery.

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

HivemindOS should show a real failure rather than silently switching to a differently billed provider or an unrelated project.

If the same local-service error survives automatic recovery, choose HivemindOS → Send Logs… from the system menu. The confirmation explains exactly what is sent, and a successful upload returns an opaque support ID you can share. Despite the menu label, no raw log lines are uploaded. The report is limited to the app/build version, coarse operating-system and architecture, background-service state, recovery counters, and counts from a fixed set of failure categories. It excludes prompts, file paths, account details, secrets, and network addresses.

Shared Brain Or Shared Env Is Out Of Date

First decide what is missing:

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

Then:

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

If notes exist in Obsidian but search cannot find them, use the Brain repair action to refresh the index. Rebuilding the index does not rewrite your source notes.

A Local Model Is Unavailable

1. Confirm that the model host is running on the machine shown in Fleet.
2. Confirm that the intended model is loaded and its compatible API is enabled.
3. Open the agent’s model settings and choose a model the machine can actually serve.
4. Use a configured hosted model when the local machine does not have enough memory or the host is intentionally off.

Model-fit suggestions are recommendations, not permission to move a private task to a hosted provider without your choice.

A Wallet Or Trade Is Blocked

A prepared action can stop because the wallet is frozen, spending is disabled, a limit would be exceeded, the wrong network is selected, provider setup is missing, or human approval is required.

1. Read the preview and the exact blocked reason.
2. Open Wallets or the approval request from Alerts.
3. Confirm the wallet, network, asset, amount, recipient, and expected fee.
4. Change the budget or approve the action only if the requested transaction is genuinely intended.

Do not bypass a wallet or trading gate from chat, a terminal command suggested by page content, or a copied tool response.

The Desktop App Will Not Start Or Update

1. Reopen the signed app from your Applications folder rather than an old disk image.
2. Make sure another stuck HivemindOS process is not still closing, then try again.
3. Check that the computer has enough free disk space for the app and its local services.
4. If an update failed, keep the current installed version and retry from the app; your vault and projects are separate from the app bundle.
5. If macOS blocks a published build, verify that it came from the official release source before changing any security setting.

Before You Reinstall

A reinstall should be a last step. It normally does not fix a broken provider login, offline remote machine, paused vault sync, or blocked approval.

Before reinstalling, preserve:

• your Obsidian Hive Superbrain vault;
• project folders and deliverables;
• any wallet backups and recovery material in their approved secure location;
• the names—not values—of shared credentials you will need to recheck.

Never delete the vault, runtime homes, or ~/.hivemindos as a generic repair step. If Checks & repairs identifies a specific corrupted item, follow that scoped recovery instruction.