AI Agent Web UIs
Maintainer note: the rules and commands on this page are mirrored in the agent skill reference at
plugins/portal-tunnel/skills/portal-expose/references/agent-backends.md. When either changes, update both files. This page is the human-facing source; the reference is the agent-facing copy.
Agent web UIs let you drive Claude Code, Codex, and other coding agents from a browser or phone. Whoever reaches one can type into your terminals, so it needs more care than a normal preview.
Rules
- Keep the app’s own login on. Set the app’s token or pairing before you expose it. Portal’s application authentication can add a sign-in in front, but it does not replace the app’s own gate.
- Keep the app on loopback. It listens on
127.0.0.1; Portal connects to it there. - Use routed HTTP.
--http-route /=<port>sendsX-Forwarded-ForandX-Forwarded-Proto: httpsand carries WebSocket upgrades, which these apps need. - Hide and pin the address. Use
--hide, a hard-to-guess--name, one identity file outside your repository, and one relay you trust with--relays <relay> --discovery=false. - Use the address-bound URL that
service ready atprints. The short<name>.<relay>URL can be claimed by another identity while your tunnel is stopped. - Keep secrets out of the command line. Tokens and client secrets go in the app’s environment.
Ovis (herdr web client)
Ovis, formerly “herdr web UI”, is a browser and phone client for herdr. It listens on 127.0.0.1:7317 by default.
Set
OVIS_TOKENto a long random value (for exampleopenssl rand -hex 32) where Ovis reads its settings, and restart it.Use Portal v2.6.1 or later, on a relay that runs v2.6.1 or later.
Start Portal:
portal expose --http-route /=7317 --strip-request-header Tailscale-User-Login --name herdr-$(openssl rand -hex 8) --identity-path ~/.config/portal/herdr.json --relays <relay> --discovery=false --hideFrom another device,
https://<address-bound host>/api/sessionmust answer401without a token.Open the address and sign in with the token, or pair the device from Settings → Phone & devices.
The plain portal expose 7317 sends no X-Forwarded-Proto, so Ovis refuses its own requests (invalid_origin). Do not set OVIS_TAILSCALE_SERVE_ONLY=1 while Portal runs. Ovis can also start Portal for you from Settings → Phone & devices → Portal, with an optional Portal sign-in in front (Portal v2.7.0 or later). See the Ovis guide’s Behind a reverse proxy section for details.
Other agent UIs
For any other agent dashboard, browser terminal, or agent API, check its documentation for its own authentication, the forwarding headers it needs or trusts, and whether it uses WebSocket or Server-Sent Events. If it has no login of its own, everyone who passes Portal’s sign-in gets a shell on your machine.