Skip to content

First launch

Hive ships as an unsigned desktop app (macOS / Windows / Linux). On first launch you'll see a guided onboarding wizard that captures your identity, picks a workspace folder, and configures a runtime.

Onboarding welcome step

Install

Grab a bundle for your OS, or build from source:

git clone https://github.com/yourname/hive.git
cd hive
cargo tauri build        # bundles for the current OS → target/release/bundle/
# or a fast dev loop without bundling:
cargo tauri dev

See Building the dist for per-OS details and cross-builds. Because builds are unsigned, first launch needs a nudge:

  • macOS: right-click → Open (or xattr -dr com.apple.quarantine /Applications/Hive.app).
  • Windows: SmartScreen → More info → Run anyway.
  • Linux: chmod +x Hive_*.AppImage && ./Hive_*.AppImage.

Wizard steps

The onboarding is 7 steps:

  1. Welcome — what Hive is and what we're about to configure.
  2. Identity — display name + handle. Hive auto-generates an Ed25519 device key behind the scenes; you never see it directly. You can also sign in with GitHub here (see below) for one identity across all your devices.
  3. Workspace — pick a folder on disk. Hive treats this as the git-style root; everything it does (file edits, command runs, git operations) is scoped to this directory.
  4. Runtime — wire up at least one LLM. The picker covers Ollama (local), Anthropic, OpenAI, OpenRouter, Claude Code, aider, pi, or a custom subprocess agent.
  5. Permissions — choose the default trust scope. Hive defaults to always ask; you can switch to workspace for tighter single-user setups.
  6. Sync — optional. If you have a relay endpoint already, paste it here so cross-network peers can find you. You can skip and add later from Settings.
  7. Finish — review and save. Hive writes hive.config.toml in your workspace root.

Onboarding runtime step

What gets written

After onboarding:

  • ~/Library/Application Support/Hive/identity.json — your account
  • device records (public bits only).
  • macOS Keychain item com.hive.identity.<accountID> — your private signing key.
  • <workspace>/hive.config.toml — runtime + transport config.
  • <workspace>/.hive/ — the workspace's event log (signed envelopes) and per-session state.

Everything is local. Nothing leaves your machine unless you explicitly configure a transport (relay endpoint or LAN discovery toggle).

Sign in with GitHub

You can use Hive anonymously with just a local device identity, but signing in with GitHub (during onboarding or later in Settings → Account) gives you:

  • One account identity across devices — the same GitHub account on your laptop and desktop resolves to one member, two devices.
  • Attributed commits — git commits Hive makes on your behalf are attributed to you.
  • Reach teammates by @handle — invite and add collaborators by their GitHub username.

Sign-in uses GitHub's device flow: Hive shows a short code, you enter it on github.com, and approve. Official builds ship with the OAuth App client id baked in; if you build a fork yourself, paste your own OAuth App client id in the sign-in panel.

See Identity & devices and Collaborators, presence & DMs.

Reset local data

To start completely over on a device, use Settings → Account → Danger zone → "Reset local data". It wipes this device's chats, identity, keys, settings, and workspaces, then relaunches Hive fresh.

This is the supported way to start over — uninstalling the app leaves your data behind on disk. If you ever need to clean up manually, Hive's data directory is:

OS Path
macOS ~/Library/Application Support/com.hive.desktop
Windows %APPDATA%\com.hive.desktop (plus %LOCALAPPDATA%\com.hive.desktop for the WebView2 cache)
Linux ~/.local/share/com.hive.desktop

Reset is irreversible

Reset local data cannot be undone. Anything not synced to a peer or pushed to git is gone. Back up your workspace folder first if in doubt.

Next steps