scroll
Open Source · Self-Hosted · Enterprise Grade

The Tornado VPN Platform

A self-hosted secure access platform combining WireGuard performance, Tor-aware routing, and real-time operations visibility. Full control. No network trust outsourced.

Star on GitHub Explore Docs ↓
WireGuard Tor-aware RS256 JWT Redis pub/sub PostgreSQL FastAPI IPAM X25519 ECDH
01 / Architecture

Supervised Control Plane with Separated Data Paths

A master supervisor starts and monitors service processes defined in runtime config. External access enters through two FastAPI surfaces. Internal contracts are standardized over UDS sockets under /run/tornado.

Supervisor

Config-driven service sync, health ping, and restart automation via MASTER_service.py

Data Plane

WireGuard wg0 + wg1, Tor manager, routing and maintenance-path handling

Control Services

Auth, session, user, IPAM, key rotator, OS/API service managers, log microservice

Persistence

Redis for sessions & events, PostgreSQL for users, SQLite for log analytics

02 / Network Design

Dual-Lane WireGuard with Tor-Aware Routing

Standard VPN traffic runs on wg0 for maximum throughput. Policy-selected traffic is routed through wg1 which exits via Tor, giving you two distinct trust tiers on the same platform.

  • wg0 — high-performance standard lane, peer-programmed via IPAM service
  • wg1 — Tor-exit policy lane with circuit management and relay state controls
  • Maintenance path handling for operator access during tunnel incidents
  • UDS microservice mesh with reduced lateral exposure surface
wg0
Standard Lane
wg1
Tor Lane
UDS
IPC Transport
03 / Security Model

Multi-Layer Authentication & Key Integrity Controls

Login payloads are protected via X25519 ECDH + HKDF + AES-GCM before credential validation. Token issuance uses asymmetric JWT keypairs with overlap-aware verification during rotations, backed by Redis JTI revocation checks.

  • Client-side encryption before credentials leave the device
  • RS256 access and refresh tokens with claim and type validation
  • Reuse detection for revoked refresh tokens via JTI tracking
  • Bootstrap key validator — public-first then private cutover rotation
  • Signal-driven in-process service key reload, zero downtime
  • Argon2 password verification with configurable cost parameters
04 / Live Telemetry

Heartbeat-Driven Session Orchestration

Sessions are created with Redis keys (vpn:session:*) and heartbeat sentinels (vpn:session:*:hb). Expired heartbeat keys move sessions to offline, resumed heartbeats recover them, and hard_ttl finalizes cleanup.

# Quick health check sequence sudo systemctl status tornado --no-pager curl -sSf http://127.0.0.1:8000/health curl -sSf http://127.0.0.1:4605/health sudo wg show # Tail live session events redis-cli subscribe vpn:live_events # Required: expiry-driven heartbeat transitions redis-cli config get notify-keyspace-events
05 / Operations Runbook

Deterministic Recovery Paths for Every Incident Class

Operations are structured around dependency-first checks, targeted service remediation, and post-incident validation — backed by direct admin API control.

  • Recovery order: PostgreSQL + Redis → tornado.service → NGINX
  • Session instability: heartbeat TTL, keyspace events, cleanup telemetry
  • Rotation incidents: validate overlap key presence and reload signal targets
  • Tunnel incidents: verify wg0/wg1, IP pools, and peer-programming logs
  • Tor relay: /status, /up, /down, /circuits controls via admin API
06 / API Surface

Client & Admin Interfaces for Full Lifecycle Control

The client API handles encrypted login, token refresh, tunnel initiation, and heartbeat. The admin API exposes service management, user lifecycle, log analytics, Tor relay controls, and key-rotator actions.

Client API :4605
GET/auth/pubkey
POST/auth/login
POST/auth/reauth
POST/vpn/initiate
POST/session/heartbeat
Admin API :8000
*/services/* & /apps/*
*/users lifecycle
*/logs/* query/export
*/circuits relay ops
*/key-rotator/*
07 / Tornado VPN Client

Desktop Client for Linux and Windows

The client apps in client/linux and client/windows provide encrypted login, token refresh, session heartbeat, WireGuard tunnel lifecycle, and Tor-over-VPN mode. Packaging flows are documented in docs/build_linux.md and docs/build_windows.md.

  • API flow: /auth/login → /vpn/initiate → /session/heartbeat
  • Session continuity with automatic reauth and heartbeat scheduling
  • Linux packaging: Debian package output (tornadovpn-client_*.deb)
  • Windows packaging: PyInstaller + Inno Setup installer output
Tornado VPN client login screen

Client login and server endpoint entry.

Tornado VPN client dashboard

Main dashboard with connection controls.

Tornado VPN client Tor mode

Tor-over-VPN toggle and route visualization.

Tornado VPN client session metrics

Live session statistics and connection status.

08 / Download

Get the Latest Tornado VPN Client

Download the official desktop clients for Linux and Windows. Both packages include encrypted authentication, automatic session management, and full Tor-over-VPN support.

Loading latest release...

Installation: Linux: sudo dpkg -i tornadovpn-client_*.deb • Windows: Run the installer and follow the setup wizard

Free & Open Source · MIT License

Ready to deploy your own secure access platform?

Tornado VPN is open source and self-hostable. Get full control over your network trust, no subscriptions, no vendor lock-in. Star us on GitHub and join the community.

View on GitHub
Documentation Report a Bug