Two parts, one private route.
Safeveil is a self-hosting-oriented VPN concept and deployment scaffold. It combines a public presentation and operator interface in dist/ with a single-node WireGuard gateway and provisioning API in gateway/. The website helps visitors understand the model and helps an operator select, connect, and administer gateways. WireGuard—not the website—carries encrypted device traffic.
Static pages explain the concept, select a location, and administer a deployed gateway.
A minimal authenticated API manages WireGuard peer records and produces standard client configurations.
You supply the Linux VPS, public IPv4 address, DNS, monitoring, backups, and operational controls.
The repository deploys one WireGuard gateway per server. The homepage’s peer-mesh animation, hop selector, and connection preview communicate a broader decentralized-network concept; they are clearly labeled simulations and are not live network telemetry.
What the website does.
The Safeveil website serves two audiences at once: visitors evaluating the privacy model and operators managing infrastructure they control. Its pages move from explanation to selection to administration without pretending that the browser itself is a VPN client.
Concept overview
The homepage explains self-hosted private access, visualizes an encrypted-network concept, and distinguishes the presentation layer from the tunnel.
Route lab
Visitors can compare balanced, maximum-privacy, and low-latency profiles. The exit city and hop count update in the interface to demonstrate routing tradeoffs; no live route is created.
Location directory
The searchable location page reads locations.json, groups gateways by region, identifies deployed gateways versus scaffold slots, and carries the selection into the console.
Gateway console
An administrator can connect to a compatible HTTPS control endpoint, validate its location, inspect interface and peer status, create peers, download configurations, and revoke access.
Technical documentation
This page records deployment requirements, configuration, API behavior, operating commands, security boundaries, and the difference between current utilities and concept visuals.
Self-hosted gateway
After deployment to a supported VPS, the gateway configures WireGuard, NAT, NGINX, TLS, a loopback control service, and persistent peer metadata under the operator’s control.
Utility and truth model
| Surface | Primary utility | Source of information | Status |
|---|---|---|---|
| Homepage | Explain the product model and let visitors explore example routes | Static content and browser animation | Illustrative |
| Locations | Search, select, and forward a region into the control flow | Versioned locations.json | Inventory-driven |
| Control plane | Provision and revoke WireGuard peers; inspect gateway state | Your deployed gateway API | Functional after deployment |
| Docs | Explain product scope, deployment, API, and operations | Repository implementation | Reference |
Control path and data path.
Safeveil intentionally separates browser-based administration from VPN traffic. The website can manage a gateway, but encrypted application traffic travels directly between an official WireGuard client and the operator’s server.
The control API defaults to 127.0.0.1:8787 and should only be exposed through the HTTPS reverse proxy.
This is the data path. The Safeveil web page is not in it and does not proxy browsing traffic.
Creates and removes peers, reports handshakes and byte counts, and returns a new client configuration once.
WireGuard encrypts device traffic, authenticates peers with keys, and carries packets through the deployed interface.
What the interface stores.
The static website does not include a user-account system or a hosted customer database. It uses browser storage to preserve limited operator convenience data.
A bearer token grants administrative control over the gateway. Treat it like a password: use HTTPS, keep it out of URLs and source control, rotate it when access changes, and never include it in screenshots or support messages.
Deploy to a clean VPS.
Use Debian 12 or Ubuntu 22.04/24.04 with a public IPv4 address. Before installation, create a DNS A record pointing to the server and allow 80/tcp, 443/tcp, and 51820/udp.
Required environment
export UNTRACE_DOMAIN="vpn.example.com"
export UNTRACE_ADMIN_EMAIL="admin@example.com"
export UNTRACE_ADMIN_TOKEN="$(openssl rand -base64 48)"
sudo --preserve-env=UNTRACE_DOMAIN,UNTRACE_ADMIN_EMAIL,UNTRACE_ADMIN_TOKEN \
bash gateway/bootstrap.shThe installer configures WireGuard, the loopback control service, NGINX, TLS through Certbot, firewall-compatible ports, and the static website. Keep the generated administrator token in a password manager; never commit it or share it in screenshots or support messages.
Provision a WireGuard peer.
- Open https://vpn.example.com/console.html.
- Enter the gateway origin and the administrator token used during deployment.
- Create a uniquely named peer and download the generated .conf file.
- Import the configuration into an official WireGuard client for Windows, macOS, iOS, Android, or Linux.
The peer private key is returned once inside the downloaded configuration and is not stored in the peer database. If that file is lost, revoke the peer and create a replacement.
Add country gateways.
Deploy one VPS per country or region. Give each deployment a unique location ID, display name, domain, and WireGuard endpoint. Then edit dist/locations.json, set that location’s available value to true, and point controlUrl to its HTTPS origin.
export UNTRACE_LOCATION_ID="de"
export UNTRACE_LOCATION_NAME="Germany · Frankfurt"
export UNTRACE_WG_ENDPOINT="vpn-de.example.com:51820"
export UNTRACE_SITE_ORIGIN="https://safeveil.example.com"Minimal control-plane API.
All responses use JSON. Administrative endpoints require Authorization: Bearer <token>. The public health endpoint does not require authorization.
| Method | Endpoint | Purpose | Auth |
|---|---|---|---|
| GET | /api/health | Service and configured-location health | Public |
| GET | /api/status | Interface, endpoint, location, and live peer state | Bearer |
| GET | /api/peers | List stored peer records | Bearer |
| POST | /api/peers | Create a peer and return its one-time client configuration | Bearer |
| DELETE | /api/peers/:id | Revoke and remove a peer | Bearer |
Create a peer
curl -X POST "https://vpn.example.com/api/peers" \
-H "Authorization: Bearer $UNTRACE_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Laptop","locationId":"de"}'Gateway environment.
| Variable | Default | Meaning |
|---|---|---|
| UNTRACE_BIND | 127.0.0.1 | Control API bind address |
| UNTRACE_PORT | 8787 | Loopback control API port |
| UNTRACE_ADMIN_TOKEN | Required | Administrator bearer token, minimum 32 characters |
| UNTRACE_WG_INTERFACE | wg0 | Managed WireGuard interface |
| UNTRACE_WG_ENDPOINT | Required | Public WireGuard host and port |
| UNTRACE_WG_SUBNET_PREFIX | 10.70.0 | Private IPv4 prefix for peers |
| UNTRACE_DNS | 1.1.1.1, 1.0.0.1 | DNS servers written to clients |
| UNTRACE_ALLOWED_ORIGIN | Empty | Exact website origin allowed by CORS |
| UNTRACE_PEER_DB | /var/lib/untrace/peers.json | Persistent peer metadata path |
| UNTRACE_DRY_RUN | 0 | Use synthetic keys and avoid interface changes when set to 1 |
Observe and maintain.
sudo systemctl status wg-quick@wg0
sudo systemctl status untrace-control
sudo wg show wg0
sudo journalctl -u untrace-control --since todayRevoking a peer removes its public key from the live WireGuard interface and persistent peer database. On reboot, the control service restores only peers still recorded in that database.
Dry-run testing
UNTRACE_ADMIN_TOKEN="development-token-with-at-least-32-chars" \
UNTRACE_WG_ENDPOINT="localhost:51820" \
UNTRACE_PEER_DB="./work/peers.json" \
UNTRACE_DRY_RUN=1 \
node gateway/bin/untrace-api.mjs
node --test gateway/tests/api.test.mjsProduction requires more.
This repository is a deployment scaffold, not a security audit. Before serving untrusted users, add an identity provider, per-user authorization, secret rotation, durable audit logs, monitoring, encrypted backups, abuse controls, and an independent security review.
IPv4 traffic is forwarded through the gateway. The client configuration routes ::/0 into the tunnel as a fail-closed IPv6 route; this scaffold does not provide routed IPv6 internet access.