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

Start a session

The + (New session) button above the session list, which opens the session launcher.

On a Mac, Cmd+N opens the session launcher too, even while you are typing in a terminal; the Linux app has no shortcut for it. See Keyboard shortcuts for the app’s other keys.

When you launch, the launcher closes and the new session appears in the session list. Its terminal opens, where you can type your first prompt, or supply it in the launcher. If you have clicked or typed elsewhere in the meantime, Farhelm leaves you where you are and briefly shows Started “name” at the bottom of the window instead.

If the host takes more than about two seconds to answer, a small status at the bottom of the window shows the host’s name and how many seconds you have been waiting. You can keep working in other sessions meanwhile. If the launch fails or needs an answer from you, the launcher comes back with your choices. If you have moved on by then, a banner across the top of the window says so instead, and its Open launcher brings the launcher back.

The search box comes first, then where the session runs, then the Agent and Command tabs with their choices.

The launcher's footer: what Launch will start (Codex, Local (this machine), and the directory), the summary of choices, and the Launch button.

Cancel, Escape, or the × (Close) at the top of the launcher closes it and forgets your choices. Reset choices clears the agent, model, and effort, and puts permissions and the wrapper prefix back to what the launcher remembers; it keeps the host, directory, and name.

The launcher's destination part: the folder or managed checkout choice, the host menu, the directory field, and directory history dropdown.

Runs on chooses between Existing host and a new environment made for this session: New container when you have a host that can run containers, and New sandbox once a Tensorlake API key is saved. Container sessions use a recipe and a Linux container host; sandbox sessions use a recipe and your Tensorlake account, and Farhelm asks before creating the billed sandbox. Either can clone a managed checkout inside or start in the new environment’s home. Opening + (New session) while a sandbox or container session is open preselects a new one from that session’s recipe, on the same Tensorlake account or container host. The host and directory controls below apply to Existing host.

With no session open, the Host menu starts on the machine you are using, listed as Local (this machine). A host that is not connected right now shows its state next to its name, such as “Unreachable, retrying”, and you cannot launch on it until it is back. Add a remote host covers adding hosts.

The directory field starts at the directory of your last agent launch on that host, or at the host’s home directory if you have not launched an agent there yet; a launch into a new managed checkout, a new container or a new sandbox does not count. With a session open on the same host, it starts at that session’s directory instead. Changing the host switches to that host’s directory, unless you typed or picked one yourself. With Folder chosen, the launcher also checks the directory on a connected host: if it does not exist there, or is not a directory, a warning under the field names the host. You can still launch; the host checks the directory again when you do.

Browse, under the host, lists the directories under the path in the directory field one level at a time, for when you would rather find a directory than type it. Choosing one of the directory list’s entries fills the field without launching. Local home also switches the host to Local (this machine). With the list open, Escape closes the list first. Name (optional) names the session in the session list; leave it empty and Farhelm picks a name.

The harness buttons with Codex chosen, and the model choice under them, both explained.
The effort and permissions choices, each explained.

Not every agent has every choice, and some offer other permission modes; Permission modes explains each, including Custom for supplying your own permission flags. Switching to another agent clears any choice it cannot take, and the launcher tells you when it does. You can choose Guarded or YOLO before choosing an agent. If choosing an agent replaces a permission you chose with a riskier mode, a red banner says so and offers Undo, including on your first agent choice. Supported agents lists what each agent offers. To answer directory-trust questions automatically for directories Farhelm manages, use the agent trust settings. To run something that is not one of these agents, switch the launcher to its Command tab, covered in Custom commands.

To start a known agent through another command, enter a Wrapper prefix on the Agent tab. Farhelm places it before the command it builds for that agent; Agent wrappers explains what the wrapper must pass through and when to use a custom command instead.

