Onboarding

Hive's first-launch wizard appears automatically when no hive.config.toml exists in the workspace folder. Seven steps, all skippable if you'd rather configure by hand.

Step	Captures
Welcome	(just a screen)
Identity	Display name + handle
Workspace	Folder path + name
Runtime	At least one provider + endpoint + key
Permissions	Default trust scope
Sync	Optional relay endpoint
Finish	Review + save

The wizard writes hive.config.toml + ~/Library/Application Support/Hive/identity.json + a Keychain entry on Save.

Re-running onboarding

If you delete hive.config.toml and relaunch, the wizard runs again with the existing identity (you keep your account + device keys). Useful if you want to start fresh on a workspace folder.

To start fully fresh — new account, new keys — also delete:

• ~/Library/Application Support/Hive/identity.json
• The Keychain item com.hive.identity.<accountID> (find it in Keychain Access)

Headless config

If you don't want the GUI wizard, ship a hive.config.toml directly and Hive will skip onboarding. Minimum viable config:

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

[transport]
kind = "local"

[sync]
enabled = false
server = ""
device_name = "my-mac"
end_to_end_encryption = true

[permissions]
default_policy = "always_ask"
allow_network = true

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

[[runtimes]]
id = "anthropic"
name = "Anthropic"
provider = "anthropic"
kind = "remote"
endpoint = "https://api.anthropic.com"
preferred_model = "claude-sonnet-4-5"
api_key_env = "ANTHROPIC_API_KEY"
supports_tools = true

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

See the Configuration reference for the full schema.