Connect and pair

Who can connect

The daemon decides per request, based on where the client connects from.

Client address	No password set	Password set
Loopback (127.0.0.1, ::1)	Allowed	Password required
Private network (10/8, 172.16/12, 192.168/16, link-local, fc00::/7)	Allowed while LAN trust is on (default)	Password required
Anything else (public IPs, CGNAT 100.64/10 such as Tailscale)	A paired device credential is required	Password required

So on a home or office LAN, a fresh daemon is usable immediately. From anywhere else, a device must pair first.

Caution

LAN trust means anyone on your private network can control agents on the daemon. Turn it off on shared networks: frogg auth trust-lan off, or set a password.

Add a host in the app

Open Hosts in the sidebar.

Method	Where	Use when
Direct connection	All clients	The daemon is reachable by IP or name: LAN, VPN, Tailscale
Remote SSH	Desktop app	You can SSH to the host. The app tunnels to the daemon over SSH and can install it for you
Paste pairing link	All clients	You have a link from frogg auth pair
Scan QR code	Android app	The QR code printed by frogg auth pair

Direct connection

Enter the host and port (9999 by default). The dialog also scans your local network for daemons. Use SSL only if a TLS-terminating proxy sits in front of the daemon; the daemon itself speaks plain HTTP and WebSocket. Enter the daemon password if you set one.

Remote SSH (desktop)

The desktop app runs your system ssh with your SSH config (keys, users, ports, jump hosts) and forwards a connection to the daemon’s port on the remote host. Nothing is exposed on the network. If no daemon is installed there, the app offers to deploy one with the same install script; see desktop app.

Pair a device

Pairing gives a device a long-lived credential. It is how you connect from outside the private network, and it is required when LAN trust is off.

1. On the daemon host, print a pairing link:

   frogg auth pair

   Pairing link (phone, QR, or paste into the app):
   https://pair.frogg.app/code/eyJ2IjozLCJwcm9kdWN0IjoiZmRlIi...
   
   Treat this pairing link like a password. Anyone with it can access this daemon.
   Access: LAN trusted — devices on your private network connect without pairing; anyone else must pair.
   Direct LAN pairing: this daemon has not been claimed yet; the first device to pair becomes its owner. Single-use, expires ...

   A QR code follows unless FROGG_PAIRING_QR=0.

2. Open the link on the device, scan the QR code in the Android app, or use Paste pairing link in any client.

3. The client connects to an address in the offer and redeems its one-time token. The daemon stores the device’s credential as a hash in ~/.frogg/principals.json.

Details that matter:

• Claim tokens are single-use and expire after 10 minutes. Run frogg auth pair again for another device.
• The first device to pair claims an unclaimed daemon. Until then, a browser opening the daemon from a public address sees a pairing page instead of the app.
• The link contains everything needed to connect. pair.frogg.app is a stateless page that hands the offer to the app; it never contacts your daemon. Change its base with app.pairingBaseUrl or FROGG_PAIRING_BASE_URL.
• A direct pairing offer lists the daemon’s LAN addresses. The device must be able to reach one of them (same network or a VPN). Override the advertised address with FROGG_PRIMARY_LAN_IP.

In the app, host settings Pair a device first asks whether to enable relay. frogg does not run a public relay; choose Not now unless you operate one. If the host has no relay endpoint, the dialog says so and offers only Not now. Set the endpoint, and whether to use TLS, in the Relay endpoint card on the same Pair devices page, then pair again.

Check and reset

frogg auth claim-status

Claimed:        yes
Password:       not configured
LAN trusted:    yes (frogg daemon trust-lan off to require pairing on the LAN)
Pairing needed: yes, for clients beyond the private network
Principals:     /home/you/.frogg/principals.json

There is no per-device revoke. To remove access, forget all devices and pair the ones you keep again:

frogg auth reset-claim

Use a password instead

A password applies to every client, including loopback and the LAN:

frogg auth set-password     # prompts, stores a bcrypt hash in config.json
frogg restart

Clients enter it in Direct connection; the CLI reads FROGG_PASSWORD. Docker and other automated installs can pass FROGG_PASSWORD as an environment variable instead.

Troubleshooting connections

Symptom	Fix
This app requires daemon 0.6.0 or later	Update the daemon (frogg update or re-run install.sh), then restart its service
Invalid Host header (HTTP 403)	You reached the daemon by a hostname it does not allow. Add it: frogg start --hostnames build-box.lan or daemon.hostnames in config
requires a password from the CLI	Set FROGG_PASSWORD
Browser shows a pairing page	You are connecting from a non-private address. Pair, or connect over the LAN/VPN
TLS error on Direct connection	Untick Use SSL unless a TLS proxy fronts the daemon

More in troubleshooting.