HivemindOS manual
API and storage reference
This page lists the dashboard’s API route groups, the collector and hosted-service endpoints, and where HivemindOS saves state on disk. Use it to find which route owns a workflow or where a piece of data lives.
For the big picture, start with How HivemindOS works.
Dashboard API route groups
The dashboard’s local API serves these route groups. They require dashboard auth, except a few routes that check their own credentials, such as signed media links.
| Route group | Purpose |
|---|---|
/api/agents/* |
Agent status checks, runtime agent creation/deletion, folder browsing |
/api/app/version |
App version and checkout metadata |
/api/brain/gbrain/* |
GBrain status, install, connect, import, embed, dream, and query |
/api/brain/synto/* |
Syntho status, install, connect, init, run, maintain, compare, eval, doctor, pack export, and query |
/api/brain/trading-brain/* |
Trading brain status and install |
/api/chat/* |
Agent chat, runtime chat stream, session reads, chat folder persistence |
/api/control-room/status |
Control-room path and setup status checks |
/api/crypto/* |
Crypto rail readiness, clear-signing reviews, local agent identity records, and offline crypto risk checks |
/api/env |
Shared and runtime-specific env listing/import/update |
/api/fleet/* |
Fleet discovery, snapshots, updates, app/service discovery, app icons, machine init, and Hetzner setup helpers |
/api/gitlawb/* |
GitLawb Code Proof CLI, DID, node health, and setup status |
/api/honey-ledger |
Honey ledger reads, local observation submission, exchange actions |
/api/integrations/github/oauth/* |
GitHub OAuth fallback that saves GH_GLOBAL for AEON |
/api/integrations/connections |
App connections: live provider status, token save, disconnect |
/api/kanban |
Board CRUD, task lifecycle, comments, claims, runs, and events |
/api/kanban/deliverable |
Open/reveal completed task deliverables |
/api/machines/directories |
Machine-aware directory discovery |
/api/maintenance |
Maintenance report and repair actions |
/api/memory-telemetry |
Dashboard/process memory telemetry |
/api/miroshark/* |
MiroShark companion status, install/start, swarm, run, and analysis flows |
/api/note-intake |
Import note-derived tasks into Kanban |
/api/obsidian/* |
Vault status, note open/access, graph, sync, skills, wallets, aliases, recent directories |
/api/orchestrator/* |
Orchestrator route/event surfaces |
/api/phone |
Phone gateway config/status, scheduled ring prompts, ring-agent actions, dashboard agent calls, and phone media generation |
/api/projects/* |
Hivemind project registry and GitLawb repo linking |
/api/runtime-files |
Safe runtime/app file roots, listing, read, and write |
/api/runtime-usage |
Runtime usage analytics for supported runtimes |
/api/runtimes/* |
Generic runtime facade (see below) |
/api/scheduler/* |
Shared schedule import/update, runtime schedule actions, skill actions, folder browsing |
/api/syncthing/* |
Syncthing status and HivemindOS vault pairing |
/api/tailscale/devices |
Tailscale and Hivemind Link device discovery |
/api/telemetry/events |
Local telemetry event recording and query |
/api/usepod/* |
UsePod registration and readiness/model/balance checks |
/api/wallet/* |
Wallet creation, balance, send, export, MoneyClaw, backup, and x402 actions |
/api/work-history |
Work history and changelog summaries |
/api/workspace/git-status |
Workspace git status for task safety checks |
OpenClaw has no routes of its own. It goes through the generic runtime and chat routes.
Generic runtime routes
These routes work the same way for every runtime. Known runtime ids are openclaw, hermes, aeon, and hivemind-os.
| Route | Returns |
|---|---|
/api/runtimes/[runtime]/status |
Runtime status |
/api/runtimes/[runtime]/skills |
Installed skills; with an action payload, syncs skills where supported |
/api/runtimes/[runtime]/schedules |
Schedules |
/api/runtimes/[runtime]/runs |
Runs |
/api/runtimes/[runtime]/outputs |
Outputs |
/api/runtimes/[runtime]/integrations |
Integration status |
/api/runtimes/[runtime]/analytics |
Analytics, where supported |
/api/runtimes/[runtime]/memory |
Memory context, where supported |
/api/scheduler/runtime-action |
Runs a schedule action on a runtime |
Crypto routes
These routes help an agent pick and prepare a money rail. They never spend. Sends, trades, crosschain intents, paid API calls, private transfers, card payments, and LLM credit funding still run through the provider’s own route or skill after its spend gate or confirmation.
| Route | Purpose |
|---|---|
/api/crypto/capabilities |
status reads readiness by provider, select picks a rail for an intent without side effects, and prepare returns a request draft, clear-signing review, and crosschain plan when relevant |
/api/crypto/clear-signing |
Turns an action draft into a clear-signing review with risks, side effects, confirmation text, and fingerprint |
/api/crypto/agent-identity |
Local agent identity records with wallet, ENS/ERC-8004 metadata, endpoints, capabilities, proofs, and status |
/api/crypto/risk-monitor |
Offline risk scoring over wallet policy, identity, env-key presence, endpoints, repo controls, DNS controls, and multisig posture |
The router covers Bankr, x402, Veil Cash, MoneyClaw, and UsePod. It reports credentials by key name and status only, never raw values or wallet secrets.
The HivemindOS MCP server exposes the same routes to external agents as crypto_capabilities, select_crypto_rail, prepare_crypto_action, review_crypto_action, agent_crypto_identity, and crypto_risk_monitor. These tools need a running, authenticated dashboard. They are not an offline wallet daemon.
Fleet apps and API services
/api/fleet/apps builds the My Apps launcher from collector reports and service probes across your machines.
- Browser apps and API-only services are listed separately. Known API services stay usable even when their root page isn’t interactive.
/api/fleet/app-iconproxies app icons so browser security doesn’t block them.- API services list their routes from an OpenAPI or Swagger document found at a common path such as
/openapi.json,/api/openapi.yaml, or/swagger.json. If none exists, a built-in catalog may be used (MiroShark has one). - My Apps only offers an open button for safe
GETroutes without path parameters.
GitLawb Code Proof
GitLawb is optional. If it’s missing, these routes return a safe status instead of breaking setup or the Work board.
| Route | Purpose |
|---|---|
GET /api/gitlawb/status |
Detect CLI/helper binaries, local DID, node health, repo/peer counts, and MCP availability |
POST /api/gitlawb/setup-cli |
Install or repair lightweight GitLawb CLI binaries where supported |
POST /api/gitlawb/identity |
Create or refresh a local DID without public node registration |
POST /api/gitlawb/node/setup |
Return local-node readiness and guidance |
GET /api/projects |
Read the shared-vault or local-fallback project registry |
POST /api/projects |
Create or update a Hivemind project |
POST /api/projects/link-gitlawb |
Link a project to a GitLawb repo; degrades gracefully when no node is available |
Node checks use http://127.0.0.1:7545 by default. Default setup doesn’t host a full node. That only makes sense after you opt into local repo hosting, and it normally means a Docker/Postgres-backed GitLawb node.
Desktop app native commands
The desktop app handles some local actions natively. The browser and remote machines use the API instead.
| Command | Purpose |
|---|---|
desktop_status |
Build commit, branch, dirty flag, runtime phase, native host, and native server port |
list_local_directories |
Browse folders on this computer without going through the collector |
create_local_folder |
Create a local folder after validating the parent and cleaning the name |
display_local_path |
Show expanded local paths in a readable form |
These power local folder picking in AEON workspace linking, chat folders, and the scheduler. Remote machines still go through /api/machines/directories or the collector’s /directories.
Collector endpoints
Every machine in your hive runs a collector. Treat every collector endpoint as private: reachable only over your Tailnet or Hivemind Link.
| Endpoint | Purpose |
|---|---|
GET /health |
Host, version, env sync status, and capability advertisement |
POST /snapshot |
Local machine, process, runtime, task, and alert snapshot |
POST /update |
Start a HivemindOS update on that machine |
GET /env |
Export known env metadata for a scope or runtime |
POST /env |
Import env values |
GET /agents |
List local runtime agents |
POST /agents |
Create a runtime agent when supported |
DELETE /agents |
Delete a runtime agent when supported |
GET /directories |
Browse folders for machine-targeted workflows |
GET /apps |
Report local apps and services for My Apps |
GET /app-proxy/<port>/* |
Proxy a local app or API service |
GET /skills |
List installed skills from known runtimes |
GET /skills/auto-sync |
Read skill auto-sync settings |
POST /skills/auto-sync |
Configure skill auto-sync |
The collector also has endpoints for runtime sessions, chat, schedules, runs, outputs, env sync, and Syncthing.
Where state is stored
Dashboard state
Dashboard preferences and caches are saved by the local server, not in browser storage, so the desktop app and the browser see the same state. Each workspace has its own file:
- Main workspace:
~/.hivemindos/dashboard-state.json - Other workspaces:
~/.hivemindos/workspaces/<id>/dashboard-state.json
This holds agent profiles, shared vault settings, recent tasks, schedules, wallets, chats, folders, discovered machines, and Honey opt-in flags. A new workspace starts clean.
A few install-wide settings always live in the main file and apply to every workspace: terms acceptance, onboarding progress, and appearance such as the theme.
Work you share with other agents belongs in the vault or a runtime, not in dashboard state.
App data folder
Default location: ~/.hivemindos
| Path | Purpose |
|---|---|
install-id |
Workspace id used by Honey and compute flows |
.env |
Shared env store, managed by the hive-env-add, hive-env-remove, and hive-env-delete helpers |
collector.env |
Collector and Link settings, such as the selected port |
gitlawb/status.json |
Short-lived GitLawb status cache with no private keys |
gitlawb/installed-by-hivemindos.json |
Marker for GitLawb CLI binaries installed by HivemindOS setup |
projects.json |
Local fallback project registry |
kanban |
Local Kanban fallback when the vault is unavailable |
runtime-agents.json |
Local runtime agent registry used by the collector |
runtime-runs |
Runtime run cache and output metadata |
skill-auto-sync.json |
Skill auto-sync settings |
telemetry/memory-samples.jsonl |
Memory samples used to spot growth trends |
agent-identities.json |
Local crypto agent identity registry for ENS/ERC-8004-style metadata |
wallet-vault.json |
Encrypted wallet secret store for user and agent wallets |
wallet-vault.key |
Wallet-vault key material when HIVEMINDOS_WALLET_VAULT_KEY isn’t set |
Shared brain vault
Default location: ~/Documents/Obsidian/hivemindos-vault
| Vault area | Purpose |
|---|---|
Intake |
Agent and user inbox; source for note task import |
Shared Context.md |
Shared instructions and context |
Operations/Work Board |
Kanban board state |
Operations/Code Projects/projects.json |
Project registry and optional GitLawb repo links |
Operations/Agent Notifications |
Notification records and settings |
Operations/Automations |
Schedules and run records |
Operations/Brain Services |
GBrain, Syntho, and trading-brain service notes |
Synthesis |
Reviewed synthesis layer and optional Syntho vault |
Skills/README.md |
Shared skill index |
Skills/<slug>/SKILL.md |
Shared skill definitions |
For the full folder map, see Where Hive Superbrain keeps things.
Runtime homes
| Runtime | Usual location | Contents |
|---|---|---|
| Hermes | ~/.hermes |
Sessions, state DB, logs, profiles, local API/CLI bridge |
| OpenClaw | ~/.openclaw |
Gateway config, token, model references, and local runtime state |
| Aeon | ~/.aeon or AEON_LOCAL_PATH |
Background runtime, skills, run history, outputs |
| Local OpenAI-compatible | Configured base URL, plus servers discovered on this machine or your fleet | LM Studio, FreeToken, Ollama, vLLM, llama.cpp server, LocalAI, or a compatible service |
Hosted services
HivemindOS runs these services. Their source is kept outside this app’s repository, and the app talks to the configured endpoint.
Honey ledger
| Route | Purpose |
|---|---|
GET /health |
Service health |
GET /ledger |
Ledger balance and summary |
POST /receipts |
Signed usage receipt ingestion |
POST /observations |
Lower-trust local usage observations |
POST /exchange |
Honey-to-HIVE ledger exchange; fails closed by default unless a separately authorized hosted conversion policy is enabled |
POST /return-to-honey |
Move legacy ledger-only HIVE back to Honey |
POST /claim-bankr-hive |
Honey-to-HIVE claim; fails closed by default unless a separately authorized hosted conversion policy is enabled |
POST /pool-events |
Admin reward-pool funding events |
Legacy reward-pool accounting stays visible for audit and return-to-Honey repair. It is not a current promise of token conversion or a fixed allocation of company revenue.
Compute gateway
| Route | Purpose |
|---|---|
GET /health |
Service health |
POST /chat |
Compatibility chat endpoint |
POST /v1/chat/completions |
OpenAI-compatible chat completion proxy |
GET /v1/models |
Model list |
Paid agent gateway
| Route | Purpose |
|---|---|
GET /health |
Service health and paid-agent readiness |
GET /api/paid-agents/<slug>/chat/completions |
Non-secret x402 paid-agent metadata |
POST /api/paid-agents/<slug>/chat/completions |
x402-protected OpenAI-compatible chat completion proxy |
Environment variables
Set these only when you need to override a default.
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_OBSIDIAN_VAULT_PATH |
Shared vault path |
NEXT_PUBLIC_OBSIDIAN_KANBAN_FOLDER |
Kanban folder inside the vault |
AGENT_TELEMETRY_PORT |
Collector port |
AGENT_TELEMETRY_HOST |
Collector bind host |
HIVE_LINK_ENABLED |
Use the Hivemind Link setup path |
HIVE_LINK_CONTROL_URL |
Local Link control API URL |
HERMES_HOME |
Hermes home override |
OPENCLAW_HOME |
OpenClaw home override |
AEON_HOME / AEON_LOCAL_PATH |
Aeon home or repo override |
LOCAL_OPENAI_BASE_URL |
OpenAI-compatible local server |
LOCAL_OPENAI_API_KEY |
Optional local server API key |
LOCAL_OPENAI_MODEL |
Preferred local model |
MIROSHARK_HOME |
Local MiroShark checkout |
MIROSHARK_BASE_URL |
MiroShark backend API URL |
NEXT_PUBLIC_GITLAWB_PROOF_READY |
Turn on Code Proof-ready dashboard behavior |
NEXT_PUBLIC_GITLAWB_NODE_URL |
Default local GitLawb node URL, normally http://127.0.0.1:7545 |
GITLAWB_NODE_URL / GITLAWB_NODE |
Server-side GitLawb node URL override |
GITLAWB_INSTALL_DIR |
Install folder for GitLawb CLI binaries |
HONEY_LEDGER_REMOTE_URL |
Official or forked Honey ledger service |
HONEY_LEDGER_ISSUER_ID |
Honey ledger issuer id |
HONEY_LEDGER_SIGNING_SECRET |
Trusted receipt signing secret |
Never commit private values, Tailnet IPs, wallet keys, or vault contents.