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

Launch templates

A launch template is a set of session launcher choices saved under a name. It holds only the choices you put in it, so templates combine: one can pick your usual agent and model, another the host and directory of a project, and applying both sets up the whole launch.

The Templates button beside + (New session) above the session list, which opens Templates.
The Templates list: choose a template to edit it, or use + New template to start another.

Choose + New template, give it a unique name without spaces or other whitespace, then choose Switches launcher to: Agent, Command, or Don’t switch. An agent or command template opens that tab when you apply it. Don’t switch keeps the current tab and offers only the host, destination, and session name.

Use + Add field for each choice the template should make, then Save. Only the fields shown under Sets are applied; a field you remove with ✕ is left alone. A Default value resets that choice to the agent’s default, which is different from leaving it out. An empty model input means the default model; otherwise you can type any model, with suggestions when the template sets an Agent type, earlier versions under Older models. Approvals and other offered choices follow that agent type. Without an agent type, every approval choice is offered, and applying the template is refused if the chosen agent does not offer that choice.

An Agent template can also choose Bash or Zsh as its Agent type for a shell session.

An agent template can also set a Wrapper prefix. Type the words that go before Farhelm’s agent command, or leave the field empty to explicitly run without a wrapper. Removing the field with ✕ leaves the launcher’s current prefix alone, including its remembered value. See Agent wrappers for the pass-through rules and why a prefix should not contain secrets.

To reuse a first message, add Initial prompt and type it into the multiline box. Each new session started from the template receives that message; you can edit it in the launcher before starting. The field is offered for agents that accept an initial prompt, or while the template leaves the agent type unset. It is not offered for command templates.

The destination can be a directory or a managed checkout, chosen with the same Folder and Managed checkout control as the launcher. On an ordinary host, its directory moves to the trash when its last session is deleted. A model or a destination can stand on its own. Another template can supply the agent or host.

The editor’s Host field begins with a Runs on switch like the launcher’s: Existing host with a host to choose, New container with a Recipe and a Container host, or New sandbox with a Recipe. Applying the template sets the launcher’s Runs on the same way. The editor offers recipes that are not built yet and container hosts that cannot run containers right now, since those are checked when you launch; a removed container host or deleted recipe stays selected, marked unavailable, and the launcher refuses the template until you change it. In a new container or sandbox the folder is its home, and a managed checkout is cloned inside. Deleting its session removes the checkout permanently, without trash, unless another session still uses it; deleting the container or sandbox removes every checkout in it the same way. See Container sessions and Give each session its own sandbox, which also covers the question Farhelm asks before creating a sandbox.

A Session name can be a Base name or a Fixed name. When you apply a base name in the session launcher or a quick launch, or an agent starts a session from the template, a managed checkout uses it as-is when free, then adds -2, -3, and so on up to -50 when taken. The session and its checkout directory get the same number, so you can launch the same setup repeatedly. A fixed name reports a clash instead. Names in existing templates are base names; a launch into an ordinary directory uses either kind as-is.

Workspace trust comes from agent trust settings. A trust choice saved in an older template is ignored and is removed when you save that template again.

Templates belong to the helm, the program that shows you every host’s sessions (The pieces), so you see the same ones whichever host you launch on. A template that sets a command still needs that command to exist on the host you launch on.

The keyboard shortcuts overview puts the launch keys in one place. In Farhelm, ? → Keyboard shortcuts also shows which templates currently hold ⚡ and number keys.

Mark a template with ⚡ to start it with Cmd+P on a Mac, or Ctrl+Shift+P on Linux. The session starts and is selected without opening the session launcher. Only one template is marked, and in the Templates list its bolt is filled amber while the others are outlines: selecting another template’s bolt moves the mark, and selecting the filled one clears it. To mark an Agent template, set Agent type to an agent, Bash, or Zsh. A Command template needs a nonblank command. With Don’t switch, it is judged as an agent launch.

Choices the template leaves out use the defaults of + (New session), including the open session’s destination and the directory it starts in, except that an open sandbox or container session does not make the quick launch start a new one like it. A template can start a fresh managed checkout this way too: marking it means you choose to create its new directory without first seeing the path. If Farhelm asks about YOLO or the launch fails, for example on a suspended host, the session launcher opens with that setup and the question or error. A template that starts a new sandbox opens the launcher on Create a sandbox for this session? the same way, unless you have turned that question off. Marking it, or giving it a number key, does not skip the question. With no marked template, the shortcut opens Templates to help you choose one. Renaming keeps the mark; deleting clears it, and Undo restores only the template.

The quick switcher’s Quick launch row does the same thing. While the session launcher is open, the shortcut applies the marked template to the draft and leaves Launch to you. Other dialogs keep their keyboard shortcuts.

To start any template by name, press Cmd+J on a Mac or Ctrl+Shift+J on Linux. This opens a template-only list: type part of a name, use ↑ and ↓ to choose, then press Enter. If you type the exact name, that template is highlighted. Each row shows its saved choices and any ⚡ or number shortcut. A template that needs more choices opens the session launcher for you to finish, with a banner saying it needs more choices. The same banner appears if your marked template no longer has what it needs to launch. Escape closes the list and returns focus to where you were. The shortcut does nothing while another dialog is open, including the session launcher.

