EchoHub/README.md

EchoHub

EchoHub

No tracking. No subscriptions. No "enhanced AI features". Just chat.

What • Setup • IRC • Deploy • Commands • Config • License

Website • Public Servers • Documentation

---

What is this?

Chat apps used to be simple. You connected to a server, joined a channel, and talked to people. No one was mining your messages for ad targeting, no one was selling your "engagement metrics", and the app didn't need 2GB of RAM to display text.

EchoHub is a return to that. Self-hosted, IRC-inspired chat that runs in your terminal. You own the server, you own the data, and the client won't try to upsell you on a premium tier.

Each server is fully independent — no central authority, no account federation, no corporate overlord. Just spin one up and go.

graph TD
    subgraph Server["Server"]
        ChatSvc["ChatService"]
        Hub["SignalR ChatHub"]
        IRC["IRC Gateway :6667"]
        Auth["JWT Auth"]
        DB["SQLite DB (EF Core)"]
        Files["File Storage"]
    end

    subgraph Clients["Clients"]
        TUI["Terminal GUI (TUI)"]
        IRCClient["IRC Client (irssi, WeeChat, ...)"]
    end

    TUI -- "WebSocket" --> Hub
    TUI -- "REST" --> Auth
    IRCClient -- "TCP" --> IRC
    Hub --> ChatSvc
    IRC --> ChatSvc
    ChatSvc --> DB
    Auth --> DB
    Files --> DB

What you get

Server

• Self-hostable — your server, your rules, your data
• Docker ready — docker compose up -d and you're done
• Real-time messaging via SignalR WebSockets
• IRC gateway — native IRC clients connect alongside TUI users, full cross-protocol messaging
• JWT auth with short-lived access tokens and 30-day refresh tokens
• Channels — create, set topics, delete (no 47-step permission wizard required)
• Moderation — ban, mute (timed or permanent), kick, role assignment
• Registration control — open, invite-code-gated (/invite), or closed; codes live in your own database
• File & image uploads with actual validation (magic bytes, not just trusting the extension)
• Image-to-ASCII — because images in a terminal is objectively cool
• Presence tracking — online/away/DND/invisible with custom status messages
• Rate limiting — in case someone gets too excited
• Auto-restart on crash with exponential backoff — it picks itself back up
• Serilog logging — console + rolling file, because Console.WriteLine isn't a logging strategy
• Zero config first run — generates its own JWT secret and config on launch

Client

• Runs in your terminal — no browser, no Electron, no 500MB of bundled Chromium
• 14 built-in themes — including hacker for when you want to feel like you're in a movie
• Slash commands — /join, /send, /status, /theme, etc.
• Colored nicknames — pick your hex color, express yourself
• Clickable everything — usernames, @mentions, #channels — just press Enter
• File/image sharing — local files or URLs; drag & drop a file onto the terminal to send it; save the original behind any ASCII-art image
• End-to-end encrypted rooms — password-protected channels are encrypted with a passphrase-derived key that never reaches the server, so not even the server owner can read messages or files (they can still see counts and storage size)
• Replies — quote a message, jump back to the original; being replied to pings like a mention
• Your data is yours — /export everything the server holds about you; /deleteaccount removes it
• Multi-server — save and switch between servers
• Auto-reconnect — drops happen, it rejoins your channels automatically
• Auto-updater — updates in-place with automatic rollback if something goes wrong
• Message history on join — you won't miss context

Getting Started

Install the Client

Windows (Chocolatey):

choco install echohub

Linux / macOS:

curl -sSfL https://raw.githubusercontent.com/HueByte/EchoHub/master/scripts/install.sh | sh

Manual download: grab a self-contained binary from Releases — no runtime needed, just run it.

Host a Server

Docker (recommended):

cp .env.example .env
docker compose up -d

Pre-built images on GHCR — linux/amd64 and linux/arm64.

From source:

dotnet run --project src/EchoHub.Server

Requires .NET 10 SDK. First run does everything for you:

