Skip to content
installcurl -fsSL https://get.farhelm.io/install.sh | sh

Add a remote host

A remote host is a Linux machine or another Mac your Mac reaches over ssh. Once it is added, sessions can run there just as they do on your Mac, and they keep running on the host while your Mac sleeps or Farhelm is closed.

Add host offers SSH for a machine you already have, and Tensorlake sandbox to create a cloud host from a saved recipe. For the latter, follow Tensorlake sandboxes, which covers account setup, billing and suspension. The rest of this page covers SSH.

  • Linux on an x86_64 or ARM (aarch64) machine, with systemd’s services for your user account, which most distributions have; or an Apple-silicon Mac without the Farhelm desktop app installed. Intel Macs are not supported. Farhelm needs no root or sudo on either: everything it installs goes in your home directory.
  • Passwordless ssh from your Mac: ssh <destination> true has to work in a terminal without asking for a password. Farhelm uses your own ssh setup, so keys, the agent, and the Host names in ~/.ssh/config all apply. A host that asks for a second factor or another approval on every ssh login works only on a best-effort basis, and only if you start Farhelm’s ssh connections to it by hand. Choose ? → SSH needs 2FA? for the two commands, or follow the link in Add host for the destination you are about to add. Run both on your Mac. Each asks for approval once and stays connected in the background. Run its command again when a connection drops. The dialog also explains when a connection cannot be shared from your helm, the part of Farhelm that shows you your sessions. Adding or updating a host also opens one ssh login of its own, so a key that asks for a touch on each login asks once more then.
  • Not BusyBox: hosts whose basic command-line tools come from BusyBox are not supported.
  • Your Mac downloads Farhelm for the host and copies it over ssh. The download starts at get.farhelm.io, which hands the release files themselves over from GitHub, so your Mac needs to reach both. The host does not: it never needs access to get.farhelm.io or GitHub.

Choose + (Add host) on the navigation rail, the column of icons down the left edge of the sidebar.

The Add host button on the navigation rail.
The add host dialog with dev@new-box typed as the ssh destination, and what that field and the add button do.

While Farhelm checks the destination over ssh, Add reads Checking…. The dialog also takes an optional alias: the name Farhelm shows for the host instead of its destination, everywhere except the host’s details. You can change it later in the host’s settings. An agent in one of your sessions can also ask to add a host. Its request waits as a card, and Open add dialog on it opens this same dialog with the agent’s destination and alias filled in (Approve what agents do).

If Farhelm is already running on the host (you set it up before, say), the host is added as it is and the dialog closes. Otherwise Farhelm asks first, listing each step setup would take on the host with the paths it uses. Copy plan copies that list, and Cancel changes nothing on the host.

What setup will create on the host, with its set up and set up, don't ask again buttons explained.

Farhelm does not need tmux on the host. On a Linux host the list includes removing the copy of tmux that earlier versions of Farhelm installed there; on a host that never had one, that step has nothing to do (New terminals has more). After you choose Set up, the dialog closes and setup runs: the host’s mark on the navigation rail shows a ring until it is done. Setup progress also appears above your sessions, naming the current step; hover over that row to see every step, or select it to open the host’s row in the host list, which Hosts at the foot of the navigation rail opens.

A remote host in the host list with its green connected dot explained.

The host now appears on the navigation rail, where choosing it shows only its sessions, and in the session launcher’s host menu; see Start a session. On a Linux host, Farhelm runs as a service of your user account, so it and its sessions keep running after you disconnect. It starts again when the machine boots where the system allows that, and at your next login where it does not.

On a remote Mac, setup places Farhelm’s program in ~/.local/lib/farhelm and its data in ~/.local/state/farhelm. It creates a background job, io.farhelm.supervisor, with its file in ~/Library/LaunchAgents. The setup question names those paths and the job before you confirm. The job runs Farhelm right away, keeps it running after you disconnect, and starts it again after a crash. After a reboot, choose Update from the host’s ⋯ menu to start it again (Manage hosts covers that action). Automatic startup at screen login has not been verified. This does not change how the desktop app runs Farhelm on your own Mac.

To have Farhelm ask again before setting up a host, turn off Set up new hosts without asking under Hosts in the settings behind the gear at the foot of the navigation rail; Manage hosts has the rest of a host’s settings.

  • When Farhelm cannot reach the host, the dialog shows ssh’s own error. Check that ssh <destination> true works in a terminal without a password.
  • A Linux host without systemd’s services for your user account cannot be set up automatically, and the dialog says so.
  • A Mac with the Farhelm desktop app installed cannot be set up, updated or uninstalled over SSH. If Farhelm is already running there, adding the host still uses it as it is. If a Mac lacks a command needed for setup, the dialog names the missing command.
  • When setup fails partway, the host appears above your sessions with Details, and its mark on the navigation rail shows a warning. Choose Details to open the host list at that host and see which step failed. Re-run in its ⋯ menu tries again.
  • Adding a destination that is already in your host list is refused, and the dialog names that host. To set it up again, use Update in its ⋯ menu, or Re-run if its setup failed.

Next: Start a session, or, to remove Farhelm later, Uninstall Farhelm.