Manage hosts
The navigation rail, the column of icons down the left edge of the sidebar, shows your ordinary session hosts. It shows your Mac, captioned Local, and each remote Linux machine or Mac you added, each with its mark, a short name, and a dot that says whether Farhelm can reach that host right now. Point at a host’s mark to see its full name. To keep every name in view, select » (Expand navigation rail) at the very bottom of the rail: the rail widens beside the session list, and « Collapse narrows it again. Farhelm remembers which you chose. Choosing a host there shows only its sessions, and All shows every host’s again (Read the session list). The Hosts button at the foot of the rail swaps the session list for the host list, where your Mac is listed as Local (this machine) and everything on this page happens; choose a host or All on the rail to go back. Adding a host is covered in Add a remote host.
The bell just above Hosts shows notices about a host, starting with trashed checkouts whose files could not be freed. It turns red with an unread count. Opening and closing it quiets the bell while keeping the problem listed until it is resolved. Host setup and update problems are not listed there; they show on the host’s mark and in the rows above your sessions, described next.
Hosts with a problem, an update, setup still running, or a sandbox or container being deleted also appear above your sessions, so you can keep track of them while you work. While a setup, update or uninstall runs, its row names the current step; hover anywhere on the row to see every step and the reason for any problem. Select a row or its Details button to open the host list at that host. The list disappears when nothing needs attention and while the full host list is open.
The host menu
Section titled “The host menu”
Open it from a host’s ⋯ in the host list, or right-click the host’s mark on the navigation rail. Update installs
your Mac’s version of Farhelm on the host; Update a host has more. Other items appear only when a host needs attention, such as setting
Farhelm up on a host that does not have it yet. Your Mac’s own row has no Uninstall or Remove. In the Farhelm
app installed on your Mac, its Update checks for a new release of Farhelm and installs it, as
Update or uninstall Farhelm describes. In the Linux app, or in a copy of Farhelm
that is not installed in ~/Applications, it is greyed out instead. If Retry or Adopt fails, a dialog shows
why.
A Tensorlake sandbox has Delete sandbox in place of Remove, and no Uninstall: Farhelm owns that machine, so deleting it loses its files and sessions. Suspend or delete a Tensorlake sandbox covers it. A container session’s host has Delete container, which removes its whole environment and files. The menu of a sandbox or a container also has Suspend, or Resume once it is suspended, and a suspended one shows Resume on its row too; Suspend and resume for a sandbox explains what each keeps and when Suspend asks first, and Container sessions covers a container’s. A container session’s container, like a sandbox session’s sandbox, appears in Hosts and update notices without a permanent rail icon.
Host settings
Section titled “Host settings”
Choose Settings in a host’s menu to open its settings. The destination and alias save with their field’s Save, and the checkout folder with its own; everything else saves as you change it.
The destination is what you would type after ssh, such as dev@build-box or a name from your ssh configuration. The
alias is only for display: it changes how the host is shown everywhere in Farhelm, up to 64 characters, and nothing on
the host itself. Without an alias, the navigation rail and the session list show a short name instead: the first part
of the hostname, or the whole IP address. The local Mac’s destination and a Tensorlake sandbox’s destination cannot be changed. Start YOLO sessions without asking is the same choice the
YOLO confirmation offers when you start a session.
Manage sessions on this host without asking lets agents in this host’s sessions create, spawn, copy, rename, stop, restart and delete sessions on this same host. A copy’s source must be here too. It starts off on every host, including Tensorlake sandboxes. Requests for other hosts, template changes, host changes and links are outside this permission. Farhelm must still be open, because the helm, the program that shows all your hosts’ sessions and serves the UI, runs inside the app and handles these requests (The pieces).
Run farhelm commands without asking also covers session actions on every other host and changes to your launch templates. Changing one switch does not change the other; you can change either while the broader permission is on. Approve what agents do explains their limits: wrapper prefixes can still need your own approval, host changes and new sandboxes or containers always do, and YOLO or custom-command launches still need the separate YOLO permission. A plain restart, including of a YOLO session, needs no YOLO permission.
Open links without asking and Open local-network links without asking are separate permissions for opening this host’s sessions’ links in your browser. Both start off, and the second includes your machine and private network. Open links from a remote session explains the cards and why allowing local-network links needs a separate choice. Adopting a reinstalled or replaced host turns all five permissions off again.
For any host, choose an icon and a color under Appearance to tell its sessions apart at a glance. The mark appears on the navigation rail, beside its sessions, in the host list and quick switcher, and in the session launcher’s host picker. Each choice saves as you make it. Your Mac starts with a red laptop mark, which you can change.
Under Checkouts, Checkout folder chooses where this host’s new managed checkouts go. Leave it empty to use the default shown in grey from Settings → Checkouts. Save an empty field, or choose Use default, to follow that default again. This field needs Save; it can be changed while the host is disconnected or suspended, and existing checkouts stay where they are. Start from a managed checkout covers launching one.
In Settings, Color terminal frames by host under Sessions adds a thin frame around every terminal in its host’s color. It starts off. The terminal background and text colors stay the same. The switch is kept by the helm and takes effect at once.
Update a host
Section titled “Update a host”When a host has an update, its mark on the navigation rail and the Hosts button at the rail’s foot show an up-arrow. Above your sessions, each update row offers Update. If several listed hosts have updates, Update all updates those hosts. While automatic updates are off, Always update there also updates the listed hosts and turns on Update remote hosts automatically, so later updates install without asking. If that choice cannot be saved, a message says later updates will still wait, with Try again. You can dismiss optional update reminders; required updates stay visible because that host’s sessions cannot be reached until it is updated. The reminders return when another host gains an update, or when you quit and open Farhelm again.
When a remote host runs an older version of Farhelm than your Mac, an ↑ Update button appears beside its name: amber when updating is optional, red when the host cannot connect until it is updated. Hover over it to see both versions. Clicking it updates the host straight away, without asking, and shows the progress in its place. Update all at the top of the full host list updates every remote host whose Update action is available.
Updating a host does not interrupt its sessions: they keep running through the update. This includes remote Macs; Update, Update all and automatic updates use the same flow for them. A remote Mac with the Farhelm desktop app installed cannot be updated this way, even though you can use Farhelm already running there; update Farhelm from the desktop app on that Mac instead. If Farhelm cannot plan an update, a dialog shows the reason before anything changes. While the update runs, its progress appears above your sessions; hover over that row to see each step. A failed update appears there with Details, and the host’s mark on the rail shows a warning until you open the host list, where its row shows what happened.
To have Farhelm update remote hosts as soon as updates are available, turn on Update remote hosts automatically in Settings, under Hosts. It starts off; Always update above your sessions turns it on too. Once on, it works whenever Farhelm is running, which on your Mac means while the app is open. It never updates your Mac. If an automatic update of a host fails, Farhelm does not try that host again until it reconnects or Farhelm restarts; the host keeps its up-arrow, so you can update it yourself. The choice applies to every remote host.
Uninstall Farhelm from a remote host
Section titled “Uninstall Farhelm from a remote host”This applies to SSH hosts. A Tensorlake host has Delete sandbox instead.
Uninstall first shows what it will remove from the host: the supervisor’s service
and Farhelm’s program files, each with its path there. On a remote Mac this removes its background job and the job’s
file in ~/Library/LaunchAgents. It also names the directory that holds the host’s Farhelm data, which it keeps, and
stops the small Farhelm processes that keep its terminals running. Nothing changes until you select Uninstall in
that dialog. Once it is done, the host is gone from the list. A short line above it confirms the
removal; hover over the line to see where the data remains, or use its Copy button to copy that directory’s path. You
can dismiss the line with ×. Delete the directory on the host yourself if you want the data gone too.
Uninstall never stops a session for you. If any session on the host has not ended (it is running, waiting or idle, or
its status is not known yet), or still has a terminal tab open, it says which ones and does nothing. Stop those sessions
first; Stop also closes their terminal tabs, as in Stop, restart, and resume. Do not start a
session on the host while the uninstall runs: one started then can end along with Farhelm. Uninstall also needs Farhelm
to be connected to the host so it can check. If its row shows Unreachable, retrying, Needs update, Too new,
Identity mismatch, Identity unverified or Duplicate, fix that first: the refusal says how, and so do the
host’s details. Remove still works. A few less common setups are
refused too, with the reason shown in a dialog: a remote Mac with the Farhelm desktop app installed, one whose Farhelm
runs from somewhere unexpected (such as a Linux host set up with an earlier release’s farhelm helm setup), and
one whose
~/.local/lib/farhelm directory is a symbolic link or has something mounted on or inside it. On a Mac the mount check is
best effort: a mount whose name contains “ (” or “ on “ can go unnoticed. Remove still works for all of them.
If something goes wrong partway, the host stays in the list and its details show which steps finished. Choose Uninstall again to finish the job; it picks up where it stopped. Once a failed uninstall has removed the service and Farhelm’s supervisor there has stopped, the next one can finish even though the host no longer answers.
To remove Farhelm from your Mac, see Uninstall Farhelm.
Remove a host
Section titled “Remove a host”
Remove in an SSH host’s menu asks first.
For an SSH host, removing it only makes Farhelm forget it. Nothing is stopped or uninstalled on the host, and adding the same destination again brings back its sessions, though their pins, and which ones you had already looked at, start fresh. Cancel or Escape leaves the host where it was. Removing a container host or changing its destination requires cleaning up the environments and recipe images recorded there first. A refusal names what needs cleanup. Container sessions explains their confirmed deletion.
The dialog stays open until Farhelm answers; if removal is refused, it shows why. If you chose to skip the confirmation, a refusal shows under the host’s row in the host list instead.
Suspend or delete a Tensorlake sandbox
Section titled “Suspend or delete a Tensorlake sandbox”Choose Suspend in a sandbox host’s menu to suspend it, which stops its CPU and memory billing while keeping its files and processes. Tensorlake can also suspend a sandbox host itself, for example on the Usage Credits plan after 24 hours without a connection from Farhelm; Tensorlake sandboxes explains more. A suspended host shows a grey Suspended state with Resume on its row, and an open session on it offers Resume host. While it resumes, it shows Resuming… and then Connecting.
Delete sandbox permanently deletes the sandbox, its files, sessions and snapshots taken from it. It always asks, regardless of Remove hosts without asking. Keep work you need elsewhere first. While Farhelm deletes it, the host shows Deleting…. If deletion fails, the host stays listed with the reason; try Delete sandbox again to finish. This needs a saved Tensorlake API key. Its recipe and the recipe’s prepared snapshot remain available for new hosts.
Turn the questions back on
Section titled “Turn the questions back on”
The gear sits at the foot of the navigation rail, below Hosts. The switches cover only actions you start in the UI; agents’ host requests still need your approval. These two apply to SSH hosts, and a change takes effect at once. Tensorlake creation has its own Create Tensorlake sandboxes without asking switch under Tensorlake; deleting a sandbox always asks.
Settings describes its other sections.
See more about each host
Section titled “See more about each host”
A host’s row also opens by itself while a setup runs on it, or when its last setup or update failed.
A Tensorlake host’s details also show its sandbox name, recipe, CPU and memory, and tunnel mappings and status. A failed tunnel makes its dot amber and shows the reason. A suspended host’s details say when suspension was noticed and whether it happened outside Farhelm. Tensorlake sandboxes covers its recipes and account settings. A container environment has its own entry in Hosts and update notices, without a permanent navigation rail icon. Its details identify the recipe, container host, tunnel status and credential delivery warnings.
Supported agents covers what each agent needs on a host, and The pieces explains what Farhelm runs on each one.