homebrew-tap

kavilo-hive — user guide

This is the client guide. If you’re operating the server side (kavilo-hived), see operator-guide.md.

What it does

kavilo-hive is the end-user CLI for an actor-based messaging hub with Signal-protocol end-to-end encryption. You connect to a kavilo-hived server your operator runs, prove you are who you say you are with an Ed25519 key, and exchange encrypted messages with other actors (people, bots) or fan-out groups over a persistent WSS connection. The server never sees plaintext.

Use cases:

Bot-to-bot messaging within a team (actor_role=bot) without standing up Signal/Matrix infrastructure.
Encrypted personal messaging where the operator owns the hub.
Asynchronous fan-out via groups (each group is its own Signal Sender-Keys session under the hood).

Install

macOS (Homebrew)

brew install kavilo-bot/tap/kavilo-hive

The macOS arm64 binary is codesigned and Apple-notarized, so there’s no Gatekeeper warning on first run.

Debian / Ubuntu (amd64) — apt

Add the kavilo apt repo once (also provides kavilo and kavilo-tunnel), then install with regular apt:

sudo install -d /etc/apt/keyrings
curl -fsSL https://kavilo-bot.github.io/homebrew-tap/apt/keyring.asc \
  | sudo gpg --dearmor -o /etc/apt/keyrings/kavilo.gpg

echo "deb [signed-by=/etc/apt/keyrings/kavilo.gpg] https://kavilo-bot.github.io/homebrew-tap/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/kavilo.list

sudo apt update
sudo apt install kavilo-hive

Upgrades come via sudo apt update && sudo apt upgrade.

Direct binary / .deb

Versioned assets live on the Releases page under the kavilo-hive-vX.Y.Z tag. The .deb is also reachable from the apt pool: https://kavilo-bot.github.io/homebrew-tap/apt/pool/main/k/kavilo-hive/.

From source

git clone https://github.com/kavilo-bot/kavilo-hive
cd kavilo-hive/rust

# Build deps (libsignal-protocol pulls protoc via prost-build).
brew install protobuf                          # macOS
sudo apt-get install -y protobuf-compiler      # Debian / Ubuntu

cargo install --path crates/kavilo-hive --locked
kavilo-hive version

Quick start

Assume your operator has given you:

