AEGIS server
setup for Ubuntu 24.04

1. Architecture overview

VPS (Ubuntu 24)
├── headless_server.py   — AEGIS chat relay (port 9999)
├── monitor_api.py       — Admin dashboard API (port 8080)
├── crypto_manager.py    — Encryption module
└── network_manager.py   — Network module

Your Computer (Windows/Mac/Linux)
├── AegisChat client     — connects to VPS port 9999
└── aegis_dashboard.html — open in browser, polls VPS port 8080

PORT 9999 AEGIS peers connect here (public)
PORT 8080 Dashboard API — restrict to your IP only

2. VPS requirements

Any basic Hetzner CX11 or equivalent is sufficient for a small group.

3. Initial server setup

SSH into your VPS as root:

ssh root@YOUR_VPS_IP

Create a dedicated user (do not run as root):

adduser aegis
usermod -aG sudo aegis
su - aegis
cd /home/aegis

4. Install dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv git build-essential
pip3 install --break-system-packages pyside6 pynacl
pip3 install --break-system-packages --ignore-installed flask flask-cors

Verify:

python3 -c "import PySide6; import nacl; import flask; print('✅ All dependencies installed')"

5. Upload server files

On the VPS, create the directory:

mkdir -p /home/aegis/aegis_server

From your local computer upload using scp:

scp headless_server.py monitor_api.py crypto_manager.py network_manager.py aegis@YOUR_VPS_IP:/home/aegis/aegis_server/

Verify:

ls -la /home/aegis/aegis_server/

6. Configure the API secret & token

Step 1 — Choose a secret phrase (generate random):

python3 -c "import secrets; print(secrets.token_hex(32))"

Copy the output — this is your AEGIS_API_SECRET.

Step 2 — Generate the dashboard token (replace secret):

python3 -c "
import hmac, hashlib
secret = b'PASTE_YOUR_SECRET_HERE'
token  = hmac.new(secret, b'aegis-monitor', hashlib.sha256).hexdigest()
print('Your dashboard token:', token)
"

Save both — secret goes into the service file, token into the dashboard HTML.

7. Create the systemd service

sudo nano /etc/systemd/system/aegis.service

Paste the following (replace placeholders):

[Unit]
Description=AEGIS Chat Server
After=network.target

[Service]
Type=simple
User=aegis
WorkingDirectory=/home/aegis/aegis_server
ExecStart=/usr/bin/python3 /home/aegis/aegis_server/headless_server.py -p 9999 --password YOUR_CHAT_PASSWORD
Environment="AEGIS_API_SECRET=YOUR_SECRET_PHRASE_FROM_STEP_6"
Restart=always
RestartSec=5
StandardOutput=append:/var/log/aegis.log
StandardError=append:/var/log/aegis-error.log

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable aegis
sudo systemctl start aegis

Check status:

sudo systemctl status aegis
tail -20 /var/log/aegis.log

Expected output includes: ✅ Server running on YOUR_VPS_IP:9999

8. Open firewall ports

sudo ufw allow 9999/tcp
sudo ufw allow from YOUR_HOME_IP to any port 8080
sudo ufw enable
sudo ufw reload
sudo ufw status

Or use SSH tunnel (more secure):

ssh -L 8080:localhost:8080 aegis@YOUR_VPS_IP -N

9. Start & verify

ss -tlnp | grep -E '9999|8080'

Test API health from browser:

http://YOUR_VPS_IP:8080/api/health

Expected: {"ok": true, "ts": ...}

10. Configure the admin dashboard

Open aegis_dashboard.html locally in a text editor. Find the CFG block:

const CFG = {
  apiBase:   "http://YOUR_VPS_IP:8080",   // or http://localhost:8080
  apiToken:  "PASTE_YOUR_TOKEN_HERE",
  dashUser:  "admin",
  dashPass:  "aegis2024",
  ...
};

Fill in your VPS IP, the token from step 6, and choose a dashboard user/pass. Save and open the HTML in your browser.

11. Client: remove saved fingerprint on server restart

Because the server generates a new keypair on every restart (forward secrecy), clients will reject the connection. Delete the old fingerprint from Windows registry:

reg delete "HKCU\Software\AegisChat\TrustedFingerprints" /v "server_fingerprint" /f

Or create a batch script:

@echo off
reg delete "HKCU\Software\AegisChat\TrustedFingerprints" /v "server_fingerprint" /f
echo Fingerprint cleared. You can now connect.
pause

12. Troubleshooting

Live logs:

tail -f /var/log/aegis.log
sudo journalctl -u aegis -f

Quick reference

sudo systemctl start|stop|restart aegis
sudo systemctl status aegis
tail -f /var/log/aegis.log
ss -tlnp | grep -E '9999|8080'
sudo ufw status

— AEGIS headless server, end‑to‑end encrypted relay —