hive.config.toml reference

Hive reads one TOML file per workspace, at the workspace root, via hive-core::config. The Settings → Runtimes and MCP servers sections write back to it through the encoder, so hand-edited and GUI-edited files round-trip cleanly.

Note: the encoder doesn't preserve comments. Hand-add commentary in a sibling README.md if you need it documented next to the config.

Connection settings live elsewhere. The relay URL, room, workspace key, API key, and Claude permission mode are edited at runtime in Settings → Multiuser sync and persist to a settings.json in the app data dir (not this file); the [transport] keys below only seed them on first launch. The theme is stored per-device. See Settings.

Full example

[app]
name = "Hive"
local_mode = false
sync_mode = "workspace"
default_runtime = "anthropic"
default_model = "claude-sonnet-4-5"

[transport]
kind = "local"           # local | relay | lan

[transport.relay]
endpoint = "wss://relay.hive.example/v1"
account_token_env = "HIVE_RELAY_TOKEN"

[transport.rendezvous]
endpoint = "https://rendezvous.example.com"
publish_candidates = true

[sync]
enabled = true
server = ""
device_name = "alice-macbook"
end_to_end_encryption = true

[permissions]
default_policy = "always_ask"   # one_action | chat | workspace | always_ask
allow_network = true

[permissions.presets.default]
read_files = true
write_files = true
run_commands = true
access_vaults = true
access_remote_runtime = true

[retrieval]
mode = "manual"          # none | manual | always
top_k = 8
chunk_size = 1200
keyword_weight = 0.35
semantic_weight = 0.65
recency_bias = false

[[runtimes]]
id = "anthropic"
kind = "remote"          # local | remote
provider = "anthropic"   # ollama | openai | anthropic | claude-code | aider | pi | subprocess | openrouter | hive-daemon | custom
endpoint = "https://api.anthropic.com"
api_key_env = "ANTHROPIC_API_KEY"
models = ["claude-sonnet-4-5", "claude-opus-4-7"]
preferred_model = "claude-sonnet-4-5"
keep_alive = ""
supports_embeddings = false
supports_tools = true
performance_score = 9.5
cost_per_1m_input_tokens_usd = 3.0

[[runtimes]]
id = "aider"
kind = "local"
provider = "aider"
endpoint = "/usr/local/bin/aider"
preferred_model = "gpt-4o"
supports_tools = true

[[runtime_pools]]
id = "default-pool"
name = "Default Pool"
runtimes = ["anthropic", "aider"]
routing_strategy = "latencyOptimized"
fallback_strategy = "priorityPerformance"
prefer_local_for_low_priority = true
reserve_paid_capacity_for_high_priority = false
minimum_requests_reserve = 0
minimum_spend_reserve_usd = 0.0

[[vaults]]
id = "main-docs"
kind = "folder"          # folder | obsidian
location = "/Users/alice/Documents/Notes"
runtime_id = "anthropic"
index = true

[[skills]]
id = "swift-strict"
source = "skills/swift-strict.md"
autoload = true
scope = "workspace"

[[mcp_servers]]
id = "filesystem"
transport = "stdio"
command = "/usr/local/bin/mcp-filesystem"
arguments = ["--workspace", "."]
autoload = true
allowed_in_runtimes = ["anthropic", "openai"]

[chat_defaults]
permission_preset = "default"
retrieval_mode = "manual"
runtime_pool = "default-pool"
show_context_panel = true
show_activity_panel = true

Section reference

[app]

Key	Type	Notes
name	string	Display label for the workspace
local_mode	bool	When true, transport defaults to local-disk
sync_mode	string	local / workspace / account
default_runtime	string	id of the runtime used for new chats
default_model	string	Model ID to seed new chats with

[transport]

kind selects which transport carries envelopes:

• local — append to .hive/.../events.ndjson. No network.
• relay — also push to the configured relay ([transport.relay]).
• lan — bonjour-discovered peers ([transport.lan]).

[transport.relay]

Routes the full envelope log through a relay. Distinct from [transport.rendezvous], which is the tiny coordination point for P2P. You typically pick one or the other.

[transport.rendezvous]

Key	Type	Notes
endpoint	string	HTTPS base URL of the rendezvous relay
publish_candidates	bool	Whether this peer publishes its own STUN candidates

See Rendezvous relay for protocol detail.

[transport.lan]

LAN discovery is a roadmap item — not implemented in the current build. See LAN discovery.

Key	Type	Notes
service_name	string	mDNS service type (default _hive._tcp)

[permissions] / [permissions.presets.NAME]

default_policy is the trust scope for new actions. Presets override per-named-policy; the active preset for a chat comes from chat_defaults.permission_preset.

[[runtimes]]

One block per LLM. See Configuring a runtime.

[[runtime_pools]]

Group runtimes for routing. The routing_strategy decides which runtime in the pool handles a given request:

• latencyOptimized — prefer the lowest-latency runtime.
• priorityPerformance — prefer the highest performance_score.
• quotaAware — avoid runtimes near quota.
• roundRobin, leastLoaded, pinned — self-explanatory.

[[vaults]]

Local knowledge bases. kind = folder for plain directories; kind = obsidian for Obsidian libraries (the loader unwraps the .obsidian structure).

[[skills]]

Auto-loadable prompt fragments. scope = workspace loads for every chat in this workspace; scope = chat is opt-in per chat.

[[mcp_servers]]

Model Context Protocol servers. See MCP servers.

[chat_defaults]

Defaults applied to new chats:

Key	Type	Notes
permission_preset	string	Which [permissions.presets.X] to apply
retrieval_mode	string	none / manual / always
runtime_pool	string	Pool ID to draw from
show_context_panel	bool	Open the Context pane on new chats
show_activity_panel	bool	Open the Activity pane on new chats

What the encoder doesn't write

• Comments.
• Whitespace layout — the encoder picks one canonical format.

What the loader silently ignores

• Unknown keys in known sections (forward-compatibility for schema additions).

The loader and encoder live in hive-core::config.