Warning
Beam is on active development stage and currently it's unusable.
Beam is a peer-to-peer sharing app for Android. One device starts a beam and shows a short code, the other enters it, and they're connected without any internet or accounts or cables.
Under the hood it uses Google's Nearby Connections API, which automatically picks the best available transport (Bluetooth, BLE, or Wi-Fi) without any manual setup.
- Nearby discovery -> find other Beam devices around you in real time
- Short code pairing -> hosts share a 6-character code, joiners type it in and connect automatically
- No internet needed -> everything happens directly between devices
- Modern UI -> fully built with Jetpack Compose and a custom in-house design system
| Layer | Technology |
|---|---|
| Language | Kotlin |
| UI | Jetpack Compose |
| Networking | Google Play Services Nearby Connections |
| Transfer protocol | BEAM/1, custom app-level protocol -> see PROTOCOL.md |
| Architecture | MVVM with ViewModel |
| Linting | ktlint (CLI) |
- Android Studio (latest stable recommended)
- JDK 17 or newer
- An Android device running Android 8.0 (API 26) or newer
- Google Play Services on the device (required for Nearby Connections)
Note
Nearby Connections does not work on emulators - you need two physical devices to test discovery and transfer.
git clone https://github.com/greenbugx/Beam.git
cd Beam
./gradlew assembleDebugThe APK will be available at app/build/outputs/apk/debug/.
To install directly on a connected device:
./gradlew installDebugapp/src/main/java/com/beam/app/
├── MainActivity.kt # Entry point and screen routing
├── network/ # Nearby Connections wrapper
├── permissions/ # Runtime permission handling
├── session/ # Session state, ViewModel, and models
├── ui/
│ ├── components/ # Reusable UI components (buttons, etc.)
│ ├── files/ # Beam workspace (shared files, transfers, peers)
│ ├── home/ # Home screen (create or join)
│ ├── join/ # Code entry screen for joining
│ ├── nearby/ # Nearby beam browsing and its code entry
│ ├── room/ # Active session screen (code display, beams list, peers)
│ └── theme/ # Design system (colors, typography)
└── util/ # Beam code generation and validation
- Create -> one device starts a beam and gets a short code
- Join -> the other device enters the code, or taps a discovered beam under nearby beams and enters its code (QR coming later)
- Connect -> the joiner's device finds the beam advertising that code and connects automatically
- Send -> files are negotiated and transferred in verified chunks by the app-level protocol (file transfer is in active development, see PROTOCOL.md)
Beam is built milestone by milestone — see TODO.md for the full plan:
- M1 — Foundation: native app, custom design system, home screen, create/join flows, Beam codes
- M2 — Sessions & Connectivity: discovery, advertising, connection handling, peer tracking
- M3 — Single File Transfer: SAF picker, transfer protocol (BEAM/1), integrity verification
- M4+ — Large files, multi-user rooms, resumable transfers, QR joining, and more
- PROTOCOL.md -> the authoritative BEAM/1 protocol design: sessions, messages, chunking, integrity and security.
- TODO.md -> milestone plan
See CONTRIBUTING.md for setup, code style (ktlint), commit conventions, and the PR checklist.
Found a vulnerability? Please report it privately - see SECURITY.md.
This project is licensed under the GNU AGPL-3.0