A WebSocket based VPN/proxy relay for virtual machines.
- Secure Communication: Supports secure WebSockets (WSS) for encrypted data transfer.
- Dynamic IP Allocation: Built-in DHCP-like server to automatically assign IP addresses to virtual machines.
- VM-to-VM Networking: Allows virtual machines on the same relay to communicate communicate with each other (configurable).
- Admin Interface: A web-based UI to monitor active sessions and manage proxy rules.
- HTTP Proxying: Reverse proxy functionality to expose services from VMs to the host network.
- Rate Limiting: Configurable bandwidth limits for each connected VM.
These default values can be overridden by setting corresponding environment variables.
| Setting | Purpose | Default |
|---|---|---|
RATE_LIMIT_KBPS |
Maximum upload/download bandwidth for each VM in kilobytes per second. | 1024 |
MAX_CONNECTIONS_PER_IP |
Maximum number of concurrent WebSocket connections from a single IP. | 4 |
ENABLE_WSS |
Use Secure WebSockets (WSS). Requires cert.pem and key.pem. |
true |
ENABLE_VM_TO_VM |
Allow VMs on the same relay to communicate with each other. | true |
LOG_LEVEL |
Controls logging verbosity. 0 (Disabled), 1 (Debug), 2 (Trace). |
1 (Debug) |
| Setting | Purpose | Default |
|---|---|---|
GATEWAY_IP |
IP address of the virtual gateway within the VM's network. | 10.0.2.2 |
DHCP_START |
The starting IP address for the DHCP pool (last octet). | 15 |
DHCP_END |
The ending IP address for the DHCP pool (last octet). | 254 |
DNS_SERVER_IP |
DNS server provided to VMs via DHCP. | 8.8.8.8 |
TCP_WINDOW_SIZE |
TCP window size for connections to/from the VM. | 10240 |
WS_PORT |
Port for the WebSocket server. | 8443 (WSS) / 8086 (WS) |
WS_BIND_ADDRESS |
IP address for the WebSocket server to bind to. | 0.0.0.0 |
ADMIN_PORT |
Port for the web-based admin interface. | 8001 |
ADMIN_BIND_ADDRESS |
IP address for the admin interface to bind to. | 127.0.0.1 |
PROXY_PORT |
Port for the HTTP reverse proxy server. | 8080 |
PROXY_BIND_ADDRESS |
IP address for the reverse proxy to bind to. | 127.0.0.1 |
| Setting | Purpose | Default |
|---|---|---|
ADMIN_SESSION_SECRET |
Secret used to sign admin session cookies. Set this in production. | change-me-in-production |
ADMIN_AUTH_DB_PATH |
Path to the SQLite database used for admin users. | ./admin_auth.sqlite |
ADMIN_BOOTSTRAP_USERNAME |
Initial admin username (required on first run if DB is empty). | none |
ADMIN_BOOTSTRAP_PASSWORD |
Initial admin password (required on first run if DB is empty). | none |
ADMIN_LOGIN_WINDOW_MS |
Sliding window for failed login attempts. | 600000 (10 minutes) |
ADMIN_LOGIN_MAX_ATTEMPTS |
Max failed attempts per IP+username within the login window. | 6 |
ADMIN_TRUST_PROXY |
Trust reverse proxy headers for IP/session security settings. | false |
ADMIN_COOKIE_SECURE |
Force secure admin session cookies (requires HTTPS at edge/proxy). | false |
This project requires Node.js. You can install the dependencies using npm:
npm installFor secure WebSockets (WSS), you need to generate a private key and a certificate. You can generate a self-signed pair using the following npm script:
npm run keygenThis will create key.pem and cert.pem in your project directory. When prompted,
you can leave the fields for distinguished name blank.
Alternatively, you can run the openssl command directly.
This is useful if you want to use different settings:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodesOnce the dependencies are installed and you have your key pair (if using WSS), you can start the relay server:
npm start
For first startup with an empty admin auth database, provide bootstrap credentials:
ADMIN_SESSION_SECRET="replace-with-strong-secret" \
ADMIN_BOOTSTRAP_USERNAME="admin" \
ADMIN_BOOTSTRAP_PASSWORD="replace-with-strong-password" \
npm startOnce the first user is created, you can remove bootstrap username/password env vars.
| In the browser you will use the relay first visit https://127.0.0.1:8443 and | trust the certificate you created.
The server will start, and you can see log output in your console.
The project includes a web-based admin UI. By default, it's available at http://localhost:8001.
The admin API now requires login. Open the admin UI and sign in using your configured admin credentials.
For public deployments behind HTTPS, set:
ADMIN_TRUST_PROXY=true
ADMIN_COOKIE_SECURE=true