bitchat README

The project's README from github.com/permissionlesstech/bitchat. As one markdown file: README.md.

icon_128x128@2x

bitchat

A decentralized peer-to-peer messaging app with dual transport architecture: local Bluetooth mesh networks for offline communication and internet-based Nostr protocol for global reach. No accounts, no phone numbers, no central servers. It's the side-groupchat.

bitchat.free

📲 App Store

📲 Play Store

Getting a copy you can trust

Install from the App Store, or build from source you have verified. A compiled build from anywhere else cannot be verified — see Verifying bitchat for how to check source against the per-release hash manifest, and for what to do if that is the only build you can get.

This matters more than it usually would: this repository has been the target of takedown demands, and when a repository or releases page disappears, mirrors appear that nobody can check.

License

This project is released into the public domain. See the LICENSE file for details.

Features

Technical Architecture

BitChat uses a hybrid messaging architecture with two complementary transport layers:

Bluetooth Mesh Network (Offline)

Nostr Protocol (Internet)

BitChat's private-envelope format is proprietary and is not NIP-17, NIP-44, or NIP-59 compatible. It uses Nostr as a relay transport but only interoperates with BitChat clients: private payloads travel inside kind-1059 events whose v2:-prefixed content is a BitChat-specific XChaCha20-Poly1305 construction, not NIP-44 encryption.

Channel Types

mesh #bluetooth

Location Channels (block #dr5rsj7, neighborhood #dr5rs, country #dr)

Direct Message Routing

Private messages use intelligent transport selection:

  1. Bluetooth First (preferred when available)

    • Direct connection with established Noise session
    • Fastest and most private option

  2. Nostr Fallback (when Bluetooth unavailable)

    • Uses recipient's Nostr public key
    • BitChat's app-specific private-envelope encryption
    • Routes through global relay network

  3. Smart Queuing (when neither available)

    • Messages queued until transport becomes available
    • Automatic delivery when connection established

For detailed protocol documentation, see the Technical Whitepaper.

Setup

Option 1: Using Xcode

open bitchat.xcodeproj

For a signed device build, create your ignored local configuration and replace the example team ID with your Apple Developer Team ID:

cp Configs/Local.xcconfig.example Configs/Local.xcconfig

Local.xcconfig.example derives unique app and App Group identifiers from that team ID. The entitlement files already reference $(APP_GROUP_ID), so tracked project or entitlement files do not need to be edited.

Useful command-line checks from the repository root:

# macOS Debug build without signing
xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" \
  -configuration Debug CODE_SIGNING_ALLOWED=NO build

# Full SwiftPM test suite
swift test

# iOS simulator tests
xcodebuild -project bitchat.xcodeproj -scheme "bitchat (iOS)" \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 17' test

If iPhone 17 is unavailable, choose an installed simulator from:

xcodebuild -showdestinations -project bitchat.xcodeproj -scheme "bitchat (iOS)"

Option 2: Using just

brew install just
just check
just run

just build and just run use the current bitchat (macOS) scheme and keep Xcode output in the ignored .DerivedData/ directory. They never patch source, project, configuration, or entitlement files.

just clean removes only .DerivedData/ and .build/. It does not invoke Git or restore tracked files, so uncommitted work is preserved. just test runs the SwiftPM suite and just test-ios runs the iPhone 17 simulator suite.

Localization

bitchat (permissionlesstech/bitchat)

Searching Database…

36.6K ·GitHub
Bitchat
Что это такое?BitChat — децентрализованное приложение для обмена сообщениями напрямую между устройствами (peer-to-peer). Оно использует сеть Bluetooth mesh для локального чата без интернета и протокол Nostr для связи через интернет по всему миру. Без аккаунтов, номеров телефонов и центральных серверов.
Это чат-приложение или протокол/библиотека, на основе которых я могу что-то строить?Это готовое нативное приложение для iOS и macOS, а не библиотека и не SDK: его можно сразу установить и запустить, а команды в стиле IRC, например /slap и /msg, уже встроены.
Как его запустить?Установите из App Store или Play Store либо соберите из исходников в Xcode, указав свой Apple Developer Team ID, или используйте утилиту запуска команд «just» (just build, just run), которая запускает сборку Xcode.
Можно ли доверять любой сборке, которую я найду в интернете?Нет. Доверять можно только сборкам из App Store или исходному коду, который вы лично сверили с манифестом хешей релиза, поскольку против репозитория уже выдвигали требования об удалении, а в других местах появлялись непроверяемые копии.
Правда ли оно работает вообще без интернета?Да, транспорт Bluetooth mesh работает полностью офлайн: сообщения передаются напрямую между устройствами через ближайшие устройства до 7 переходов, поэтому его можно использовать во время катастроф или в местах без связи.
Оставляет ли сеть Bluetooth mesh какие-то следы о том, кто я?Приложение не использует аккаунты и номера телефонов, но каждое устройство хранит постоянный идентификатор, производный от его ключа идентичности, который может перехватить любое радиоустройство поблизости. Кроме того, сообщения с промежуточным хранением и пересылкой не обеспечивают прямой секретности.
Как приложение решает, использовать Bluetooth или Nostr для сообщения?Оно отдаёт предпочтение Bluetooth, если доступна прямая сессия, зашифрованная по протоколу Noise: это самый быстрый и наиболее приватный вариант. Если Bluetooth недоступен, оно переходит на Nostr, используя публичный ключ получателя. Если недоступны оба способа, сообщения ставятся в очередь и отправятся автоматически, как только появится связь.
Что такое каналы по местоположению?Это географические чат-комнаты на основе координат geohash через ретрансляторы Nostr. Доступны уровни точности от городского квартала (#dr5rsj7) до страны или региона (#dr), что позволяет участвовать в местных или региональных обсуждениях без необходимости находиться в зоне действия Bluetooth.
Совместимо ли шифрование BitChat с другими клиентами Nostr?Нет. Формат приватных конвертов BitChat закрытый: он использует собственную конструкцию XChaCha20-Poly1305 внутри событий kind-1059, а не стандартное шифрование NIP-44. Поэтому он работает только с другими клиентами BitChat, хотя и передаётся через ретрансляторы Nostr.
Что произойдёт, если я активирую экстренную очистку?Тройное нажатие мгновенно удаляет все локальные данные с устройства. Это полезно для быстрой защиты информации в опасных ситуациях, например на протестах.
What are similar projects?EnvoyMesh, nebula, tailscale, EasyTier, simplex-chat, ZeroTierOne, gun, Signal-iOS
Which topics is it in?nostr, bluetooth-le, mesh-network, bluetooth, decentralized, p2p, messaging, chat, encryption, swift, offline, mobile
Creator
permissionlesstech
Size
113.6 MB
Stars
36.6K
Updated
CommitSep 24Releasev1.7.1Jul 31
Age
1y
Commits · 90 Days