Skip to content

Your phone (web app and push)

The hub (v0.2.9, #231) works on a phone: an installable web app with a layout made for it, and Web Push notifications when an agent needs you. It is free and runs entirely on your machine. Your phone talks to your hub directly, so it has to reach it: on your LAN, over Tailscale, or through your own tunnel. The paid Itervox relay removes the tunnel: with it, your phone reaches your hub from anywhere with no network setup. Nothing on this page needs it.

  • Needs you (/hub/m, the app’s start page): every project’s agents waiting for an answer — questions and guardrail approvals — and recent failed runs, oldest first.
  • Projects: every project on the hub with its health and counts.
  • An issue (/hub/p/{project}/m/{issue}): what the run is doing now, the question with a reply box, or Approve and Reject for a guardrail approval, the steering chips and a message box for a running agent, and Pause dispatch / Resume dispatch for the project. These are the dashboard’s own controls over the project’s API through the hub, with your phone’s token’s scope.
  • This phone: turn notifications on, and see or remove every device the hub pushes to.

The full dashboard is one tap away on every page.

The hub on a phone: the Needs you list with one card per waiting issue across projects The hub on a phone: the Needs you list with one card per waiting issue across projects
The hub on your phone: what needs you, across every project.
A project dashboard on a phone: the status bar, New task, and Needs attention with a reply, a review and a paused row, above the live counters A project dashboard on a phone: the status bar, New task, and Needs attention with a reply, a review and a paused row, above the live counters
One project's dashboard at phone width.

The hub listens on 127.0.0.1:8089 by default. Pick one of these. Push notifications and installing the app need https (browsers allow service workers only on https or localhost), so the Tailscale and tunnel routes are the ones that give you everything.

With Tailscale on the Mac and the phone, publish the hub on your tailnet with a real certificate:

Terminal window
tailscale serve --bg 8089

The hub is now at https://<machine>.<tailnet>.ts.net/hub/ on every device in your tailnet and nowhere else. The hub keeps listening on loopback; nothing else changes. (Binding the hub to the machine’s Tailscale address, "hub": {"bind": "100.x.y.z"}, also works, but over plain http: no push and no install.)

Any tunnel or reverse proxy that serves https and forwards to 127.0.0.1:8089 works, for example Cloudflare Tunnel:

Terminal window
cloudflared tunnel --url http://127.0.0.1:8089

Every hub route except the health probe and the static files needs a hub token, and the pairing exchange needs a one-time code, so a public URL exposes nothing without them. Put access control in front of it too (Cloudflare Access, an IP allow-list) if you can; see Remote access for the trade-offs.

"hub": {"bind": "0.0.0.0"} in ~/.itervox/settings.jsonc listens on every interface (restart the daemons); the phone opens http://<your-mac's-LAN-address>:8089/hub/m. Use it only on a network you trust. Over plain http the phone layout, replies, approvals, steering and pause all work, but the browser will not install the app or take push notifications. For those, put an https reverse proxy with a certificate the phone trusts in front of the hub, or use Tailscale.

On the computer, open the hub dashboard (/hub/) with an admin hub token and choose Phones:

  1. Set Hub address on the phone to the address from step 1 (for example https://my-mac.tailnet.ts.net). It defaults to the address the page is open at, which is wrong if that is 127.0.0.1.
  2. Choose Show pairing QR code and scan it with the phone’s camera.
  3. On the phone, name the device and tap Pair.

The phone exchanges the one-time code for its own operator token, kept on the phone, and opens the app. A code works once and expires after 10 minutes; it travels in the link’s #fragment, so no server or proxy logs it. Wrong codes are throttled. Paired devices on the same page lists every paired phone; Revoke stops its token at once and removes its push notifications. itervox token list --hub shows device tokens as device: <name>, and itervox token revoke --hub <id> works too.

No QR scanner? Copy the link under the code into the phone, or create an operator hub token by hand (itervox token create --hub --name phone --scope operator --expires 30d) and paste it on the phone’s sign-in screen.

  • iPhone (iOS 16.4 or later): open the hub in Safari, tap Share → Add to Home Screen, then open Itervox from the Home Screen. Push works only from the installed app.
  • Android: Chrome offers Install app (or Add to Home screen) in its menu.

In the app, open This phone, keep or change the device name and tap Notify this device, then allow notifications. The hub sends Web Push through your browser’s push service (Apple, Google, Mozilla or Microsoft):

  • What a push carries: the kind, the project, the issue, a short redacted title (“ENG-12 needs input”) and a link into the app. Never agent output, a question’s text or a command. Tapping it opens the issue’s page.
  • Encrypted end to end (RFC 8291): the push service sees only ciphertext. The hub signs its requests with a key it generated on first use, ~/.itervox/hub/push_vapid.pem (0600, never leaves the machine).
  • What is sent, and when, is the hub’s notification settings: the push channel in the matrix, per project and kind, with snooze and digests. Questions and guardrail approvals arrive at once; the other kinds you turn on come as digests.
  • Devices are kept in ~/.itervox/hub/push_subscriptions.json (0600). A device whose subscription the push service drops, or whose token is revoked, is removed. Send test for the push channel in the hub’s notification settings checks the whole path.

The same dashboard bundle can be served from another origin (a static host, for example) and talk to your hub:

  • Build it with VITE_API_ORIGIN=https://my-mac.tailnet.ts.net pnpm build in web/, or set it at runtime in the served index.html: <meta name="itervox-api-origin" content="https://my-mac.tailnet.ts.net">. Every API call then goes to that origin; the page’s paths stay the same (/hub/, /hub/m, /hub/p/{project}/...), so route them all to index.html.

  • List the page’s origin in server.allowed_origins of the daemon that serves the hub (usually in ~/.itervox/settings.jsonc) and restart it:

    { "server": { "allowed_origins": ["https://dash.example.com"] } }

    Without it (the default) the hub and every daemon answer same-origin pages only: no CORS header is sent and every cross-origin preflight is refused. See Configuration.