After a quick launch, Rename opens with the session’s name selected while the agent is already starting. Enter keeps the name; typing replaces it, and Enter saves it. Escape or Cancel keeps the name too. Closing Rename takes you to the new terminal. This also happens for number shortcuts, combined launch sequences and the Cmd+J list, even when a template supplied the name. If the session launcher opened first, it already offered the name field and Rename does not open again. If you have clicked or typed elsewhere before the session starts, Farhelm leaves you where you are and skips Rename; rename the session from its row instead.

In Settings under Sessions, Name sessions on quick launch turns this off. It is on by default. Naming a session this way leaves its managed checkout’s directory unchanged: a directory created as repo-N keeps that name.

Give a template a number key with the key button beside its ⚡. Cmd+0–9 on a Mac, or Ctrl+Shift+0–9 on Linux, starts that template directly, with the same defaults and YOLO questions as quick launch. The key is the number’s position on your keyboard; it does not use the numeric keypad.

Each key belongs to one template, and a template has one key at most. Picking an occupied key moves it to this template; No shortcut removes it. Number keys and ⚡ are independent. Rename keeps the key; delete frees it, and Undo restores only the template. Pressing an unbound key from the session list opens Templates to help you set one. With the session launcher open, a bound key applies its template to your draft; an unbound key shows a message there. Other dialogs keep the keyboard.

Any template can hold a number key, even one that only changes a model or directory. Pressed alone, a partial template opens the session launcher with its choices applied and a brief banner explaining how to combine it with other templates. Complete the setup there, or close it and use a launch sequence. The ⚡ mark still needs a template that can launch on its own.

Giving a template a number key also chooses to create any managed checkout it names without showing the path first, just as marking it with ⚡ does.

Press Cmd+X on a Mac, or Ctrl+Shift+X on Linux, type template names separated by spaces, then press Enter. For example, Cmd+X, myproject codex, Enter starts myproject’s setup with codex’s choices applied on top. You can mix names with number keys: Cmd+X, Cmd+1, Cmd+5, Enter still combines keys 1 and 5, and bare number keys work too. The usual quick-launch chord adds your ⚡ template. Later templates win where their choices overlap, just as when you apply templates in the launcher.

A full name with the same capitalization wins first, then a full name ignoring capitalization, then a unique name starting with what you typed. If several names match, or none do, Enter shows an explanation and leaves the whole sequence unapplied. Matching names appear beneath the amber pill as you type. Tab completes and queues a unique match; an exact name wins over longer names that start the same way. Backspace edits only the unfinished word, leaving queued templates alone. Inside a word, a number key adds its character to the word; with no word started, it queues that key’s template. On keyboards where Shift types digits, Shift and a number key can start a name with a digit.

New or renamed templates cannot contain whitespace. Older names with spaces keep working, including editing and delete Undo. Tab can queue one of them when the text before its first space identifies it uniquely. With both my project and myproject saved, reach my project by its number key or the launcher instead.

A larger amber pill in the middle of the terminal shows your queued templates and the word you are typing, with a brief entrance and a soft glow. With no session open it sits in the middle of the main area; while the launcher is open it stays at the bottom so you can keep editing. There is no timeout. Escape cancels; clicking, leaving the Farhelm window or opening a dialog cancels too. Arrows and other shortcuts cancel and go to their usual target. While the sequence is active, typing stays out of the terminal. Enter with no templates queued cancels. Outside the session launcher, text fields keep the chord for themselves: Cmd+X still cuts on a Mac, and Ctrl+Shift+X starts no sequence there on Linux. In the launcher’s own fields, a selection keeps that normal action; without selected text, the prefix starts a sequence.

The combined setup starts directly, with the same defaults and YOLO questions as quick launch. If a template does not fit, the session launcher opens and names the template and choice that need attention. If the combined choices still do not make a complete setup, a banner says to complete it there. An unbound number opens Templates when you press Enter. With New, Clone, Replace with or Restart with open, Enter applies the queued templates to that draft instead of starting a session. The pill says apply there; an unbound key or template that does not fit shows a message above search and leaves that press’s edits unapplied. Single number shortcuts and ⚡ still start immediately from the session list without the prefix.

When you have set up a launch in New, Clone or Restart with, choose Save as template, beside Reset choices.

The save as template panel with a name typed and the agent and effort checked, with the name, checkboxes, and Save explained.

Agent, model and effort choices are checked when set, as are an initial prompt you typed and command choices. Approvals and a wrapper prefix are checked when you chose them; a host and directory only when you picked or typed them. A session name is checked after you type it or apply a template that sets it. A selected managed checkout’s repository is checked too; unselected repository text is left out. Remembered defaults and a cloned session’s host and directory stay available, but unchecked.

The session-name row offers Base name and Fixed name too. A name you typed starts on base; a name supplied by a template keeps that template’s choice. Saving a numbered base keeps the original name: app-review-2 is saved as app-review, ready to find the next free checkout when you use it again.

