Breakout-room NPM

breakout-room

A fully-featured implementation of @agree-able/room demonstrating secure peer-to-peer chat rooms with identity verification. Perfect for studying how to build p2p applications or for direct use in your projects.

Quick Start

npx breakout-room

Start a host

Join as a participant

The CLI includes an interactive menu system that guides you through all available options and configurations.

Usage Modes

Command-line switches are available to reduce the amount of interactive menu choices. You can provide enough to start the app automatically.

1. Start a Room Manager

Create a hub for hosting multiple rooms with configurable:

Room purpose and rules
Identity verification requirements (Keybase integration)
Automatic or manual participant validation
Persistent configuration via JSON

Example starting a room manager:

npx breakout-room --mode=roomManager --reason="Code Review Sessions" --rules="Professional conduct"

2. Join an Existing Room

Connect to an existing room using one of these methods:

agreeableKey: A reusable connection key with room entry requirements
domain: Lookup room details via DNS TXT record
invite: One-time invite code

Example joining with domain:

npx breakout-room --mode=join --domain=example.com --hostProveWhoami=true --agree=true --autoValidate=true

hostProveWhoami the host will show their keybase username and domain ownership (if available)
autoValidate if the host proves username and and domain, dont prompt to enter room
agree just agree to both the reason and rules of the room

3. Simple Room

Quick setup for basic chat functionality without advanced features.

DNS Integration

When running a room manager, you'll receive an agreeableKey. To allow easy discovery, add it to your domain's DNS:

Create a TXT record for: _breakoutroom.yourdomain.com
Set the value to: key=YOUR_AGREEABLE_KEY

Users can then connect using just your domain:

npx breakout-room --domain=yourdomain.com

Keybase Verification

Keybase integration provides cryptographic identity verification. To use this feature, you need:

A Keybase account with:
- An active username
- A PGP key added to your verification chain
- Access to your private key for message signing
- Your public key accessible at: https://keybase.io/USERNAME/pgp_keys.asc
For room hosts:
- Verify domain ownership through Keybase's DNS TXT verification method
- This allows participants to cryptographically verify both your identity and domain control

The verification process happens automatically when enabled, ensuring secure identity verification without manual steps.