featherChat/warzone/docs/USAGE.md

featherChat Usage Guide

Version: 0.0.46

---

Installation

Build from Source

Requirements: Rust 1.75+, cargo

git clone <repo-url>
cd warzone

cargo build --release

# Binaries output to target/release/:
#   warzone-server   — relay server (with embedded web client)
#   warzone-client   — CLI / TUI client

WASM Build (Web Client)

Requirements: wasm-pack

cd crates/warzone-wasm
wasm-pack build --target web
# Output in pkg/ — copy to the web client directory

Linux Cross-Compile

The scripts/build-linux.sh script builds Linux x86_64 binaries on a Hetzner Cloud VPS.

# Full pipeline: create VM, build, download binaries
./scripts/build-linux.sh --all

# Or step by step:
./scripts/build-linux.sh --prepare    # Create VM, install deps, upload source
./scripts/build-linux.sh --build      # Build release binaries on the VM
./scripts/build-linux.sh --transfer   # Download binaries to target/linux-x86_64/
./scripts/build-linux.sh --destroy    # Delete the VM

# One-command ship to all production servers:
./scripts/build-linux.sh --ship       # prepare + build + transfer + deploy + destroy

Server Configuration

warzone-server --bind 0.0.0.0:7700 --data-dir ./warzone-data

Flag	Default	Description
--bind	0.0.0.0:7700	Listen address
--data-dir	./warzone-data	sled database path
--enable-bots	(off)	Enable Bot API and BotFather

Environment variables:

Variable	Default	Description
WARZONE_ADMIN_PASSWORD	admin	Password for admin alias ops
RUST_LOG	info	Log level filter

---

Identity

Generate a New Identity

warzone-client init
# Prompts for passphrase
# Displays fingerprint + 24-word BIP39 mnemonic
# SAVE THE MNEMONIC — it is the only way to recover your identity

The seed is stored at ~/.warzone/identity.seed, encrypted with Argon2id + ChaCha20-Poly1305.

Recover from Mnemonic

warzone-client recover abandon ability able about above absent absorb abstract ...
# Prompts for passphrase, restores the same identity

View Your Identity

warzone-client info
# Fingerprint: a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4

In the TUI, use /info to display your fingerprint, /seed to display your 24-word recovery mnemonic, and /eth to display your Ethereum address.

Ethereum Address

Your ETH address is derived from the same seed via domain-separated HKDF. One seed, dual identity.

warzone-client eth
# Fingerprint: a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4
# Ethereum:    0x71C7656EC7ab88b098defB751B7401B5f6d8976F

Addressing

featherChat supports three addressing modes. All three work anywhere a peer address is accepted:

Format	Example	Description
Fingerprint	a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4	SHA-256 of Ed25519 pubkey, 8 groups of 4 hex digits
Alias	@alice	Human-readable, server-resolved
ETH address	0x71C7...976F	Ethereum address derived from the same seed

---

TUI Client

Launch the interactive terminal UI:

warzone-client chat --server http://your-server:7700
warzone-client chat @alice --server http://your-server:7700
warzone-client chat a3f8:c912:... --server http://your-server:7700

Complete Command Reference

Peer and Navigation

Command	Description
/peer <fingerprint>	Set DM peer by fingerprint
/p @alias	Set DM peer by alias (short form of /peer)
/peer 0x...	Set DM peer by ETH address
/r [message]	Reply to last DM sender; optionally include an inline message
/dm	Switch to DM mode (clear group context)

/peer a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4
/p @alice
/peer 0x71C7656EC7ab88b098defB751B7401B5f6d8976F
/r
/r hey, got your message
/dm

Groups

Command	Description
/g <name>	Switch to group (auto-joins if not a member)
/gcreate <name>	Create a new group (you become creator)
/gjoin <name>	Join an existing group
/gleave	Leave the current group
/gkick <fp_or_alias>	Kick a member (creator only)
/gmembers	List members of the current group with online status
/glist	List all groups on the server

/gcreate ops-team
/g ops-team
/gmembers
/gkick @mallory
/gleave
/glist

When in a group, the header bar shows #groupname and all messages are sent to that group.

Alias Management

Command	Description
/alias <name>	Register an alias for your fingerprint
/aliases	List all registered aliases
/unalias	Remove your alias

Alias rules: 1-32 alphanumeric characters (plus _ and -), case-insensitive, normalized to lowercase. TTL is 365 days of inactivity, with a 30-day grace period. Registration returns a recovery key — save it.

File Transfer

Command	Description
/file <path>	Send a file to the current peer or group

/file /path/to/document.pdf
/file ./photo.jpg

