System Architecture
Phantom-WG is a WireGuard®-based VPN management platform. All components run within a Docker container architecture, and the core component Phantom Daemon communicates over Unix Domain Socket (UDS).
Production Topology consists of three containers orchestrated via Docker Compose. The primary objective of this architecture is to securely forward queries to the Daemon.
There are two distinct traffic paths that reach the Daemon.
Management Traffic (User Interaction) (:443): Internet →
phantom-nginx → phantom-auth → phantom-daemon
VPN Traffic (:51820/udp): WireGuard clients connect directly to
phantom-daemon.
The UDS socket (daemon.sock) is shared with phantom-auth via a Docker named
volume.
phantom-nginx, is the only externally exposed HTTPS entry point of the system.
Routing
|
Location
|
Target
|
Description
|
|---|---|---|
/auth/* |
phantom-auth:8443 | Auth endpoints (login, MFA, session) |
/api/* |
phantom-auth:8443 | API proxy — buffering disabled for backup operations |
/ |
SPA static (try_files) | React SPA fallback — unknown paths are served as index.html |
/assets/* |
Static cache | 1 year, Cache-Control: public, immutable |
Nginx Configuration
phantom-auth, serves two roles: it directly handles its own auth endpoints (/auth/*) and
proxies daemon API requests over UDS (/api/*).
Environment
|
Variable
|
Default
|
|---|---|
AUTH_HOST |
0.0.0.0 |
AUTH_PORT |
8443 |
AUTH_LOG_LEVEL |
info |
AUTH_PROXY_URL |
unix:///var/run/phantom/daemon.sock |
AUTH_PROXY_TIMEOUT |
30.0 |
AUTH_PROXY_MAX_BODY |
67108864 (64 MB) |
AUTH_DB_DIR |
/var/lib/phantom/auth |
AUTH_SECRETS_DIR |
/run/secrets |
AUTH_TOKEN_LIFETIME |
86400 (24h) |
AUTH_MFA_TOKEN_LIFETIME |
120 (2m) |
AUTH_TOTP_SETUP_LIFETIME |
300 (5m) |
AUTH_INACTIVITY_TIMEOUT |
1800 (30m) |
AUTH_RATE_LIMIT_WINDOW |
60 |
AUTH_RATE_LIMIT_MAX |
5 |
phantom-daemon, is the core of the system. It manages WireGuard interfaces, client management, firewall rules, and databases. Management access is provided exclusively over UDS.
Environment
|
Variable
|
Default
|
|---|---|
PHANTOM_DB_DIR |
/var/lib/phantom/db |
PHANTOM_STATE_DIR |
/var/lib/phantom/state/db |
WIREGUARD_LISTEN_PORT |
51820 |
WIREGUARD_MTU |
1420 |
WIREGUARD_KEEPALIVE |
25 |
WIREGUARD_ENDPOINT_V4 |
— |
WIREGUARD_ENDPOINT_V6 |
— |
Kernel Requirements
|
Parameter
|
Description
|
|---|---|
NET_ADMIN |
WireGuard interface and nftables rule management |
NET_RAW |
Raw socket access |
net.ipv4.ip_forward=1 |
IP packet forwarding |
/dev/net/tun |
TUN interface creation |
Docker Compose Layout
Request Lifecycle
How an API request flows through the system:
Bridge Architecture
The daemon performs system-level operations through native bridges. The Python layer manages the business logic, while the bridges communicate directly with the kernel.
|
Bridge
|
Language
|
Responsibility
|
|---|---|---|
| wireguard-go-bridge | Go | WireGuard userspace, TUN interface creation, peer management, UAPI protocol |
| firewall-bridge | Rust | nftables rule groups, routing policy, atomic rule application |
Databases
All databases are in SQLite format. They are divided into two categories:
Persistent Data
User data and configuration. Backup and migration are performed through these databases.
|
Database
|
Owner
|
Container Path
|
|---|---|---|
| wallet.db | daemon | /var/lib/phantom/db |
| exit.db | daemon | /var/lib/phantom/db |
| auth.db | auth-service | /var/lib/phantom/auth |
Runtime State
Runtime data managed by bridges. Automatically created when the daemon starts, no intervention required.
|
Database
|
Owner
|
Container Path
|
|---|---|---|
| device.db | wireguard-go-bridge | /var/lib/phantom/state/db/wireguard/{ifname}/ |
| firewall.db | firewall-bridge | /var/lib/phantom/state/db |