A server URL (e.g. https://hive.example.com:8443).
A hive ref (the path segment after /h/, e.g. team-alpha).
An actor id + role (user or bot).
A one-time 6-digit bootstrap code (valid for a short window).
Optionally, the server’s CA cert (if it’s self-signed).

1. Initialize a local profile

kavilo-hive config init \
  --server-url https://hive.example.com:8443/h/team-alpha \
  --ca-file ~/Downloads/kavilo-hive-ca.crt \
  --name personal \
  --actor-id alice \
  --actor-role user

This writes ~/.config/kavilo-hive/config.yaml (or $XDG_CONFIG_HOME/kavilo-hive/config.yaml), generates a long-term Ed25519 keypair, and stores the private key under ~/.local/share/kavilo-hive/keys/.

Profiles are independent — pass --name <profile> to make a second one (for a different actor or a different hive).

2. Claim your identity

The very first time you talk to the server, redeem the bootstrap code:

kavilo-hive claim --code 123456

Server-side this binds your fresh Ed25519 public key to the actor record. You can also pass --code later via env var KAVILO_HIVE_BOOTSTRAP_CODE.

3. Health check

kavilo-hive health
# kavilo-hive — connection to hive.example.com:8443 OK (TLS verified, actor authed)

4. Send a one-shot message

kavilo-hive send --to bob --body "ping"

The body is encrypted client-side with a Signal Double-Ratchet session keyed off bob’s prekey bundle (fetched from the server’s prekey directory on first use, cached locally afterward). The server only sees sender id, target id, and opaque ciphertext.

5. Interactive shell

kavilo-hive shell

Drops you into a REPL with line-editing, completion, and live receive. Prompt is actor-id@hive>. Type a target id and the message; /help for in-shell commands.

Commands

Command	What it does
`kavilo-hive config init …`	Create a new profile
`kavilo-hive config path`	Print the config file path
`kavilo-hive whoami`	Print active profile + actor id + fingerprint
`kavilo-hive health`	Verify TLS + auth round-trip to the server
`kavilo-hive claim --code …`	Redeem a bootstrap code
`kavilo-hive actor list`	List actors on this hive
`kavilo-hive actor fingerprint <id>`	Print a counterparty’s identity fingerprint (for safety-number checks)
`kavilo-hive send --to <id> [--group <ref>] --body "…"`	Send one message and exit
`kavilo-hive shell`	Interactive REPL
`kavilo-hive version`	Build info (version, commit, target triple, rustc)

Run kavilo-hive <command> --help for the full flag set.

Identity & safety numbers

Each actor has a long-term Ed25519 identity key. Its 60-digit fingerprint is what you and a counterparty compare out-of-band to defend against an evil server reissuing keys. Two-sided check:

kavilo-hive actor fingerprint bob          # local view of bob's key
kavilo-hive actor fingerprint --self       # your own key, to share with bob

If bob hands you the same digits over Signal/in person, you’ve confirmed that no MITM has replaced his key in the hive’s prekey directory.

Config file

~/.config/kavilo-hive/config.yaml looks like:

active_profile: personal
profiles:
  personal:
    server_url: https://hive.example.com:8443/h/team-alpha
    ca_file: /Users/alice/Downloads/kavilo-hive-ca.crt   # optional
    actor_id: alice
    actor_role: user
    key_file: /Users/alice/.local/share/kavilo-hive/keys/personal.ed25519

You can hand-edit it, switch profiles with --profile <name>, or call kavilo-hive config init --name <name> again to add another one.

Environment overrides (handy for CI/automation):

KAVILO_HIVE_CONFIG — alternate config-file path.
KAVILO_HIVE_PROFILE — pick a profile.
KAVILO_HIVE_BOOTSTRAP_CODE — pass code to claim non-interactively.

Troubleshooting

x509: certificate signed by unknown authority Your operator’s server uses the built-in self-signed CA. Re-run kavilo-hive config init with the correct --ca-file (download from https://<server>/ca.crt and trust the operator’s fingerprint).

401 unauthorized on health / send Bootstrap code wasn’t redeemed yet, or was redeemed against a different profile. Run kavilo-hive whoami to see which key the client thinks it’s holding, and kavilo-hive claim --code … to bind it.

prekey bundle for <peer> not available The peer has never connected to the server and hasn’t uploaded prekeys. They need to run kavilo-hive health (or any command that triggers a prekey-pool refresh) at least once. The server stores prekey bundles lazily.

fingerprint changed The counterparty’s identity key on the server doesn’t match what you saw last time. Either they reset their device (legitimate — confirm out-of-band and re-trust with kavilo-hive actor verify <id>) or something’s wrong. Don’t blow past the warning.

Where do my logs go? tracing writes to stderr at info by default. Crank it up with RUST_LOG=kavilo_hive=debug,kavilo_engine=debug kavilo-hive shell.

Where things live on disk

Path	Contents
`~/.config/kavilo-hive/config.yaml`	Profile + server URL + CA path
`~/.local/share/kavilo-hive/keys/`	Ed25519 identity private keys (one per profile)
`~/.local/share/kavilo-hive/sessions/`	Signal Double-Ratchet + Sender-Keys state
`~/.local/share/kavilo-hive/prekeys/`	Local one-time prekey pool

(~/Library/Application Support/kavilo-hive/... on macOS via the directories crate’s defaults — exact paths printed by kavilo-hive config path and kavilo-hive whoami.)

Server side / running your own hive → operator-guide.md
Protocol design + threat model → docs/adr/0001-signal-level-e2e.md in the source repo
Federation between independent hubs → docs/adr/0002-multi-server-federation.md

This site is open source. Improve this page.