Tunnel Setup
Configure ngrok tunnels for remote access to DorkOS
Tunnel Setup
DorkOS includes optional ngrok tunnel support for accessing your instance remotely from any device. The tunnel is non-blocking -- if it fails to start, the server continues working locally.
Prerequisites
- An ngrok account (free tier works)
- An ngrok auth token from your ngrok dashboard
Quick Start
Set your ngrok auth token
Export your token as an environment variable:
export NGROK_AUTHTOKEN=your-token-hereStart DorkOS with tunneling enabled
Use the --tunnel flag:
dorkos --tunnelOr use the environment variable:
export TUNNEL_ENABLED=true
dorkosAccess the tunnel URL
The tunnel URL appears in the terminal output after the server starts. Use this URL to access DorkOS from any device.
Configuration
Prop
Type
Security
Tunnels expose your DorkOS instance to the public internet. Always protect your tunnel with basic auth in production.
Set up basic auth by providing credentials in the TUNNEL_AUTH variable:
export TUNNEL_AUTH=myuser:mypassword
export NGROK_AUTHTOKEN=your-token-here
dorkos --tunnelWith basic auth enabled, anyone accessing the tunnel URL will be prompted for a username and password before they can reach DorkOS.
How It Works
Server starts normally
DorkOS starts the Express server on the configured port (default 4242).
Tunnel connects
After the server binds, the tunnel manager dynamically imports the @ngrok/ngrok SDK and creates a tunnel. This dynamic import means there is zero overhead when tunneling is disabled.
URL is available
The tunnel URL appears in the terminal output. If tunnel creation fails, the server continues working locally -- the failure is non-blocking.
Graceful shutdown
When you stop the server (via SIGINT or SIGTERM), the tunnel is closed automatically before the process exits.
Health Check
When a tunnel is active, the health endpoint includes tunnel status:
curl http://localhost:4242/api/health{
"status": "ok",
"tunnel": "https://your-domain.ngrok.io"
}The tunnel field only appears in the health response when a tunnel is actively connected. Use this to programmatically verify tunnel availability.
Development Mode
For development with tunnels, use the dedicated dev tunnel script which tunnels the Vite dev server on port 3000:
npm run dev:tunnel -w apps/serverThis starts the full dev environment (Express + Vite HMR) and creates an ngrok tunnel pointing at the Vite dev server port.
Troubleshooting
If the tunnel fails to start, check that your NGROK_AUTHTOKEN is valid and that you have not exceeded your ngrok account's tunnel limit. The server will continue running locally even if the tunnel fails.
Common issues:
- "Tunnel is already running" -- The tunnel manager is a singleton. Restart the server to create a new tunnel.
- Auth token not found -- Ensure
NGROK_AUTHTOKENis exported in your shell, not just set in a.envfile that the tunnel manager cannot read. - Custom domain errors -- Custom domains require a paid ngrok plan. Remove
TUNNEL_DOMAINto use an auto-assigned URL.