NOTE: The launcher remembers the permissions of your last launch from its Agent tab and the last wrapper prefix used with each agent. After you launch with YOLO chosen for an agent whose default is not YOLO, the next launcher opens on YOLO too; Custom flags are never remembered this way. Launches your agents start, custom commands, and plain Replace do not change what it remembers.

If you know an agent conversation’s id, enter it in the launcher to continue that conversation instead of starting fresh. This works in New, Clone and Replace with, for an agent in an existing directory. Pi and OMP ask for a session file instead; use its absolute path or a path relative to the session directory, without spaces or ~.

The choice applies to this start only. Templates and recent setups do not save it, and a later Clone starts fresh. Farhelm does not check whether the conversation exists; a mistyped id is handled by the agent. Goose, Cursor and OpenCode can open a conversation this way, but Farhelm cannot continue it with a later Restart. For restarting a session whose id Farhelm never learned, see Restart with.

For agents that accept one, Initial prompt supplies the first message when the session starts. The box accepts multiple lines, and Enter adds a line without launching. Restart, Clone and Replace do not send the message again; Clone and Replace with open with it cleared. Picking a recent setup leaves a message you have already typed alone. Goose, Pi and custom commands have no initial-prompt box, and Muse cannot combine one with a conversation id.

To reuse a message for new sessions, save it in a launch template.

Before a YOLO launch, Farhelm asks you to confirm unless that host has Start YOLO sessions without asking on. New Tensorlake hosts start with this on; other hosts ask until you tell them not to. This setting skips the confirmation, not the launcher’s permission choice.

The YOLO confirmation, with answers to start guarded instead, start YOLO once, stop asking on this host, or cancel.

Cancel goes back to the launcher with nothing started.

If you chose YOLO and the agent also offers Guarded, Start guarded session instead starts it with the agent’s own safety checks. This choice is available in the session launcher and Restart with.

On a host that asks, it is not only the YOLO choice that asks. Custom permission flags ask too, because Farhelm does not check what they do. Farhelm offers Pi and OpenCode only in YOLO mode, so every launch of either asks. Goose runs in YOLO mode unless you pick one of its approval modes, so its launches ask too, and so does a custom command you say runs in YOLO mode. Farhelm goes by that answer alone and never reads the command to check it. Cursor launches ask as well, because they run on Cursor’s own setting, and so does a plain Replace of a session an older version of Farhelm started without choosing a permission mode. It does not take an agent’s word for it, though, and an agent cannot confirm a YOLO launch: on a host that asks, an agent cannot start a YOLO session or a custom command at all (Approve what agents do).

To change your mind about a host later, open Hosts at the foot of the navigation rail and choose Settings from that host’s ⋯ menu. Manage hosts covers the rest of a host’s settings.

A host's menu in the host list, with its settings item marked.
The permissions part of a host's settings, with the Start YOLO sessions without asking switch explained.
The recent setups list under the launcher's search box, showing setups that match the chosen directory.

A setup keeps the agent, model, effort, permissions, wrapper prefix and destination of a launch you made on the launcher’s Agent tab, however you filled it in. Farhelm keeps setups separately for each host, and keeps launches into a new sandbox or container on their own, so they stay after that sandbox or container is deleted. The launcher shows up to three, from the chosen host and from your new sandboxes and containers. Type recent: in the search box to find older setups.

A setup that made a new sandbox or container names the recipe and where it runs, such as “web container on build1”. Matching setups can show even when the selected host is disconnected or you already have a recipe selected. Choosing one restores the recipe and where it runs. The next launch creates a fresh sandbox or container. If the recipe or container host has been removed, choose another before launching.

If you choose one of these setups in Replace with…, Farhelm refuses it and says Restart and Replace keep the existing environment.

To start another session like one you already have, choose Clone from that session’s menu instead. It opens the launcher with that session’s choices already filled in. Stop, restart, and resume covers it, along with Replace with….

The search box has the keyboard focus when the launcher opens, so you can set up a whole launch without the mouse.

