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

Turning it on in the app

You can start and stop remote access from the DorkOS window, without restarting the server:

1. Open the Control Center — the ⚡ icon in the top bar
2. Flip Remote access on. The first time, this opens a short setup where you paste your ngrok token
3. Once it connects, a globe appears in the top bar

The globe is only there while remote access is running. Click it and you get:

• Your address, with a Copy link button
• A QR code to scan with your phone
• A switch to turn remote access off
• Manage…, which opens the full Remote Access window

The full window is where the settings live:

• 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

You can do all of it from the keyboard too: press ⌘K and type "remote" to copy the link, show the QR code, or turn remote access on or off.

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.
• The tunnel dropped: you get a notification either way, and it tells you which happened. ngrok sometimes loses its session and re-establishes it on its own — DorkOS says "reconnecting", keeps your address, and the globe dims until it is back. If the tunnel closed for good, DorkOS says so and stays off until you turn it back on.

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

Opening a tunnel takes a few seconds, so the address arrives after the opening banner rather than inside it — below the startup logs, with a QR code you can scan to open DorkOS on your phone:

  DorkOS v0.8.0
  Local:   http://localhost:4242
  Network: http://192.168.1.100:4242

... startup logs ...

  Tunnel:  https://your-domain.ngrok-free.app

  Scan to open on mobile:
  [QR Code]

Turning Remote Access on later from the app prints the same thing, wherever the terminal has got to.

Development Mode

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

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

Next Steps