1. Creates appsettings.json from the example config
2. Generates a secure JWT secret
3. Creates the database with a #general channel

Run the Client (from source)

dotnet run --project src/EchoHub.Client

Connect, register, chat. That's the whole onboarding flow.

Build from Source

dotnet build src/EchoHub.slnx

IRC Gateway

EchoHub includes a built-in IRC protocol gateway. Any standard IRC client can connect to the same server and chat alongside TUI users — messages flow both ways in real time.

Enable It

In the server's appsettings.json:

{
  "Irc": {
    "Enabled": true,
    "Port": 6667,
    "ServerName": "echohub",
    "Motd": "Welcome to EchoHub IRC Gateway!"
  }
}

Connect

# irssi
irssi -c your-server.com -p 6667 -w <password> -n <username>

# WeeChat
/server add echohub your-server.com/6667 -password=<password> -nicks=<username>
/connect echohub

Auth works via PASS/NICK/USER or SASL PLAIN. New usernames are auto-registered on first connect — no separate signup needed.

What Works

Feature	How it maps to IRC
Text messages	Standard PRIVMSG (long messages split at ~400 byte chunks)
/me actions	Native CTCP ACTION in both directions
Replies	TUI replies arrive as > nick: snippet | text
Images	[Image: filename] + download URL + ASCII art line-by-line
File uploads	[File: filename] /api/files/{id}
Channels	JOIN, PART, NAMES, TOPIC, LIST
Presence	AWAY, WHO, WHOIS
Status	Maps to IRC away/here

TLS

If running behind nginx (recommended), let nginx handle TLS -- see Deployment with nginx below.

For direct TLS without a reverse proxy, the IRC gateway can terminate TLS itself:

{
  "Irc": {
    "TlsEnabled": true,
    "TlsPort": 6697,
    "TlsCertPath": "/path/to/cert.pfx",
    "TlsCertPassword": "your-password"
  }
}

Client Commands

Command	Description
/join <channel> [password]	Join a channel (passphrase for encrypted channels)
/me <action>	Action message — * nick waves (native CTCP ACTION over IRC)
/banner <text>	Render short text as a big ASCII banner
/passwd <old> <new>	Change the current encrypted channel's passphrase (creator only)
/size [s|m|l]	ASCII-art size for attached images (no arg = picker)
/downloadpath [path]	Set the download folder (no path = native folder picker)
/leave	Leave current channel
/topic <text>	Set channel topic (creator only)
/send <file or URL>	Upload a file or image
/status <online|away|dnd|invisible>	Set your status
/status msg <text>	Set a status message (keeps your status; empty text clears it)
/nick <name>	Set display name
/color <#hex>	Set nickname color
/theme <name>	Switch theme
/profile	Open profile editor
/users	List online users in channel
/servers	Manage saved servers
/invite [uses] [hours]	Create a registration invite code (Admin+); also list / revoke <code>
/export	Download everything the server stores about you as JSON
/deleteaccount	Permanently delete your account (password re-confirmed)
/help	Show help
/quit	Exit

Message actions: right-click a message for a context menu — reply (quotes the message; Esc cancels a pending reply), delete, save/download/play its attachment, mention the sender, view their profile, or copy the text. (Keyboard alternative: press F6 to focus the message list, select with the arrow keys, and press Delete; F6 again returns to the input.) You can always delete your own messages; moderators and above can delete others' messages, but only from users below their own role.

Themes

/theme <name> to switch:

Theme	Vibe
default	Gray on black — clean and quiet
transparent	White on black — for fancy transparent terminals
transparentlight	Black on transparent — dark characters for light transparent terminals
classic	White on blue — IRC nostalgia
light	Black on white — for the brave
hacker	Green on black — I'm in
solarized	Cyan/yellow on dark gray — for the refined
dracula	Purple accents on black — the classic dark theme
monokai	Yellow highlights on black — warm and familiar
nord	Cool blues — arctic vibes
gruvbox	Earthy yellows on black — retro warmth
ocean	Cyan on deep blue — underwater aesthetics
highcontrast	Bright yellow on black — maximum readability
rosepine	Muted pinks on black — cozy and soft

