Encrypt to a name,
not to a key.

Build and run Kleo

Tagging a release builds installers for macOS, Linux and Windows, but they are not signed yet — so until they are, build it yourself and know what you're running. That takes Rust ≥ 1.85 (edition 2024), Node.js ≥ 20, and Tauri's platform packages (Xcode Command Line Tools on macOS; WebView2 on Windows; webkit2gtk-4.1, libayatana-appindicator3, librsvg2 and libdbus-1-dev on Linux).

npm install
npm run tauri dev        # run it with hot reload
npm run tauri build      # bundle for this platform (dmg/app, msi, deb/AppImage)

Point it at a node

Kleo talks to plain-bitnames over JSON-RPC and defaults to http://127.0.0.1:6002. Open Settings → BitNames node, enter a URL, press Test connection, then Save. The sidebar then shows block height, balance and peers, refreshed every five seconds.

Don't have a chain yet? One script downloads, builds and runs a full regtest stack — Bitcoin Core, the BIP300 enforcer and plain-bitnames:

scripts/regtest.sh install      # once: ~2 min, mostly the enforcer build
scripts/regtest.sh start        # funds the enforcer, activates BitNames, deposits 10 BTC
scripts/regtest.sh demo-names   # register alice, bob, carol, dave + publish two profiles
scripts/regtest.sh automine 10  # a block every 10 s, so registrations confirm

Set up your wallet

Open Your names. If the node's wallet has no seed, Kleo offers to create one: twelve words to write down, then a three-word check before it continues. Restoring an existing wallet takes the same phrase.

Check your backup compares a phrase you've written down against the wallet without changing anything — worth doing the day after, when the handwriting is cold.

Register a BitName

In Your names → Register, type the name you want. Kleo checks whether it is free, then runs the two-block dance: a reservation that commits to the name without revealing it, and a registration in a later block that reveals it and publishes your keys. Progress is shown as it goes, and it resumes if you close the app.

• The name itself never appears on-chain — only blake3(name).
• Registration publishes your signing key and encryption key with the name, so others can find them.
• On regtest, mine or wait for blocks (scripts/regtest.sh mine 2) for it to complete.

Sign something, and verify someone

Open Notepad, type your text, pick your name under Sign as and press Sign. You get an armored block that survives email and chat.

Going the other way, paste anything into the Notepad and press Verify. Kleo resolves the claimed signer on-chain, compares the key, checks the signature over the exact text, and returns one of the four verdicts above — in a sentence, not a symbol.

Encrypt to a name

Type a recipient's BitName under Encrypt to. Kleo looks up the encryption key that name publishes and shows it to you before anything happens. Sign & Encrypt puts your signature inside the envelope, so only the recipient learns who wrote it; their Decrypt checks that inner signature automatically.

• A name with no published encryption key can't be written to, and Kleo says which.
• If a saved contact's keys have changed, encrypting is blocked until you review the change.

Work with files

Files takes the same four operations to disk. Drop files in, or choose them.

• Sign writes a detached <file>.bnsig. It covers the file's BLAKE3 hash, so renaming doesn't break it; verifying reports both whether the signature is good and whether the contents still match.
• Encrypt writes <file>.bnenc. Each file gets a one-off key and only that key is sealed to the recipient, which keeps large files fast. The name, size and any signature travel inside the encrypted part.
• Decrypt restores the original name and never overwrites an existing file.
• Checksums writes a BLAKE3 .b3sums file in the usual <hash>  <name> layout; checking one reports every file as unchanged, changed or missing.

Publish a profile

A profile is how a name becomes a phone-book entry: display name, bio, website, links and ways to be paid. The owner commits on-chain to the BLAKE3 hash of the profile's canonical JSON; the document itself is served by any host. Kleo re-hashes what it receives and compares.

Publish from Your names → Public profile…, to a hosted resolver or to your own:

kleo-resolver --node http://127.0.0.1:6002 \
  --listen 0.0.0.0:7777 --public-addr 203.0.113.7:7777

# or push a document to someone else's resolver
kleo-resolver publish --node http://127.0.0.1:6002 \
  --to http://127.0.0.1:7777 --name alice alice.json

Start a conversation

Chat needs one thing first: your device has to be findable. At the bottom of the Chat pane, press Publish it for <your name>. That writes this machine's endpoint into your profile under chat.endpoint, covered by your on-chain commitment, and takes one block like any other profile change.

Then type any BitName into Write to a BitName… and send. Kleo reads their endpoint from their profile, opens an encrypted link straight to their machine, and delivers a message signed by you and sealed to them.

• A message is judged by its signature, never by the link it came in on. An envelope claiming to be someone it isn't signed by is shown as unverified.
• A message from a device the sender doesn't publish still counts as theirs if the signature holds — Kleo just tells you where it came from.
• History is stored locally in the same encrypted vault as your contacts, and a conversation can be deleted outright.
• Forward secrecy switches itself on when both names publish a prekey — which yours does, the moment you publish your endpoint. Each message then gets a key of its own, used once and dropped, so a BitName key obtained later opens nothing that was already said. The header says forward secret when a conversation has it.

Run a hub, or use one

A hub is the small server that holds what a direct link can't: profiles, mail for people who are offline, where a machine can currently be reached, and channel posts. One binary, four roles, each switchable.

kleo-hub --node http://127.0.0.1:6002 --listen 0.0.0.0:7777 \
  --public-addr 203.0.113.7:7777 --hub-name myhub --retention-days 30

• Leaving mail is signed by the sender's BitName — that is the whole spam barrier, so there are no accounts.
• Collecting it is signed by the recipient's, over a statement carrying the time, so a captured request goes stale.
• A hub is itself a BitName, so it can be looked up and pinned like a person.

Fund the wallet, and pay by name

BitNames is a sidechain: coins move in by paying a special address from a Bitcoin wallet, and out through a withdrawal bundle Bitcoin settles later. Wallet does both, and pays either an address or a BitName — Kleo looks up where that name takes payments, from its profile or from the chain.

Charge strangers, or pay to be heard

Under Your names → Price to write to you, publish what someone you've never spoken to pays to reach you. It goes on-chain, so a sender sees it before writing instead of being silently dropped.

Writing to someone who charges, Kleo offers to send the message as the payment: a transfer to the address holding their name, with your message — signed and sealed to them — inside the memo. Once they reply, writing is free.

• Contacts, and anyone you've replied to, are never charged.
• An allow list invites someone through for free, once or always.
• Memos are public and permanent, which is why Kleo encrypts what goes in one.

Keep a backup

Your recovery phrase restores the wallet and every name it holds. It restores none of what Kleo keeps privately: who you saved and the keys you pinned for them, who you blocked or invited, the channels you follow, and every conversation. Those live only on this machine until you write them somewhere.

Settings → Backup puts the lot in one file, encrypted with Argon2id to a passphrase you choose — not to this machine's keychain, which is the point: that key never leaves the machine that made it.

• Restoring only ever adds: contacts you already hold keep the keys you pinned here, and messages are matched by id, so importing twice changes nothing the second time.
• A wrong passphrase and an altered file are reported as the same thing, because authenticated encryption cannot tell them apart.

Start a channel

A channel is a BitName. In Channels, turn one of your names into one and choose who may post: only you and the authors you list, members of a private group, or anyone with a BitName.

• Broadcast posts are public and signed, so any hub can hold them and every reader checks them against the chain.
• Private groups seal a group key to each member's BitName and encrypt posts under it. Changing the membership makes a new key, so whoever was removed reads nothing written afterwards.
• Communities are open to any BitName holder, with published moderator and ban lists — a ban is the channel's decision, applied by every hub and reader alike.