Documentation
Everything you need to know about the Y protocol, from cryptographic identities to decentralized peer discovery.
Getting Started
Y is designed to be zero-config. Once installed, simply run:
y openOn first launch, Y bootstraps the Tor client and creates your unique hidden service. This may take ~30 seconds. Subsequent launches are nearly instant.
TUI Navigation Guide
The Y interface is a keyboard-driven Terminal User Interface (TUI). There are no menus — just keybindings.
Sending a Message
To share a public thought: press n, type your message, and hit Enter. It will be signed and gossiped to the network.
To send a private DM: navigate to the DM view with d, select a contact, and compose.
Using Communities
Switch to the community view with c. You can join open communities instantly or request access to private ones.
Press Enter on a community to enter the group chat.
Pro Tip: The Command Mode
Press : to enter command mode. This allows you to perform administrative actions like :alias new-name or :peers to check your connection health.
Identity & Keys
In Y, your keypair is your identity. There are no accounts, passwords, or central registries.
The Address
A permanent cryptographic identifier derived from your Ed25519 public key. It looks like root:a8Kx2m...
The Alias
A human-readable name (e.g., phantom-cipher). Aliases are not unique; they are paired with a shortcode for disambiguation.
Your keys are stored locally at ~/.root-chat/db. If you lose this directory, you lose your identity and any DMs stored locally.
Messaging & Encryption
Every message in the network is cryptographically signed. If a single bit is altered, the receiving peer will reject the message.
| Type | Visibility | Encryption |
|---|---|---|
| Post | Public broadcast | Signed only |
| DM | Sender + Recipient | X25519 + ChaCha20Poly1305 |
| Community | Group members | Signed, group-scoped |
Direct Messages (DMs) use an end-to-end encrypted tunnel. The mediator (or any relay) only sees encrypted blobs of data; they cannot read your private conversations.
What is a Mediator?
A mediator (also called a seed node or discovery node) is simply a regular Y peer that stays online 24/7 to act as a lighthouse for the network. It has no special privileges — it cannot read your DMs, censor posts, or control the network in any way.
On startup, your client connects to a known mediator automatically (via the built-in SEED_NODES list) and uses it to bootstrap into the Kademlia DHT. Once in the DHT, your peer discovers other active peers and begins gossiping messages directly.
Key Properties:
- Just a regular peer running
y serveheadless - No elevated permissions in the protocol
- Cannot decrypt your DMs (X25519 + ChaCha20Poly1305)
- Cannot censor or modify your posts (Ed25519 signatures)
- Anyone can run one — the more, the more resilient
What Unlocks When Connected
Connecting to a mediator isn't required for core messaging, but it unlocks network-wide discovery features:
Global Timeline
Unfiltered posts from across the entire network. Share ideas, discuss freely, no moderation from above. Every peer you discover becomes a relay — posts propagate organically.
User Discovery
Search and find other users by alias or address. Only available when connected to a mediator — direct peer connections don't expose the network directory. Press / in the TUI to search.
Communities (Experimental)
Create open or private groups with owner-controlled membership. Self-governed, no central moderation. Join requests queue up for private communities. Still evolving — expect rough edges.
What Happens If All Mediators Go Down?
Nothing is lost. Your messages, identities, and DMs remain safe. The system is perfectly functional for direct communication.
If all mediators are offline, you simply connect to others manually by sharing your .onion address, or by being active with peers you've already connected to. The DHT continues to operate among connected peers — mediators are only needed for initial discovery.
# Connect directly to a known peer
Y_PEER=someone.onion:7331 y open
# Or specify multiple custom seeds
Y_SEEDS=seed1.onion:7331,seed2.onion:7331 y openRun Your Own Mediator
Anyone can run a seed node. The more seeds, the more resilient the network becomes. It runs headless — no TUI, just the network engine.
# On any always-on server (EC2, VPS, Raspberry Pi, etc.)
y serve
# Custom port (default: 7331)
Y_PORT=8080 y serve
# Limit stored posts (default: 1000)
y serve --max-posts 500
On startup, y serve prints its .onion address. Submit it as a PR to SEED_NODES in src/network/engine.rs to help bootstrap the network for everyone.
Direct Peer Connection (No Mediator Needed)
You don't need a mediator to use Y. If you already know someone's .onion address, you can connect directly:
# Your friend shares their address (from Profile view in TUI, press 'y')
Y_PEER=abc123def456.onion:7331 y openOnce connected directly, you'll discover their peers, and their peers' peers — the network grows organically. This is how Y worked before mediators existed, and it still works today.
Privacy & Security FAQ
Does Y store my data on a server?
No. All data is stored locally on your machine (Sled DB) or distributed across the network in the DHT. There is no "Y Cloud" or central database.
Can my IP address be leaked?
Y uses Tor Hidden Services. All traffic is routed through the Tor network, meaning your real IP is never exposed to peers or mediators. Your identity is your .onion address.
Who can read my DMs?
Only you and the recipient. DMs are encrypted using a session key established via X25519 Diffie-Hellman. Even if a mediator relays the message, they only see an encrypted blob.
Is the Global Timeline anonymous?
Yes. While your public key is attached to your post for verification, it does not reveal your real-world identity. You can change your alias at any time via :alias.
Network Architecture
Message Flow
- Sign: Every message signed with your Ed25519 identity key
- Encrypt (DMs): X25519 Diffie-Hellman + ChaCha20Poly1305 for recipient only
- Route: Gossip protocol — every peer relays to its neighbors
- Store: Kademlia DHT replicates posts across nodes (persist offline)
- Verify: Recipients verify signatures; tampered messages rejected
No central server exists. The mediator is only a convenient entry point — a peer you can always reach. Once you're in the mesh, you're a full participant.
Troubleshooting
"Network connection failed" or "Cannot reach mediator"
Ensure the Tor daemon is running on your system. Y relies on the system Tor process to route traffic. Use systemctl status tor to check.
"Identity lost" or "Database corrupted"
Your identity is stored in ~/.root-chat/db. If this folder is deleted, you cannot recover your previous address. Back up this folder to preserve your identity.
"Direct connection failed"
Verify that the peer you are connecting to is currently online and their .onion address is correct. Remember that Tor connections can sometimes take a few seconds to establish.
Key Commands Reference
| Key / Command | Action |
|---|---|
| t | Timeline (public posts) |
| d | Direct messages |
| c | Communities |
| / | Search users (requires mediator) |
| p | Profile / identity (press 'y' to copy .onion) |
:peers |
Show connected peer count |
:search <query> |
Search users by alias/address |
:create <name> |
Create open community |
:create <name> private |
Create private community (approval required) |
:join <id> |
Join a community |
CLI Flags
# Override seed nodes
Y_SEEDS=seed1.onion:7331,seed2.onion:7331 y open
# Connect to specific peer directly
Y_PEER=someone.onion:7331 y open
# Custom port for serve
Y_PORT=8080 y serveReady to dive in?
Read the full technical specifications on GitHub, or jump straight to installation.