This quickstart walks you through installing Bitchat, setting up your identity, and sending your first message — either over the local Bluetooth mesh or through a Nostr location channel. The whole process takes only a few minutes, and you will not be asked to create an account or provide any personal information at any point.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/permissionlesstech/bitchat/llms.txt
Use this file to discover all available pages before exploring further.
Get Bitchat
Install Bitchat on your iOS or macOS device. There are two ways to get a copy: the App Store (recommended for most users) or building directly from the verified source.
- App Store
- Build from Source
The App Store build is the easiest path and is the only compiled binary that can be independently verified against the release hash manifest.Download Bitchat on the App Store →Bitchat is a universal app and the same listing installs on both iPhone and Mac (Apple Silicon with macOS 13+).
Set your nickname
The first thing Bitchat asks when you launch is to choose a nickname. This is the name other users on the mesh will see next to your messages. It is not an account — there is no verification, no registration, and no server involved. The nickname is broadcast alongside your messages within the local mesh.Pick something you are comfortable with and tap Continue. You can change it later in Settings.
Join the mesh channel
Once you are past the nickname screen, Bitchat automatically begins scanning for nearby peers over Bluetooth Low Energy. You do not need to do anything — peer discovery is always on when Bluetooth is enabled.The main channel is
mesh #bluetooth. Any device running Bitchat within multi-hop Bluetooth range will appear here. Messages in this channel travel over the local mesh only; no internet is involved.If no peers appear immediately, that is normal — you may be the only device in range, or nearby peers may not have Bitchat running. The mesh populates as other devices come online.Send your first message
Tap or click the compose field at the bottom of the Private messages are end-to-end encrypted using the Noise
mesh #bluetooth channel, type your message, and tap the send button. Your message is signed with your device’s Ed25519 key and broadcast over the Bluetooth mesh.Public channel messages are visible to all peers within multi-hop range (up to 7 hops). They are not encrypted — the mesh channel is a public room, not a private conversation.To send a private message to a specific peer, use the /msg command:XX protocol and only the intended recipient can read them.Enable Nostr for location channels (optional)
If you have an internet connection and want to reach users beyond Bluetooth range, enable the Nostr transport in Settings. Once enabled, Bitchat connects to a global network of Nostr relays and joins location-based channels derived from your current geohash coordinates.Location channels let you chat with people in the same geographic area — a city block, a neighborhood, or a whole country — without knowing anyone’s identifiers. These channels update automatically as you move.Nostr is also used as a fallback delivery path for private messages to mutual favorites when neither device has a Bluetooth connection to the other.
Mesh features require physical Bluetooth-capable devices. Running Bitchat in the iOS Simulator will show the full UI and let you explore all controls, but no peers will be discovered and no messages will relay over Bluetooth. To test the mesh, install on two or more real devices and bring them within Bluetooth range of each other.