Pair your phone

Coming in 1.2.0. This feature is not in the current release (1.1.0). It ships in flockr 1.2.0.

The phone app talks to a mobile gateway inside your flockr server. The gateway is off by default. You turn it on, run flockr mobile pair, and scan the QR code with the app.

Before you start

The phone must reach your computer's IP address on the gateway port (47390 by default). Use a private network address that the phone can reach, such as a NetBird or WireGuard address, or a LAN address.

Enable the gateway

In ~/.config/flockr/config.toml:

[mobile]
enabled = true
listen = ["100.92.14.3"]   # your private network address; never 0.0.0.0

Restart the flockr server. All [mobile] keys need a server restart.

Key	Default	Meaning
`enabled`	`false`	Start the gateway. Nothing listens when false.
`listen`	`[]`	Literal IP addresses, optionally with a port: `["100.92.14.3", "[fd00::1]:47390"]`. `0.0.0.0`, `::`, and host names are rejected.
`port`	`47390`	Port for `listen` entries that have none.
`advertise`	`[]`	Hosts shown in the pairing QR, in try order (IPs or DNS names). Empty means the listen addresses.
`name`	host name	Name shown in the app and in push alerts.
`max_devices`	`8`	How many phones can be paired.
`pairing_ttl_secs`	`600`	Pairing code lifetime in seconds (60 to 3600).

A public address works, but it exposes the pairing endpoint to the internet. Prefer a private network address.

Pair

On your computer, run:
```
flockr mobile pair
```
It prints a QR code and a flockr://pair?p=... link. The code is good for one use and expires after 10 minutes by default.
In the app, tap Pair and scan the QR code, or paste the link.
The command prints the phone that paired and exits.

Options:

--ttl <SECS>: code lifetime in seconds (60 to 3600).
--no-wait: print the code and exit without waiting.
--json: print the link and expiry as JSON (implies --no-wait).

You can pair the app with several servers. Each one gets its own row on the first screen.

What pairing pins

The QR code carries the server's public key. The app stores it and uses it for every later connection, so only that computer can complete the encrypted handshake. If the server's key changes, or the address now points at a different machine, the app says so, stops reconnecting, and asks you to pair again. See Privacy and security.

Anyone who sees the QR code before it is used can pair within its lifetime. flockr mobile pair prints the device that paired, so you can check it was yours.

When to pair again

The app says the server's key changed.
The phone was paired with the early v1 prototype protocol. Servers support only v2, and phones paired under v1 must pair again.
A QR code from an older flockr is rejected. Update flockr and run flockr mobile pair again.

Manage paired phones

Command	What it does
`flockr mobile devices [--json]`	List paired phones (same as `devices list`).
`flockr mobile devices revoke <device_id>`	Remove a paired phone. Its connections close within 2 seconds.
`flockr mobile devices revoke --all`	Remove every paired phone.
`flockr mobile status [--json]`	Show the gateway's addresses, key fingerprint, devices, pending pairing, and push setting.

A paired phone can do anything you can do at the command line on that server, including typing into any pane. Treat a lost phone like a lost SSH key and revoke it.

What you can do from the phone

See every agent and terminal, and whether each one is working, blocked, or done.
Open a pane and watch it live. It opens at its desktop size, scaled to the phone. Fit resizes the pane to the phone's screen, and the desktop gets its size back when you leave.
Type into a pane with the phone keyboard or dictation. A key row sends Esc, Tab, Shift-Tab, Ctrl-C, Ctrl-D, arrows, Backspace, Enter, and y, n, 1, 2, 3 for answering a blocked agent's prompt.
Attach images. The server saves each one like a desktop clipboard image paste and pastes its path into the pane.
Read the last 500 lines of a pane in History.
Get an alert when an agent is blocked or done. Tapping it opens that agent's pane. See Push alerts.
Approve or deny messages between agents that wait for you, and change each machine's approve_messages setting.
If the computer is in a flock, reach the other machines in it through the computer you paired with.

Reading a finished agent on the phone clears its done badge on every desktop client too.