VAGUS

Overview

This guide documents production deployment of the VAGUS relay server from ../relay-server using:

• Node.js runtime for the relay process.
• systemd for daemon lifecycle management.
• nginx as TLS terminator and reverse proxy.
• Optional Redis persistence (recommended production mode).

Architecture

Endpoints served by relay:

• POST /pair
• POST /revoke
• GET /health
• WSS /connect/<session_token>?role=app|client

Prerequisites

• Ubuntu/Debian VPS with sudo access.
• Domain DNS relay.example.com pointing to the VPS.
• Node 20+ installed at /usr/bin/node.
• nginx and systemd installed.
• Optional: Redis available locally for persistence.

# one-time packages
sudo apt update
sudo apt install -y nginx redis-server certbot python3-certbot-nginx

Install Relay Server

1. Provision target directory

sudo mkdir -p 
sudo chown -R $USER:$USER 

2. Copy relay source

# from your repo host
cp -R ../relay-server/. /

3. Install dependencies

cd 
npm install --omit=dev

Environment Configuration

Use .env.example as baseline. Key production settings:

Example env file

sudo tee  >/dev/null <<'EOF'
NODE_ENV=production
PORT=
TRUST_PROXY=true
RELAY_BUILD=2026.02.25
REQUIRE_REDIS=true
REDIS_URL=
REDIS_PREFIX=vagus:relay:
REQUIRE_ORIGIN=false
EOF

systemd Service (Daemon)

Service template is provided at ../relay-server/deploy/systemd/vagus-relay.service.

Install service

sudo cp /deploy/systemd/vagus-relay.service /etc/systemd/system/vagus-relay.service

# recommended: use env file instead of inline Environment lines
sudo sed -i 's|^# EnvironmentFile=|EnvironmentFile=|' /etc/systemd/system/vagus-relay.service

sudo systemctl daemon-reload
sudo systemctl enable vagus-relay
sudo systemctl restart vagus-relay
sudo systemctl status vagus-relay --no-pager

Logs

journalctl -u vagus-relay -f

Nginx + SSL

Nginx template is provided at ../relay-server/deploy/nginx/relay.example.com.conf.

1. Install nginx site config

sudo cp /deploy/nginx/relay.example.com.conf /.conf
sudo ln -sf /.conf /.conf
sudo nginx -t
sudo systemctl reload nginx

2. Issue SSL certificate (Let's Encrypt)

sudo certbot --nginx -d relay.example.com
sudo nginx -t
sudo systemctl reload nginx

3. Firewall (if UFW is enabled)

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Relay listens on :. Do not expose publicly.

Verification

Health endpoint

curl -sS https://relay.example.com/health | jq

Expected fields include:

• status: "ok"
• mode: "multi-client"
• relay_build
• persistence: "redis" (if Redis configured)

Smoke test

cd 
node scripts/smoke-test.js

Operations

Restart relay

sudo systemctl restart vagus-relay

Deploy update

cd 
# sync updated source here
npm install --omit=dev
sudo systemctl restart vagus-relay
curl -sS https://relay.example.com/health

Zero-data guarantees

• Payloads are relayed in memory and not persisted by relay.
• Redis stores session metadata only (token/code/session state), not message bodies.

Troubleshooting

Security Checklist

1. Run behind TLS only. Enforce HTTP-to-HTTPS redirect.
2. Keep relay port private (loopback), expose only 443/80 via nginx.
3. Use Redis persistence for restart safety and controlled session cleanup.
4. Set TRUST_PROXY=true when behind nginx for correct client IP rate limiting.
5. Set RELAY_BUILD per release for traceable health diagnostics.
6. Review ORIGIN_ALLOWLIST/REQUIRE_ORIGIN only if browser-origin restrictions are needed.
7. Monitor logs and alert on relay start failures, 5xx spikes, and pair abuse events.