Files are split into 64 KB chunks, each encrypted with the Double Ratchet session key. The recipient reassembles and verifies a SHA-256 hash over the complete file. Maximum file size is 10 MB. Received files are saved to the current directory.

Contacts and History

Command	Description
/contacts or /c	List all contacts with message counts
/history or /h	Show message history for current peer (last 50)
/history <fp>	Show history for a specific peer

Identity and Security

Command	Description
/info	Show your fingerprint
/eth	Show your Ethereum address
/seed	Show your 24-word recovery mnemonic
/devices	List your active device sessions
/kick <device_id>	Revoke a specific device session

Friend List

Command	Description
/friend	List friends with online/offline status
/friend <address>	Add a friend by fingerprint or alias
/unfriend <address>	Remove a friend

The friend list is end-to-end encrypted and stored on the server as an opaque blob. The server cannot read it. Presence status (online/offline) is shown next to each friend.

General

Command	Description
/help or /?	Show command list
/quit or /q	Exit the TUI

Keyboard Navigation

Key	Action
PageUp / PageDown	Scroll messages by 10
Up / Down (when input is empty)	Scroll messages by 1
Ctrl+End	Snap scroll to bottom
Left / Right	Move cursor in input
Home / Ctrl-A	Beginning of line
End / Ctrl-E	End of line
Ctrl-U	Clear input
Ctrl-W	Delete word before cursor
Ctrl-C	Quit

Receipt Indicators

Indicator	Meaning
Single tick	Sent (no confirmation yet)
Double tick (gray)	Delivered (decrypted by recipient)
Double tick (blue)	Read (viewed by recipient)

---

Web Client

Access

