Remote machines over SSH

flockr can reach a flockr server on another machine over SSH. You can save the machine once and run commands on it by name, or attach to it directly.

Saved SSH machines

flockr machine manages saved SSH machines.

Command	What it does
`flockr machine add [--label LABEL] [--remote-session NAME] <SSH_TARGET>`	Prepare the remote flockr server and save the machine. `--label` sets the name shown in the sidebar (default: the SSH host, or host/session). `--remote-session` picks a session on the remote server.
`flockr machine list [--json]`	List saved machines.
`flockr machine status [LABEL_OR_ID] [--json]`	Check saved machines without prompting for authentication.
`flockr machine reconnect <LABEL_OR_ID>`	Authenticate a saved machine in this terminal and check that it connects.
`flockr machine rename --label <LABEL> <PROFILE_ID>`	Rename a saved machine.
`flockr machine remove <PROFILE_ID>`	Remove a saved machine.
`flockr machine enable <PROFILE_ID>`	Enable a saved machine.
`flockr machine disable <PROFILE_ID>`	Disable a saved machine.

Run interactively, machine add finds the sessions running on the remote machine and may ask you to pick one. Without an interactive terminal it uses the remote default session unless you pass --remote-session. If a running remote server doesn't match, setup asks before stopping it, and the default answer is No.

machine list lists connection profiles, not the panes on each machine. Removing a machine disconnects the client but doesn't stop its remote sessions.

Run a command on a saved machine

Put --machine <label-or-id> before an API command to run it on that machine:

flockr --machine <label-or-id> agent list
flockr --machine <label-or-id> pane list
flockr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000

The selector is an enabled saved profile ID or a unique, case-sensitive label. An SSH host name doesn't work here.
Commands use that machine's remote session. No open flockr window is needed.
Don't combine --machine with --session or --remote.
IDs belong to one server. Two machines can both have w1:p1, so look up IDs on the machine you target.
The remote server must already be running and compatible. --machine never installs, starts, or restarts it.
Local configuration, session management, install commands, and interactive attach are not forwarded.

Attach to a remote server

flockr --remote <ssh-target> [--session <name>]

This opens the flockr interface for a server on another machine, through SSH.

--remote-keybindings <local|server>: use your local keybindings or the server's. The default is local.
--handoff: opt into live handoff. If the remote server has to be replaced to match, flockr tries a live handoff first and falls back to a restart if that fails.

By default flockr runs SSH through a generated config. It includes your ~/.ssh/config first, adds ServerAliveInterval and ServerAliveCountMax as fallbacks (your own values still win), and reuses the first authenticated connection. To run plain SSH against your config unchanged, set:

[remote]
manage_ssh_config = false

The image paste key, keys.remote_image_paste (default ctrl+v), is only active in flockr --remote. Set it to an empty string to turn it off.

SSH machines and the flock

	Saved SSH machine	Flock member
Connection	SSH from your machine to the other one	Each member connects to the hub over Noise, no SSH
Setup	`flockr machine add` on the machine you work from	`flockr flock init`, `invite`, and `join`
Direction	One machine reaches another	Every member sees every other member's agents
Agent messages	No (`flockr message` reaches agents in the flock)	Yes, see Agent messages
Commands	`flockr --machine <label> ...`	`flockr --machine <member> ...`

If a saved SSH machine and a flock member have the same name, flockr shows the flock entry, since both reach the same computer. See Set up a flock.