Set up a flock

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

What a flock is

A flock is several flockr servers that see each other's agents through one hub, without SSH. It is off by default.

Hub: one machine holds the member list and decides who is in the flock. It is the only machine that needs a listen address.
Members: every other machine connects only to the hub. Members never connect to each other.

Members connect to the hub over Noise, with keys the hub checks against its member list.

Pick a network

The flock binds only to IP addresses you list. 0.0.0.0 and :: are rejected, so it never listens on every interface. Use a private network address, such as a NetBird address, that every machine can reach.

Enable [flock] on each machine

Add a [flock] section to ~/.config/flockr/config.toml on every machine. On the hub:

[flock]
enabled = true
listen = ["100.92.14.3"]   # the hub's private network address
# port = 47392
# name = ""                # this machine's name in the flock; default: host name

On a member, enabled = true is enough. Members don't need listen.

Key	Default	Meaning
`enabled`	`false`	Join this machine's server to a flock.
`listen`	`[]`	Literal IP addresses, optionally with a port, for example `["100.92.14.3", "[fd00::1]:47392"]`. Only the hub needs it. `0.0.0.0` and `::` are rejected.
`port`	`47392`	Port for `listen` entries that have none.
`name`	host name	This machine's name in the flock. Other machines use it to address its agents.

All of these keys need a server restart. approve_messages, also in [flock], applies without a restart; see Agent messages.

Start the flock on the hub

flockr flock init [--name NAME]

This makes the current machine the hub. --name sets the flock's name (default flock). If [flock] is not enabled, or the hub has no listen address, the command prints a note telling you to set them and restart the server.

Invite a machine

On the hub, run:

flockr flock invite [--role ROLE] [--ttl SECS]

--role: admin (default), member, or viewer. A viewer can only read (list agents and panes, read output, and wait for events). Admins and members can do everything.
--ttl: invite lifetime in seconds, from 60 to 3600. The default is 600 (10 minutes).

The hub's server must be running with [flock] enabled and a listen address, or the invite fails. The command prints a QR code and the join command to run on the new machine, then waits.

Join from the new machine

flockr flock join '<url>'

Paste the URL from the invite. Both machines then show a short code:

The new machine prints Short code: ... and waits.
The hub prints the join request and the same short code, and asks you to approve.
Check that the codes match, then answer y on the hub.

A machine can be in one flock at a time. After joining, restart the new machine's server if you enabled [flock] after it started.

Check the flock

Command	What it does
`flockr flock status [--json]`	Show this machine's flock state: the flock, this machine's member ID (and whether it is the hub), and the node's state.
`flockr flock members [--json]`	List members.
`flockr flock agents [--json]`	List agents on every member, with the address to send messages to each one (the SEND TO column).
`flockr flock remove <member-id\|name>`	Remove a member. Run it on the hub.

Every other computer in the flock shows up as a machine in flockr, next to your saved SSH machines, under its flock name. You can open it and see its agents and panes. The client reaches it through the hub, not SSH. If a saved SSH machine has the same label as a flock member, the flock entry replaces it, since both reach the same computer.

You can run any API command on a member from the command line:

flockr --machine <member> agent list