XtermChat
Documentation

01 Introduction

XtermChat is a lightweight, self-hosted chat system built for the terminal. Unlike third-party platforms, XtermChat stores nothing on external servers. You deploy the server on your own VPS, connect with the CLI client or a browser, and all messages stay on infrastructure you control.

It is designed for developers and sysadmins who want something simple that just works — without the overhead of Matrix, the enterprise focus of Mattermost, or the data concerns of Slack.

02 How it works

XtermChat has two parts: a server you deploy on a VPS, and a client your team installs on their machines. They communicate over a simple REST API with JSON payloads.

03 Requirements

04 Server setup

SSH into your VPS and follow these steps. The entire process takes about 5 minutes.

git clone https://github.com/dnysaz/xtc-server.git
cd xtc-server

pip3 install flask flask-cors werkzeug

sudo ufw allow 8080
sudo ufw enable
sudo ufw status

python3 server.py start
# [*] Server started in background (PID: 12345)

curl http://localhost:8080
# {"service": "XtermChat Gateway", "status": "online", "version": "1.1"}

File structure

Custom port

Default is 8080. Edit the bottom of server.py to change it:

elif command == "run_internal":
    app.run(host='0.0.0.0', port=9000)  # ← change here
else:
    app.run(host='0.0.0.0', port=9000)  # ← and here

05 Client setup

macOS / Linux

git clone https://github.com/dnysaz/xtc-client.git
cd xtc-client

make install

xtc

Windows (native — no WSL needed)

git clone https://github.com/dnysaz/xtc-client.git
cd xtc-client
pip install -r requirements.txt

python xtc.py

06 First time use

07 CLI commands

# Connect to server
xtc connect @103.45.67.89:8080

# Create a private room with password
xtc create:room @devteam mypassword

# Interactive room creation
xtc create:room

# Join a private room (password prompted automatically)
xtc start:chat @devteam

08 Chat interface

Running xtc start:chat opens a full terminal UI with three panels and a dual-focus mode system.

Focus modes

Keyboard shortcuts

Global

INPUT MODE

CHAT MODE (after pressing Tab)

09 Web interface

XtermChat includes a browser-based UI. Start it with:

xtc start:web
# URL: http://localhost:5000

Open http://localhost:5000. Enter server IP, port, username, and a 5-digit PIN to connect.

Web vs CLI

10 Room management

# Public room — anyone on the server can join
xtc create:room @general

# Private room — password required
xtc create:room @team secretpassword

# Interactive mode — prompts for name, password, description
xtc create:room

Private rooms appear in xtc list:rooms with a LOCKED label. Passwords are stored as bcrypt hashes — the raw password is never saved.

Creator privileges

When you create a room, your hardware UUID is recorded as creator_pin. Only you (from the same machine) can:

• Delete the room: xtc delete:room @roomname
• Purge all messages: type :purge inside chat

11 Emoji shortcuts

Type any shortcut in a message — it auto-converts when you press Enter. Type :e to open the reference panel inside the chat.

12 Identity & security

How CLI identity works

Server-side validation

Default setup uses HTTP, acceptable for private/internal networks. For public-facing deployments use HTTPS — see the next section.

13 HTTPS setup

No client code changes needed. Just point your client at an https:// URL after setup.

Option A — Caddy (recommended)

Automatically obtains and renews SSL certificates from Let's Encrypt.

sudo apt install caddy -y

# /etc/caddy/Caddyfile
yourdomain.com {
    reverse_proxy localhost:8080
}

sudo systemctl reload caddy

Option B — Nginx + Let's Encrypt

sudo apt install nginx certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com

server {
    listen 443 ssl;
    server_name yourdomain.com;
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

After setup, update your client:

xtc connect @yourdomain.com

14 Server management

Start / stop

python3 server.py start    # start in background
python3 server.py stop     # stop
python3 server.py          # run in foreground (debug)

Check status & logs

cat server.pid
ps aux | grep server.py
tail -f server.log
grep "ERROR\|Exception" server.log

systemd service (auto-restart on reboot)

# /etc/systemd/system/xtermchat.service
[Unit]
Description=XtermChat Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/xtc-server
ExecStart=/usr/bin/python3 /home/ubuntu/xtc-server/server.py run_internal
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable xtermchat
sudo systemctl start xtermchat

Update & backup

# Update
cd xtc-server && python3 server.py stop && git pull && python3 server.py start

# Backup — entire state is one file
cp xtc.db xtc_backup_$(date +%Y%m%d_%H%M).db

15 Database

Everything is stored in xtc.db — a single SQLite file auto-created on first run.

# Inspect with check_db.py
python3 check_db.py

# Direct SQLite
sqlite3 xtc.db
.tables
SELECT * FROM rooms;
SELECT COUNT(*) FROM messages WHERE room='general';
SELECT * FROM messages ORDER BY id DESC LIMIT 20;
.quit

# Full reset
python3 server.py stop && rm xtc.db && python3 server.py start

16 API reference

Base URL: http://YOUR_SERVER:8080 — all endpoints return JSON.

{"status": "online", "service": "XtermChat Gateway", "version": "1.1"}

// Request
{"user": "ketut", "pin": "12345"}

// 200 — PIN matches    {"status": "success", "message": "Welcome back"}
// 201 — new user       {"status": "success", "message": "New identity registered"}
// 403 — PIN mismatch   {"status": "failed", "message": "Identity locked to another device/PIN."}

{"status": "success", "count": 2, "rooms": [
  {"name": "general", "has_password": false, "creator": "KETUT",
   "description": "General chat", "created_at": 1741234567}
]}

{"room": "general", "password": "", "user": "KETUT", "content": "Hello world", "pin": "UUID"}
// 201 → ok | 403 → PIN mismatch | 400 → empty or too long (max 4000 chars)

GET /messages/general?password=
// Response: [{"sender": "KETUT", "content": "Hello", "pin": "UUID", "timestamp": "2026-03-14 08:30:00"}]
// 401 → password required

{"room": "general", "user": "ketut", "pin": "UUID"}
// 200 → ok | 403 → Unauthorized: Hardware ID mismatch

{"room": "general", "user": "ketut", "pin": "UUID"}
// 200 → ok | 403 → Unauthorized: Hardware ID mismatch

17 Troubleshooting

Connection refused

curl http://YOUR_IP:8080       # test direct access
sudo ufw status               # check firewall
cat server.pid                # check if server running
ps aux | grep server.py

Identity locked to another device

Username registered from a different machine. Options:

# Option 1 — use a different system username
# Option 2 — admin removes the old entry
sqlite3 xtc.db "DELETE FROM users WHERE username='yourname';"

Access denied on purge or delete

You must be on the same machine that created the room. Hardware PIN is device-specific.

Server won't start — port in use

sudo lsof -i :8080
sudo kill -9 <PID>
rm server.pid && python3 server.py start

Copy not working (Linux)

sudo apt install xclip   # or: sudo apt install xsel

Chat scroll not working

Minimum terminal size is 80×24. Press Tab to enter CHAT MODE first, then use arrow keys or PageUp/PageDown.

Server crashed / not responding

tail -50 server.log
rm server.pid && python3 server.py start

18 FAQ

xtc connect @localhost:8080

sqlite3 xtc.db "DELETE FROM users WHERE username='yourname';"

# Server
cd xtc-server && python3 server.py stop && git pull && python3 server.py start

# Client
cd xtc-client && git pull && make install