Beekeeper

The operator CLI for Hive. Drives Hive installs, manages devices, and serves Claude Code sessions to remote clients (iOS, web).

The package ships two binaries:

• beekeeperd — gateway daemon, owned by launchd. WebSockets in, Claude Code sessions out.
• beekeeper — operator CLI. Installs the daemon, drives Hive lifecycle, manages devices.

Install

sudo npm i -g @keepur/beekeeper
beekeeper init

beekeeper install is one-shot: writes a LaunchAgent plist, creates a config dir at ~/.beekeeper/, and loads the daemon. Daemon's running on :8420 by the time the command returns.

beekeeper init is the first-run wizard — it generates ~/.beekeeper/env (JWT + admin secrets + Anthropic API key), then runs beekeeper install. Re-runs are safe; pass --force to rotate the admin secret. (beekeeper install on its own still works for upgrades, where the env file already exists.)

Set up Hive

beekeeper hive setup

This fetches the latest @keepur/hive release and opens a Claude Code session that walks you through hive init, Slack pairing, dependency setup (Node, MongoDB, Ollama, Qdrant), and your first conversation. Budget about 20 minutes. Re-running detects existing instances; pass --force to install fresh.

beekeeper hive list                         # show installed instances + run state
beekeeper hive update <instance>            # update one instance
beekeeper hive update --all                 # sequential fleet update, fail-fast
beekeeper hive update --all --tag v0.5.5    # pin a version
beekeeper status                            # gateway health

beekeeper hive update drives hive update across one or all installed hive instances.

Pair a device

beekeeper user add <id> "<display name>"     # one-time, register the user
beekeeper pair <id> "iPhone"                 # 6-digit code, 10-min TTL

Enter the code in the Keepur iOS app (or any client speaking the beekeeper protocol). Devices auth with JWTs from there.

Common commands

beekeeper help                 # full command list
beekeeper status               # gateway health (sessions, connected devices)
beekeeper sessions list        # active Claude Code sessions
beekeeper devices list         # registered devices
beekeeper hive setup           # install/upgrade hive on this Mac
beekeeper hive list            # all hive instances + run state
beekeeper hive update [<instance>] [--all] [--tag <version>]  # update one or all hive instances
beekeeper user list            # registered users
beekeeper pair <user> <label>  # issue a pairing code
beekeeper install              # install/reload the LaunchAgent
beekeeper uninstall            # remove the LaunchAgent

--json is accepted on status, sessions list, devices list, capabilities.

Update

beekeeper update                 # latest
beekeeper update --tag v1.4.0    # pinned (semver — v prefix tolerated)
beekeeper update --tag next      # npm dist-tag

update captures the currently-installed version, runs npm i -g @keepur/beekeeper@<tag>, and bootout-then-bootstraps the LaunchAgent so the new daemon is running before the command returns. The plist is left alone by default — pass --regen-plist to regenerate the wrapper + plist when a new package version ships a template change.

Rollback

beekeeper rollback

Restores the version that was installed before the most recent beekeeper update. Exits non-zero if no rollback target is recorded — in that case install a specific version manually with npm i -g @keepur/beekeeper@<version>.

The legacy sudo npm i -g @keepur/beekeeper@latest && beekeeper install path still works for first install or manual recovery.

TLS / remote access

If you reach beekeeper from anything other than localhost, put TLS in front of :8420. Beekeeper serves plain HTTP/WS by design — bring your own Cloudflare Tunnel, Tailscale Funnel, Caddy, nginx, etc. iOS clients won't connect over plain ws:// (App Transport Security blocks it). Localhost-only setups need nothing extra.

Docs

For deeper reading or when you need the API surface:

• Configuration — beekeeper.yaml, env vars, LaunchAgent details.
• API reference — REST endpoints (device self-service, admin, internal).
• Federation — how Hive (or any sibling) registers as a ?channel= capability.
• Architecture — what's inside the gateway.
• Development — contributing, running from source, releasing.

License

Proprietary. Copyright (c) 2026 Keepur Co. All rights reserved. See LICENSE.

Beekeeper is distributed to operators under a separate licensing agreement. If you do not have one, contact [email protected].

Versions 1.0.0 – 1.6.2 of @keepur/beekeeper were released under Apache-2.0 and remain available under that license; versions 1.7.0 and later are governed by the terms in LICENSE.