Tunnel Setup

Want to check on your agents from your phone, or show a friend what you're building? A tunnel gives your local DorkOS instance a temporary public address, no domain or router setup required.

DorkOS uses ngrok to do this: it's a service that opens a secure path from the internet to something running on your machine. Its free tier covers everything on this page.

Don't worry if it doesn't connect right away: DorkOS keeps running locally either way.

Setup is a one-time job that takes about two minutes. Before your first tunnel, you need two things:

Prerequisites

• An owner login for your DorkOS. A tunnel puts your instance on the public internet, so DorkOS will not start one until a login protects it. If you don't have one yet, starting a tunnel walks you through creating it. See Securing Your Instance.
• A free ngrok account and its auth token. ngrok is the service that carries the tunnel. Grab the token from your ngrok dashboard and paste it into DorkOS. The free tier is enough.

After this one-time setup, remote access really is one tap: scan the QR code and approve from your phone.

Quick Start

export NGROK_AUTHTOKEN=your-token-here

dorkos --tunnel

export TUNNEL_ENABLED=true
dorkos

UI Toggle

You can also start and stop the tunnel from the DorkOS interface, without restarting the server:

1. Click the Globe icon in the status bar
2. Toggle Enable remote access on
3. The tunnel URL and a QR code appear once it connects

The dialog also gives you:

• Custom domain: set a static ngrok domain so your URL stays the same across restarts
• Connection quality indicator: a green, yellow, or red dot showing how fast the tunnel is responding
• Copy URL: copy the tunnel URL to your clipboard
• Copy session link: copy a direct link to the current session

If you have DorkOS open in several browser tabs, they all update together. Turn the tunnel on or off in one tab, and every other open tab reflects it within about a second.

Custom Domains

By default, your tunnel gets a new random URL every time it starts. ngrok also offers free static domains that stay the same across restarts:

1. Go to dashboard.ngrok.com/domains and claim a free domain
2. Enter it in the Custom domain field in the Remote Access dialog, or set TUNNEL_DOMAIN

That way, any QR code or bookmark you saved keeps working after you restart DorkOS.

Security

Starting a tunnel with login off routes you into owner-account creation first ("Exposing DorkOS requires a login."). Once the owner account exists and Require login is on, the tunnel starts and remote visitors get the sign-in screen. See Securing Your Instance for the full flow, per-user API keys, and CLI recovery.

You can optionally add ngrok's own HTTP basic auth on top of the login, as a second gate at the edge:

export TUNNEL_AUTH=myuser:mypassword
export NGROK_AUTHTOKEN=your-token-here
dorkos --tunnel

With TUNNEL_AUTH set, anyone accessing the tunnel URL is prompted for those credentials by ngrok before reaching DorkOS's own sign-in screen.

Troubleshooting

Common issues:

• "Tunnel is already running": the server replies with a 409 status, its polite way of saying "one at a time." Stop the existing tunnel first.
• Auth token not found: make sure NGROK_AUTHTOKEN is exported in your shell, or paste it into the Remote Access dialog.
• Custom domain errors: verify your domain is claimed at dashboard.ngrok.com/domains.
• Connection quality red: latency to the tunnel is over 500ms, usually because the nearest ngrok edge server is far from you geographically.
• Disconnected toast: if the tunnel drops unexpectedly, you'll see a notification. DorkOS tries to reconnect automatically.

Reference: how the tunnel works under the hood

Everything below is background for the curious. You don't need it to set up or use a tunnel.

API Endpoints

Control the tunnel programmatically:

# Start the tunnel
curl -X POST http://localhost:4242/api/tunnel/start

# Stop the tunnel
curl -X POST http://localhost:4242/api/tunnel/stop

# On-demand status check
curl http://localhost:4242/api/tunnel/status

Health Check

When a tunnel is active, the health endpoint includes tunnel status:

curl http://localhost:4242/api/health

{
  "status": "ok",
  "tunnel": {
    "enabled": true,
    "connected": true,
    "url": "https://your-domain.ngrok-free.app"
  }
}

CLI QR Code

When a tunnel starts, the CLI prints a QR code:

  DorkOS v0.8.0
  Local:   http://localhost:4242
  Network: http://192.168.1.100:4242
  Tunnel:  https://your-domain.ngrok-free.app

  Scan to open on mobile:
  [QR Code]

Development Mode

Contributors working on DorkOS itself can run the tunnel against the dev server:

pnpm --filter=@dorkos/server run dev:tunnel

Next Steps