Configuration

appsettings.json is auto-generated on first run. Tweak what you need:

Key	Default	Description
Urls	http://0.0.0.0:5000	Listen address and port
ConnectionStrings:DefaultConnection	(empty — app directory)	SQLite connection string
Jwt:Secret	(auto-generated)	JWT signing key
Server:Name	My EchoHub Server	Server display name
Server:Description	A self-hosted EchoHub chat server	Server description
Server:Registration	open	open, invite (codes via /invite, Admin+), or closed
Server:PublicServer	false	List on the public directory
Server:PublicHost	(empty)	Public hostname for directory listing
Irc:Enabled	false	Enable the IRC gateway
Irc:Port	6667	IRC listen port
Irc:TlsEnabled	false	Enable TLS for IRC
Irc:TlsPort	6697	IRC TLS port
Irc:ServerName	echohub	IRC server name in protocol messages
Irc:Motd	Welcome to EchoHub IRC Gateway!	Message of the day
Cors:AllowedOrigins	(all origins)	CORS whitelist

Logging uses Serilog — console + daily rolling files with 14-day retention. Configure in the Serilog section.

Deployment with nginx

Most production deployments run behind nginx. Here's a config that handles both the HTTP/WebSocket server and the IRC gateway:

# HTTP + WebSocket (EchoHub Server API + SignalR)
server {
    listen 443 ssl;
    server_name echohub.example.com;

    ssl_certificate     /etc/letsencrypt/live/echohub.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/echohub.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for SignalR WebSocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;

        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    # Increase max upload size for file sharing
    client_max_body_size 10m;
}

# HTTP → HTTPS redirect
server {
    listen 80;
    server_name echohub.example.com;
    return 301 https://$host$request_uri;
}

# IRC TLS (port 6697 → plain IRC on 6667)
stream {
    upstream irc_backend {
        server 127.0.0.1:6667;
    }

    server {
        listen 6697 ssl;
        proxy_pass irc_backend;

        ssl_certificate     /etc/letsencrypt/live/echohub.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/echohub.example.com/privkey.pem;
    }
}

With this setup, keep the EchoHub IRC gateway's TlsEnabled set to false — nginx terminates TLS. See the full example at examples/nginx.conf.

Project Structure

src/
├── EchoHub.Core/            # Shared models, DTOs, contracts, validation
│   ├── Constants/           # ValidationConstants, HubConstants
│   ├── Contracts/           # IChatService, IChatBroadcaster, IEchoHubClient
│   ├── DTOs/                # Record DTOs
│   └── Models/              # Entity models
│
├── EchoHub.Server/          # ASP.NET Core server
│   ├── Auth/                # JWT token service
│   ├── Controllers/         # REST API endpoints
│   ├── Data/                # EF Core DbContext + migrations
│   ├── Hubs/                # SignalR ChatHub
│   ├── Services/            # ChatService, presence, file storage, image processing
│   └── Setup/               # First-run setup, DB initialization
│
├── EchoHub.Server.Irc/      # IRC protocol gateway
│   ├── IrcGatewayService    # TCP listener (BackgroundService)
│   ├── IrcCommandHandler    # IRC command dispatch (JOIN, PRIVMSG, etc.)
│   ├── IrcBroadcaster       # Fans chat events to IRC connections
│   └── IrcMessageFormatter  # MessageDto → IRC PRIVMSG lines
│
├── EchoHub.Client/          # Terminal.Gui TUI client
│   ├── Config/              # Client configuration
│   ├── Services/            # API client, SignalR connection
│   ├── Themes/              # 13 built-in themes
│   └── UI/                  # MainWindow, dialogs, chat renderer
│
└── EchoHub.slnx             # Solution file

License

MIT — do whatever you want with it.