The launcher's search box with claude typed, listing matching agents, models, and setups.

Enter takes the highlighted result. Typing a path offers to use it as the directory or to browse it. When nothing matches ordinary text, the list offers Set session name. For example, type asdf and press Enter to name the session; a separate Enter in the emptied box launches it. A prefix with no matching choices shows why, while you type. Escape hides the list or its message without clearing your text; Enter reopens it before another Enter can choose a row. Away from the search box, Enter on one of the launcher’s choices, such as a harness, an effort, or a recent setup, picks it and launches with everything as it then stands.

In the directory dropdown, Enter chooses a suggestion only after an arrow key has highlighted it, without launching. With nothing highlighted, Enter in the directory field launches the path you typed.

The search box with name: claude typed, offering that session name instead of choosing the Claude agent.

A few other prefixes do something no plain search does: gh: starts a managed checkout, tl: applies one of your launch templates, saved sets of launcher choices, and perms: picks a permission mode, including Agent’s own setting where available. You can also type guarded or yolo without a prefix, even before choosing an agent; perms:guarded and perms:yolo work then too. Other permission modes and effort choices need an agent first. Rejections and errors appear in yellow, while ordinary typing hints keep the normal text color. effort:default returns to your agent’s default reasoning effort. The rest only narrow a search to one kind of thing: host:, harness:, model:, effort:, folder:, and recent:. host:local picks the machine you are using.

For a setup you use often, mark a quick-launch template. Cmd+P on a Mac, or Ctrl+Shift+P on Linux, starts it directly. A YOLO question or failed launch opens the session launcher with the setup ready to finish.

For a saved setup you know by name, Cmd+J on a Mac or Ctrl+Shift+J on Linux opens a template-only list. Type its name and press Enter to start it; if it needs more choices, the session launcher opens with its saved choices applied.

For several favorite setups, give templates number shortcuts: Cmd+0–9 on a Mac, or Ctrl+Shift+0–9 on Linux.

You can also combine templates from the keyboard: Cmd+X on a Mac, or Ctrl+Shift+X on Linux, then their number keys and Enter. Later templates override earlier choices, so a project setup can be combined with a different agent.

While New, Clone, Replace with or Restart with is open, the ⚡, number and sequence shortcuts apply templates to the current draft instead of starting a session; the template list’s shortcut does nothing there. You can stack several presses, then review the choices before pressing Launch. The sequence prefix works in the launcher’s text fields when no text is selected; with text selected, the keys keep their usual meaning, such as Cut on a Mac.

A session can also start in a new clone of a GitHub repository instead of an existing directory. Farhelm calls this a managed checkout. It makes the directory for the session. On an ordinary host, deleting its last session moves it into the trash (see Stop or delete). The trash at the top of the session list shows where those directories are and lets you clean them up. In a container session or sandbox session, the clone lives inside and Delete removes it permanently, without trash, unless another session still uses it; deleting the last session there removes the whole environment too.

Choose Managed checkout in the Where row, enter the repository as owner/repo, and select its suggestion. You can also type gh:owner/repo in the search box and choose Managed checkout: owner/repo. Farhelm suggests repositories you have launched or cloned before, but it does not search GitHub, so type a new one in full.

On an existing connected host, the launcher shows the directory the clone will go into before launch, and the launch button waits until it does. A new container or sandbox picks its directory inside once it is ready. Quick launch creates that directory directly: marking the template means you have chosen to start it without seeing the path first. Giving it a number key makes the same choice. Each checkout gets a new directory of its own, named after the repository and numbered (farhelm-1, farhelm-2, and so on), or named after the repository and the session if you gave the session a name (farhelm-fix). Folder switches back to an ordinary directory.

Clone on a session in a managed checkout starts a managed checkout of the same repository, even if the session runs in a subdirectory. The name starts as the source’s name plus -clone, then -clone-2, -clone-3, and so on when taken. Editing the name keeps exactly the name you enter and reports a conflict if its directory is taken. Folder restores the source’s directory and name; for a new sandbox or container it stays at the home directory. Replace with and Replace keep the existing directory.