Navigate to the server URL in a browser (e.g., http://your-server:7700). The web client generates a new identity automatically on first visit. Your seed is stored in localStorage — back it up using /seed.

The web client uses the same E2E encryption as the TUI, compiled to WASM.

URL Deep Links

The web client supports deep links for direct navigation:

URL	Effect
/message/@alice	Opens a DM with the alias @alice
/message/0xABC...	Opens a DM with an ETH address
/group/#ops	Opens the group #ops

Share these links to let someone jump straight into a conversation.

Clickable Addresses

Fingerprints and addresses displayed in messages are clickable. Clicking an address sets it as your DM peer. If you are currently typing, clicking copies the address instead.

Supported Commands

The web client supports the same slash commands as the TUI: /peer, /p, /r, /dm, /g, /gcreate, /gjoin, /gleave, /gkick, /gmembers, /glist, /alias, /aliases, /unalias, /file, /contacts, /c, /history, /h, /info, /eth, /seed, /friend, /unfriend, /devices, /kick, /help, /quit.

---

Voice Calls

Web Client

1. Set a peer (paste ETH address or use /peer @alias)
2. Click the Call button or type /call
3. Peer sees "Incoming call" and clicks Accept
4. Both allow microphone access
5. Audio flows -- speak normally
6. Click "End Call" or type /hangup to end

TUI Client

1. /call <peer_address> -- initiate call
2. Peer sees notification and can use /accept or /reject
3. Audio currently requires web client (TUI shows hint)
4. /hangup -- end call

Commands

Command	Description
/call	Start voice call with current peer
/accept	Accept incoming call
/reject	Reject incoming call
/hangup	End current call

Group Calls

Group calls allow multi-party audio within a group context. Any group member can initiate a call, and others can join at any time.

Command	Description
/gcall	Start a group call in the current group
/gjoin	Join an active group call
/gleave-call	Leave the group call (call continues for others)
/gmute	Toggle your microphone mute in the group call

Group call audio is routed through the WZP QUIC SFU relay. Media is transport-encrypted (QUIC TLS) but not E2E encrypted -- the relay can observe audio streams. MLS-based E2E encryption for group calls is planned.

---

Read Receipts

featherChat tracks message delivery and read status with three indicators:

Indicator	Symbol	Meaning
Sent	Single gray tick	Message sent to server, no confirmation yet
Delivered	Double gray tick	Recipient decrypted the message
Read	Double blue tick	Recipient viewed the message in their viewport

Read receipts are sent automatically when messages enter the visible area of the chat window. The system uses the sender's fingerprint for tracking and a dedup set to avoid sending duplicate read receipts for the same message.

---

Markdown Formatting

Messages support markdown formatting in both the TUI and web client:

Syntax	Result
**bold**	bold
*italic*	italic
`code`	inline code
# Header	Header (at start of line)
> quote	Block quote (at start of line)
- item	List item (at start of line)

Markdown is rendered inline in messages. In the TUI, bold, italic, and code spans use terminal attributes. In the web client, they render as HTML.

---

Admin Commands

Server administration commands for operators:

Command	Description
/admin-calls	List all active calls on the server
/admin-unalias <alias>	Remove any user's alias (requires admin password)

/admin-unalias prompts for the server's admin password (set via WARZONE_ADMIN_PASSWORD environment variable). /admin-calls currently has no auth protection -- an admin role system is planned.

---

Groups

Creating and Using Groups

/gcreate ops-team      # Create (you become creator)
/g ops-team            # Switch to group (auto-joins if needed)
/gjoin ops-team        # Explicitly join an existing group

Once in a group, all messages you type go to that group. The server fans out to all members.

Membership

• /gmembers shows all members with aliases and online status.
• The creator can kick members with /gkick <fingerprint_or_alias>.
• Any member can leave with /gleave.

Sender Keys

The protocol uses Sender Keys for efficient group encryption. Each member generates a random 32-byte chain key, distributes it to all other members over 1:1 encrypted channels, and encrypts group messages with their sender key. This gives O(1) encryption cost per message instead of O(N). Sender keys are rotated on member join or leave.

---

File Transfer

Files are transferred end-to-end encrypted through the relay server.

1. The sender reads the file and splits it into 64 KB chunks.
2. A FileHeader message is sent with the filename, total size, chunk count, and SHA-256 hash.
3. Each FileChunk is encrypted with the Double Ratchet session and sent sequentially.
4. The recipient reassembles all chunks and verifies the SHA-256 hash.
5. The completed file is saved to the current directory.

Maximum file size: 10 MB. Chunk size: 64 KB.

---

Friend List

The friend list provides presence tracking for contacts you care about.

• /friend <address> adds a friend (by fingerprint or alias).
• /friend lists all friends with their current online/offline status.
• /unfriend <address> removes a friend.

The friend list is encrypted client-side and stored on the server as an opaque blob. The server relays it but cannot read its contents.

---

Bots

Messaging Bots

Clients auto-detect bot aliases (names ending in Bot, bot, or _bot) and send messages as plaintext -- no E2E session is established. Simply use /peer @mybot_bot and type your message. The client handles the rest.

Creating Bots with BotFather

To create a bot, message @botfather:

1. /peer @botfather
2. Send a message requesting a new bot (e.g., "create WeatherBot")
3. BotFather registers the bot and returns the API token
4. Use the token to run your bot against the server's Bot API

BotFather is auto-created on servers that have --enable-bots enabled. It is the only way to create bots.

Bot Bridge for Telegram Compatibility

The tools/bot-bridge.py script provides a compatibility layer that lets you use existing Telegram bot libraries (python-telegram-bot, aiogram, Telegraf) with featherChat. It translates between the two APIs, handling differences like fingerprint-based addressing and numeric ID translation.

python tools/bot-bridge.py --token YOUR_BOT_TOKEN --server http://localhost:7700

See docs/BOT_API.md and docs/LLM_BOT_DEV.md for full Bot API documentation.

---

Federation

Federation connects two featherChat servers so that users on different servers can message each other transparently.

Setup

Each server needs a federation config file:

{
  "server_id": "alpha",
  "shared_secret": "long-random-string-shared-between-both-servers",
  "peer": {
    "id": "bravo",
    "url": "http://10.0.0.2:7700"
  },
  "presence_interval_secs": 5
}

Start the server with federation enabled:

warzone-server --bind 0.0.0.0:7700 --federation federation.json

How It Works

The two servers maintain a persistent WebSocket connection between them. When a client on server Alpha sends a message to a fingerprint registered on server Bravo, server Alpha forwards the message over the federation link. The recipient's server delivers it via their normal WebSocket connection. Presence information is exchanged on a configurable interval.

From the user's perspective, federation is transparent. You address peers the same way regardless of which server they are on.

---

Multi-Device

Setup

1. On the new device, recover from mnemonic: warzone-client recover <24 words>
2. Register with the server: warzone-client register --server http://...
3. Both devices share the same fingerprint and receive messages.

Device Management

• /devices lists all active sessions for your identity.
• /kick <device_id> revokes a specific device session.

Ratchet sessions are per-device and not synchronized between devices. Use encrypted backup/restore (warzone-client backup / warzone-client restore) to transfer session state.

---

Encrypted Backup and Restore

# Export sessions and pre-keys, encrypted with your seed
warzone-client backup my-backup.wzb

# Restore on another device (requires same seed)
warzone-client restore my-backup.wzb

The backup contains all Double Ratchet sessions and pre-key secrets. It is encrypted with HKDF(seed, info="warzone-history") + ChaCha20-Poly1305.