Tunnel Setup

DorkOS includes optional ngrok tunnel support for accessing your instance 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

export NGROK_AUTHTOKEN=your-token-here

dorkos --tunnel

export TUNNEL_ENABLED=true
dorkos

UI Toggle

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 QR code appear when connected

The dialog also provides:

• Custom domain — Set a static ngrok domain so your URL stays consistent across restarts
• Connection quality indicator — Green/yellow/red dot showing latency to the tunnel
• Copy URL — Copy the tunnel URL to your clipboard
• Copy session link — Copy a direct link to the current session

Multi-Tab Sync

When DorkOS is open in multiple browser tabs, all tabs stay in sync with tunnel status. Changes in one tab are reflected in all others within about 1 second via BroadcastChannel.

Remote devices connected via the tunnel URL receive real-time status updates via SSE.

Custom Domains

ngrok offers free static domains that persist 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

Benefits:

• Same URL across restarts
• QR codes and bookmarks remain valid

Configuration

Security

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

With basic auth enabled, anyone accessing the tunnel URL is prompted for credentials before reaching DorkOS.

How It Works

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

For development with tunnels, the tunnel targets the Vite dev server port (4241 by default) so HMR and proxied API calls work correctly:

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

Embedded Mode

When running as an Obsidian plugin, the tunnel UI is automatically hidden since tunneling does not apply in that context.

Troubleshooting

Common issues:

• "Tunnel is already running" — The server returns 409. Stop the existing tunnel first.
• Auth token not found — Ensure NGROK_AUTHTOKEN is exported in your shell, or paste it in the Remote Access dialog.
• Custom domain errors — Verify your domain is claimed at dashboard.ngrok.com/domains.
• Connection quality red — High latency (>500ms) to the tunnel, usually caused by geographic distance to the ngrok edge server.
• Disconnected toast — If the tunnel drops unexpectedly, you will see a notification. The system attempts to reconnect automatically.

Next Steps