When no prepared checkout is ready, Git brings the host’s cache of the repository up to date, then clones the default branch in the session’s terminal. The agent starts once that finishes. Both commands use the host’s own Git credentials, so anything Git asks for, such as a password, shows up in the terminal for you to answer. A private repository without a credential helper can ask twice. If either command fails, the session’s status shows error, the terminal says what went wrong, and any partial clone stays where it is.

In a container session or Tensorlake sandbox, private repositories need a GitHub token that the host’s recipe selects from Settings → Credentials; public repositories need none.

The cache makes repeated managed checkouts faster and takes roughly the disk space of one extra copy of each repository on each host. It lives under Farhelm’s state directory on that host, in repo-cache/<owner>/<name>.git, outside your checkout directory. Farhelm removes caches unused for more than 30 days when the host’s supervisor, the program that keeps its sessions running, starts (see The pieces). You can delete a cache directory by hand at any time; existing checkouts stay independent, and the next managed checkout downloads it again. Avoid doing that while a checkout is being prepared, since it can make that launch fail, and leave the sibling .lock files in place so concurrent checkouts still take turns. Git tidies the cache in the background after a launch rather than in its terminal; another launch of the same repository may wait while that finishes. A cache failure names its path in the terminal and stops the clone.

An agent on an ordinary host can also start a session in a new managed checkout when you ask it to, with your approval (Approve what agents do).

On ordinary hosts, first tell Farhelm which directory new checkouts go into. Until you have, choosing Managed checkout asks for it:

The launcher in managed checkout mode asking for the checkout folder, with the field and its save button explained.

This sets the default for hosts without a directory of their own. To change it later, or save an empty field to clear it, use Default checkout folder under Checkouts in Settings, opened from the gear at the foot of the navigation rail, the column of icons down the left edge of the sidebar.

The same section has a Post-clone command field for a shell command to run in each new clone, on its host, before the agent starts (installing dependencies, say). Save it explicitly; empty the field and save to remove it. Changes affect future checkouts only.

By default, Farhelm keeps one extra checkout ready for each repository you launch on each host. The next launch updates that earlier clone from GitHub instead of cloning again, avoiding much of the local work. Its terminal says when it uses an earlier checkout. The Keep a checkout ready for faster launches switch is under Checkouts in Settings.

The extra checkout uses disk space in .farhelm-spares inside your checkout directory, in addition to the repository cache. Farhelm prepares it through your login shell, without a terminal or credential prompts, at low CPU priority for at most about ten minutes. If credentials need you to type something, or preparation fails, the next launch can clone normally in its terminal. Your post-clone command still runs only when you launch, in the session’s final directory.

This is a clone made earlier and then updated. Unchanged files keep older modification times, and Git’s reflog records the earlier clone and update. FETCH_HEAD and ORIG_HEAD exist, and objects from deleted branches can remain until Git cleans them up. Git hooks and checkout filters, including Git LFS, run when the extra checkout is prepared in another directory, then only for the update in the final directory. That update runs post-merge rather than post-checkout.

If the branch was deleted upstream, or rewound or rewritten so that it no longer contains the prepared checkout’s commit, Farhelm clones normally. Git 2.48 and later also notices a changed default branch; older capable Git may use the original default branch until the next spare is prepared. Any other failed update stops the launch and shows its error instead of starting another clone and asking for credentials again.

Turning the switch off affects future creates. Each repository’s prepared checkout is discarded at its next create on that host. Choosing a different checkout directory likewise discards the old spare when you next create a checkout of that repository. Unused spares go with the repository cache after 30 days. Leave .farhelm-spares to Farhelm; uninstalling keeps it alongside your other checkout data.

