Direct egress
Explicit direct route
Direct path is explicit and guarded by policy. It is not an automatic fallback.
Routed VPN control plane
Route devices through a self-hosted VPN hub.
Assign each device an Internet egress and each private subnet a tunnel. VPN Hub applies the routes on Ubuntu 24.04 and blocks traffic when its selected egress is down.
Fail closed on egress failureConfirmation with rollbackDrift checks against configuration
Example device route
example revision · 4d7c2aCLIENTlaptop-0110.80.0.2
encrypted tunnel
HUBrouting policyconfigured
selected egress
EGRESSwireguard-euexample tunnel
Namespaceper tunnel
Direct fallbackblocked
Rollbackon timeout
01 / routing configuration
How routing is built
Declare devices, tunnels, and DNS rules in YAML. The agent applies that revision and detects differences between configuration and runtime state.
- policy file defines devices, tunnels, egress role, and DNS scope
- agent renders namespaces, nftables chains, nft set, and service units from that policy
- each provider tunnel has its own network namespace and kill switch
02 / entry and egress
Supported egress and entry paths
WireGuard
Primary tunnel
One tunnel, one namespace, deterministic policy scope.
AmneziaWG
Client entry
Obfuscation settings are part of tunnel profile rotation.
Xray / VLESS
Alternative transport
Per-tunnel namespace and explicit profile handling.
OpenVPN
Provider compatibility
Kept for mixed provider environments.
03 / failure handling
Operational safety model
A failed egress stays blocked. Changes that require confirmation roll back if the confirmation window expires.
- Root-only operations for install, uninstall, and state mutation.
- No silent fallback to direct outbound traffic when policy becomes invalid.
- Provider input is validated and normalized before state reconciliation.
- The optional Telegram bot supports profile issuance, revocation, and deployment confirmation.
- Recovery guides cover SSH access, dry runs, and confirmation windows.
04 / routing scenarios
Routing and operations
Split tunnel by destination
Routing
Keep corp, private, and public traffic separate with per-tunnel DNS and namespace policy.
hubctl tunnel routes corp-private --add 203.0.113.0/24
Devices through a selected provider
Connectivity
Assign an egress to each employee device and change that assignment when needed.
hubctl device set-egress laptop corp-egress
Private service access
Security
Expose private subnets only through approved tunnels with DNS pinning.
hubctl tunnel routes corp-private --add 192.0.2.0/24
SOCKS5 app steering
Operations
Send selected application traffic through an assigned tunnel without changing whole host routing.
hubctl routes
Provider migration with rollback
Availability
Test canary candidates, then restore the last-known-good upstream if health fails.
hubctl subscription refresh corp-egress
Device isolation
Security
Reject unplanned client-to-client traffic by default and add explicit ACLs.
hubctl client-acl add phone laptop tcp/22
Incident pause and rollback
Reliability
Stop risky changes and restore previous revision through timer-based confirmation.
hubctl deploy --confirm-within 5m
Private DNS and DNS zone split
Networking
Private names follow tunnel DNS policy, public names keep normal resolver behavior.
hubctl tunnel zones corp-net --add corp.example
Emergency maintenance mode
Ops
Review dependent devices and change their egress before disabling a tunnel.
hubctl tunnel disable corp-egress
Fleet onboarding and profile rotation
Lifecycle
Issue deterministic client profiles with revision-aware identifiers.
hubctl device add laptop --egress corp-egress --address 198.51.100.10/32
Drift correction
Configuration
Validate declared state, then re-apply controlled policy when runtime state diverges.
hubctl validate && hubctl deploy
Read-only health for operators
Monitoring
Track health, drift, and unit status before applying production changes.
hubctl status --format yaml
05 / Telegram operations
Telegram bot operations examples
The bot surfaces operational previews and confirmations, including guarded deploy flow and quick troubleshooting links.
Telegram bot example
🚀 Deploy
🚀 Deploy
Active revision: docs-current-0001
New revision: docs-next-0002 (2 tunnels, 2 devices)
Excluded revoked devices: docs-retired
Changes:
• ➕ tunnel docs-private
• 🔀 docs-laptop: direct → docs-egress
• ➕ device docs-phone → direct
With rollback protection, the agent restores the previous revision if you do not confirm in time, even if the new revision cuts off access.
📱 Devices
📱 Devices
🟢 docs-laptop → docs-egress — online
🚫 docs-phone → direct — never connected, revoked
🚇 Tunnels
🚇 Tunnels
🟢 docs-private — private-network, wireguard, on
⏸ docs-egress — egress, xray, off
📡 Subscriptions
📡 Subscriptions
🟢 docs-egress — 203.0.113.44:443
Automatic refresh: every 6h; a candidate must first prove it works in an isolated namespace.
📊 Status
📊 Status
Revision: docs-current-0001 (created 2h ago)
2 tunnels, 2 devices
⏳ Awaiting confirmation: revision docs-next-0002, 3m 20s left
Agent: 🟢 active (running), restarts: 0
Drift: ✅ host matches the revision
🔔 Notification settings
🔔 Notification settings Intervals: health — 5m, drift — 30m, subscriptions — 6h (configured in telegram.yaml). Categories: Tap a category to toggle it; the selection is stored on the hub and survives bot restarts.
Example bot actions: Review changes, Confirm deployment, Inspect devices, Inspect tunnels, Open status, Open settings
06 / operation guides
Cookbook preview
Step-by-step guides for deployments, recovery, segmentation, and provider checks.
Deploy with rollback window
Safe apply path with operator confirmation timeout.
Recovery and rollback
What to do when DNS, tunnel, or host state diverges.
Private subnet segmentation
Build isolated app and private subnet policies from one hub file.
Subscription canary testing
Promotion flow for candidate upstream endpoints.
Set up your first hub.
Validate the example configuration on a disposable Ubuntu host, then connect one device and verify its route.