The template keeps the current Agent or Command tab and only the choices you check. Cancel or Escape returns to the setup without saving. Save as template is not offered in Replace with, for a session in a container or sandbox, or when Runs on is New container or New sandbox.

codex-deep selected for editing, with its agent switch, Codex, model, effort, add and remove controls, and Save button.

Choose a template’s row to open its editor. Duplicate opens an unsaved copy with a new name. Changes are saved only when you choose Save, which is greyed out until there is something to save; leaving an edited template asks whether to save, discard, or keep editing. Hidden formatting characters in a template’s fields show as visible codes, and such a field cannot be edited in place: remove it with ✕ and add it again. A template name with hidden characters shows them the same way and stays unchanged until you choose Replace name, which clears it so you can type a new one. A template whose session name or command contains hidden or control characters still launches, but Farhelm refuses to save changes to it until you replace those fields. This includes joined emoji in a session name.

Changing Switches launcher to or the Agent type can make a field that is already set no longer fit. It stays visible with a message: change or remove it before saving. A stored template that sets agent or command choices but has no saved tab choice opens with that tab chosen and marked as Unsaved changes; saving stores that choice, while discarding keeps the template applying as before.

Delete removes a template immediately. The Undo notice lasts about ten seconds while Templates stays open; choose it to restore the template, provided another template has not taken its name. An older template that no longer meets today’s rules for saving shows Delete permanently instead, and cannot be restored.

A session remembers the choices it was launched with, not which templates supplied them, so editing or deleting a template never changes a session that already started from it.

The launcher's search box with tl: typed, listing the three templates.
The launcher after applying codex-deep and then api-repo, launching Codex on build-box in ~/src/api.

Templates apply in the order you choose them, and where two set the same choice, the later one wins. A template only fills in what it holds, so anything the launch still needs, such as the agent when no template picked one, you choose by hand as usual.

You can also press the ⚡ shortcut, a bound number key, or a completed launch sequence while New, Clone, Replace with or Restart with is open. Several presses stack in order, and Launch remains your action. Your current field and search text stay in place unless a template switches tabs and removes that field; focus then returns to the launcher’s search.

A template whose choices do not fit what the launcher holds is refused as a whole, with a message saying which choice did not fit: a model the chosen agent does not offer, for example, or an older template with a model and no saved tab choice while the launcher is on its Command tab. In Replace with, a template can name the session’s own host, but a different host is refused. In Restart with, a template can repeat the current launcher tab, agent, host, directory or session name; changing one is refused. A first message is always refused when restarting.

Agents on ordinary hosts can apply templates too, when they start sessions of their own with the farhelm command. This command combines two templates.

Terminal window
farhelm agent create --template codex-deep --template api-repo

Here api-repo supplies the host and directory, so the command needs neither --host nor --cwd. Other options such as --model act as further changes after the templates, and farhelm agent templates lists the templates and what each sets.

An agent on an ordinary host can also use a template whose Runs on is a recipe. That starts a session in a new sandbox or container, and Farhelm always asks you first. An agent inside a sandbox or container can use only templates that set no host and no recipe, and cannot list or change templates (Agents in sandboxes and containers).

An agent on an ordinary host can start a fresh managed checkout with a template too, or give farhelm agent create --gh acme/web directly (--github is an alias). --title "Fix parser" names its directory web-fix-parser; without a title Farhelm picks the next free web-N. The approval card shows the repository and exact directory before starting it.

farhelm spawn always starts on the agent’s own host and never makes a fresh checkout, so it refuses a template that sets a host or a managed checkout. farhelm agent clone of a session on an ordinary host copies its existing directory and takes no repository option; cloning a sandbox or container session starts a new one from the same recipe instead. On a host that asks before YOLO launches, an agent cannot use a template that makes the launch YOLO or a custom command (Approve what agents do).

Agents on ordinary hosts can also create, edit, and delete templates with farhelm agent template create, edit, and delete. Create and edit accept --gh/--github for a managed checkout, or --cwd for an existing directory, and --title-kind base or fixed to choose the kind of session name. They can assign ⚡ with --quick-launch or a number with --key 1 (using any digit from 1–9 or 0). An edit can remove this template’s mark or key with --no-quick-launch or --no-key, even without changing its other choices. Assigning a mark or key that belongs to another template moves it; the card tells you which template loses it. The ⚡ mark needs an agent, Bash or Zsh for an Agent template, or a nonblank command for a Command template. Without a saved launch kind, it is judged as an agent launch. A number key can select a partial template. farhelm agent templates shows these assignments alongside each template’s choices. Each change shows you the whole template on a card first, command line included, and happens only if you allow it, unless you have told Farhelm not to ask for that agent’s host (Approve what agents do). A change that leaves a wrapper prefix in a template always asks, on every host, because later launches from it treat the prefix as yours. An agent’s edit cannot remove a choice from a template, so it never drops a command line the agent could not see.

NOTE: Templates are not a place for secrets. Every host your helm manages can read every template, command lines included.

Read the session list covers keeping track of the sessions you start.