Remote Access & Mobile Dashboard

By default Itervox binds the HTTP server to 127.0.0.1:8090 — only reachable from the same machine that runs the daemon. To view the dashboard from your phone or another computer, you have five options.

Always set ITERVOX_API_TOKEN before exposing the dashboard outside loopback. The dashboard has no built-in authentication on 127.0.0.1. As soon as the server binds to anything reachable from another device, you must enable bearer token auth. Put the value in .itervox/.env (loaded automatically) or export it:

ITERVOX_API_TOKEN=$(openssl rand -hex 32)

All API requests — including the web dashboard’s fetch calls and SSE streams — then require an Authorization: Bearer <token> header. The dashboard handles this for you:

When the daemon starts with ITERVOX_API_TOKEN set, it prints a dashboard URL with ?token=<token> appended (look for the dashboard URL (carries token — copy/paste once) log line).
Open that URL once from your phone or other device. The dashboard captures the token, stores it in sessionStorage, and strips it from the URL bar.
After that, every request and SSE connection sends the bearer header automatically. If the token is missing, rejected, or the session ends (closing the tab), you’ll see a login screen that accepts the token via a paste input. Tick Remember on this device to persist it in localStorage instead of sessionStorage.

For scripted access (curl, other backends), attach the header manually:

curl -H "Authorization: Bearer $ITERVOX_API_TOKEN" http://localhost:8090/api/v1/state

Option 1 — LAN bind (same WiFi)

The simplest path. Edit your WORKFLOW.md:

server:
  host: 0.0.0.0
  port: 8090

Restart itervox. The dashboard is now reachable from any device on the same network. Find your laptop’s LAN IP:

# macOS / Linux
ipconfig getifaddr en0      # Wi-Fi on macOS
hostname -I                  # Linux

On your phone, browse to http://<laptop-ip>:8090/?token=<your-token> — this matches the URL the daemon prints at startup. The dashboard will capture the token on first load and strip it from the URL.

Pros: zero setup, works on home/office WiFi, real-time SSE streaming. Cons: only works on the same network. Doesn’t survive when your phone leaves WiFi or your laptop sleeps.

Option 2 — SSH tunnel (developer-friendly)

If you’re already SSHing into a machine that runs Itervox, forward the port:

ssh -L 8090:localhost:8090 user@remote-host

Then browse to http://localhost:8090 in your local browser. On iOS/Android, apps like Termius and Blink Shell support port forwarding.

Pros: familiar to developers, no daemon config changes needed. Cons: mobile SSH clients are awkward; the tunnel dies when the SSH session disconnects.

Option 3 — Tailscale (recommended for remote work)

Tailscale is a zero-config WireGuard mesh VPN. Install it on both your laptop and your phone, log into the same account, and your phone can reach the laptop directly via its <laptop-name>.<tailnet>.ts.net hostname — from anywhere in the world.

# WORKFLOW.md
server:
  host: 0.0.0.0   # bind to all interfaces — Tailscale handles auth + encryption
  port: 8090

On your phone: http://laptop.tail-scale-name.ts.net:8090/?token=<your-token> on first visit. The dashboard captures the token and subsequent visits work without the query parameter.

Pros: works from anywhere, end-to-end encrypted, no port forwarding, no public exposure. NAT-traversal is automatic. Cons: requires installing Tailscale on every device; the free tier is generous but is a third-party dependency.

Option 4 — ngrok (managed public URL)

ngrok is the original tunnelling-as-a-service. One command and you get a public HTTPS URL that proxies to your local dashboard.

Setup

Install ngrok and authenticate (ngrok config add-authtoken <token>).
Start the Itervox daemon as usual (default 127.0.0.1:8090 is fine — ngrok talks to localhost).
In a separate terminal:
Terminal window
```
ngrok http 8090
```
ngrok prints a public URL like https://abcd-1234.ngrok-free.app.
On your phone, open https://abcd-1234.ngrok-free.app/?token=<your-token> on first visit — the dashboard will capture the token and strip it from the URL.

Lock down the public URL

The free tier exposes a random URL on every restart. Use ngrok’s built-in basic auth or OAuth to keep random visitors out:

ngrok http 8090 --basic-auth="you:strongpassword"

Or restrict by IP / Google email on a paid plan. Always set ITERVOX_API_TOKEN as well — defence in depth.