The Agent trust section in Settings has separate trust switches for Codex, Muse and Pi, all off by default. Each applies on every host to directories Farhelm manages, including checkouts an agent requests. Enabling one lets the repository’s own hooks, settings and commands run as if you had approved them. Farhelm passes an argument when starting the agent; it leaves the agent’s saved configuration alone. Directories outside managed checkouts keep the agent’s own trust behavior. These switches apply to the launcher’s Agent tab; custom commands keep their own arguments.

The current setting applies when you start a session, use Clone, Restart with or Replace with in a managed checkout. Plain Restart and Replace reuse the trust carried by the saved launch. See Stop, restart, and resume for those actions. Muse’s YOLO mode grants trust regardless of its switch. Pi’s switch approves project settings and extensions; Pi still runs the agent’s actions without asking.

For Claude, Agent trust can also Answer Claude’s “trust this folder?” for new checkouts. This is off by default and applies to future managed checkouts on every host, including ones an agent requests or that start with another agent. Directories you choose yourself still get Claude’s question.

There is no supported Claude switch for this. Farhelm edits Claude’s own settings file on the session’s host, normally ~/.claude.json, and removes that directory’s trust key when the checkout moves to the trash. The edit is best effort: a Claude session exiting at the same instant can lose either program’s update, and a future Claude version can change how the file works without notice. Read the caution in Settings before turning it on. As with answering Yes yourself, trust allows the repository’s own Claude hooks and commands to run.

While Claude, Codex or Muse asks its trust question in a managed checkout and that agent’s switch is off, a note above the session’s terminal says, in that agent’s words, that Farhelm can answer it for you. Its button, Settings and caveats for Claude and Settings for Codex and Muse, opens Agent trust at that agent’s switch. × hides the note until the question leaves the screen, and Don’t show again stops that agent’s note for every session, leaving the other agents’ notes alone. To bring one back, turn on Show the hint when Claude asks about a managed checkout, or the Codex or Muse one, in Agent trust. The note goes away once you turn the agent’s switch on. Farhelm answers nothing from the note itself; the question waits in the terminal as before. A Codex or Muse session started from the Command tab shows no note, and neither does Pi.

Each host can have a checkout directory of its own in its settings. An empty Checkout folder uses the default from Settings → Checkouts; Use default restores that choice. Changing the default affects each host without its own directory at its next launch, including hosts already added. Existing checkouts stay where they are.

The post-clone command applies to every host. To give one host a command of its own, run farhelm helm checkout-config on the machine where you run the Farhelm app, whose built-in helm keeps your checkout settings (see The pieces); farhelm helm checkout-config --help lists the options. A host given its own command there keeps it whatever Settings says.

Farhelm owns the managed checkouts it makes, the directory they go into, their prepared checkouts and their trash. Work in a checkout as usual, but do not restore a backup or filesystem snapshot over them, and keep them on an ordinary filesystem rather than one like FAT: Farhelm does not detect such changes.

What you see depends on how far the launch got. When Farhelm can tell before starting anything that the launch will not work, for example because the directory does not exist on that host or the host just went offline, it shows the reason in a Not launched. alert under the launcher’s buttons and keeps your choices, so you can fix it and launch again. No session is created. When the agent itself fails to start, for example because it is not installed on that host, the session is created and its status shows error; the agent’s page in Supported agents says what to install. An agent that starts and then quits shows exited. Read the session list explains each status.

If you try to launch on a suspended sandbox, Farhelm shows the host’s name and asks you to resume it first. For example, devbox is suspended. Resume it in Hosts, then launch. A quick launch to a suspended Tensorlake host is refused for the same reason.

If the host does not answer within 20 seconds, the launcher comes back without Not launched. and says the request is still being carried out: the session may still start and appear in the session list. Your choices stay in the launcher.

With the session running, Work in a session covers talking to the agent in its terminal, and Read the session list covers keeping track of what your sessions are doing.