Pros: the fastest path to a public URL, automatic HTTPS, works through any NAT or firewall, ships with built-in auth options. Cons: depends on a paid SaaS for stable subdomains; free-tier URLs change on every restart; a third-party sees your traffic in transit (though it’s end-to-end TLS to your machine).

Option 5 — Piko (self-hosted reverse tunnel)

Piko is an open-source, MIT-licensed reverse tunnel that you can self-host. It works like ngrok or Cloudflare Tunnel, but the server is yours — no SaaS, no rate limits, no third-party in the data path.

This is the recommended option if you want a public URL for your dashboard without depending on any vendor.

Setup

Run a Piko server somewhere with a public IP (a $5 VPS works fine). Piko ships as a single Go binary and supports clustering for high availability if you need it.
Terminal window
```
piko server --proxy.bind-addr :8000 --upstream.bind-addr :8001
```
On your laptop, run the Piko agent pointing at your local Itervox dashboard:
Terminal window
```
piko agent http itervox-dashboard 8090 \
  --connect.url ws://your-piko-server:8001
```
This opens an outbound connection to the Piko server and registers the endpoint name itervox-dashboard.
Configure DNS so that itervox-dashboard.your-domain.com (or whichever subdomain you choose) points to the Piko server’s proxy port.
On your phone, browse to http://itervox-dashboard.your-domain.com/?token=<your-token> on first visit. The dashboard captures the token, and subsequent visits work without the query parameter. The Piko server routes the request through the outbound tunnel to your laptop’s Itervox dashboard.

Why Piko fits Itervox

MIT-licensed and self-hostable — same ethos as Itervox itself. No vendor in the loop, no SaaS dependency, no rate limits.
Outbound-only tunnels — your laptop never needs an inbound port open or port forwarding on your home router.
Survives network changes — agents reconnect automatically when your laptop changes networks (coffee shop → home → office).
Single binary — fits the Itervox philosophy of “one binary, one config file.”

Pros: completely self-hosted, no vendor lock-in, public URL that survives network changes, free apart from VPS hosting. Cons: requires a small VPS with a public IP and a domain name; one-time setup is more involved than Tailscale.

Comparison

Option	Same WiFi	Remote	Self-hosted	Setup	Best for
LAN bind	✅	❌	✅	1 min	Home / office, single user
SSH tunnel	✅	✅	✅	2 min	Developers SSHing into a server
Tailscale	✅	✅	⚠️ third-party	5 min	Personal use, multi-device
ngrok	✅	✅	❌ SaaS	2 min	Quickest public URL, demos
Piko	✅	✅	✅	30 min	Teams, vendor-independent setups

The API token

Itervox is secure by default when exposed beyond loopback: if you bind the server to any non-loopback address (0.0.0.0, a LAN IP, a Tailscale IP, etc.) and you haven’t set ITERVOX_API_TOKEN, Itervox will auto-generate a random 32-byte token on startup and install bearer-token authentication. The token is printed once in the startup log alongside a dashboard URL that embeds it:

INFO server: auto-generated ephemeral API token for non-loopback bind host=0.0.0.0
INFO dashboard URL (carries token — copy/paste once) url=http://0.0.0.0:8090/?token=<long-hex-token>

Auto-generated tokens are ephemeral — they change on every restart. For a stable token (so your phone’s bookmark keeps working across restarts), pin one yourself in .itervox/.env, which Itervox loads automatically on startup and which survives shell restarts and launcher scripts that wouldn’t inherit an exported variable:

ITERVOX_API_TOKEN=$(openssl rand -hex 32)

An export ITERVOX_API_TOKEN=… in your shell also works, but only if you launch itervox from that same shell session.

Opting out of bearer auth on LAN

If you really want an unauthenticated non-loopback bind — for example, a daemon running on an air-gapped LAN or behind a strict firewall where you accept the risk — set the explicit opt-out in WORKFLOW.md:

server:
  host: 0.0.0.0
  port: 8090
  allow_unauthenticated_lan: true

Itervox will then bind non-loopback with no auth middleware installed, and log a warning at startup. This flag does nothing when ITERVOX_API_TOKEN is set — an explicit token always wins.

When ITERVOX_API_TOKEN is set, the daemon startup log includes a dashboard URL that embeds the token (http://host:8090/?token=…) — copy/paste that URL into your browser once. The dashboard captures the token into sessionStorage, strips it from the URL bar via history.replaceState, and sends it as Authorization: Bearer on every subsequent request (including SSE streams). If the token is missing, wrong, or the session ends, the dashboard shows a login screen with a paste input.