Settings

Agent settings

Set the launch values that new tasks and schedules start with, and manage the launchers, their install status, status reporting and program paths.

On this page

Purpose

Task Defaults sets the launch values that a new task and a new schedule start with. Engines manages the launchers (the agents that Orkestra can start), shows which agents are installed, controls agent status reporting, and tells Orkestra where to find the agent programs.

Where to find it

  1. Click the Settings gear button in the top bar.
  2. In the list on the left, click Task Defaults or Engines.

Both panes keep your changes in a draft until you click Apply or OK. The window and its buttons are in Settings: the window, appearance, terminal, workbench and notifications.

What you see

Task Defaults pane (two groups)

Group New task launch defaults

  • Launch mode — choose where a new task starts: Current repository (default) or Separate worktree.
  • Default launcher — choose which agent launcher new tasks use. Each launcher has a button with its icon and name. No choice is selected until you choose one; first-run setup may select one for you (First-run setup, Getting started and tours).
  • Default model — a list. It starts with Default (engine-managed), then the models of the chosen launcher, then Custom model id…. Custom model id… opens a text field (example text "e.g. gpt-5.6-terra"). A saved model that the launcher does not list shows as "<name> (not listed)". A reload icon button (tooltip "Reload model list") loads the list again. The list is disabled until you choose a launcher.
  • Default effort — a list with Default (harness-managed) and the effort levels of the chosen model. A reload icon button (tooltip "Reload reasoning effort list") loads it again. The row shows only when the chosen launcher has an effort setting (Claude Code and Codex).
  • Permission mode — a list of the permission modes that the chosen launcher offers. The default is Ask each time. A reload icon button (tooltip "Reload permission modes") loads the list again.
  • Run automatically — on by default. When enabled, Orkestra sends the prompt and starts the agent immediately.

Group New schedule defaults

  • Default launcher — choose the launcher for scheduled runs. It is independent of the default launcher for new tasks. One button appears for each launcher.
  • Repeat — choose the initial schedule pattern: Once, Every day, Weekdays (default) or Weekends.
  • Permission mode — choose from the schedule launcher's modes. It defaults to Full access for unattended runs and has its own reload button.
  • Time — new schedules start with the current system time.

Engines pane (three groups)

Group Launchers

  • A launcher combines an agent with its own environment variables (for example, proxy settings) and extra arguments. Launchers can be used by Helm and terminal launch controls.
  • A note "Installed launchers are detected at startup. Re-scan after installing a CLI." and the Re-scan button (name "re-scan installed launchers").
  • One row for each launcher. A new Orkestra has Claude Code, Codex, Cursor, OpenCode and Antigravity. A row has, from left to right:
    • An arrow button with the launcher name. A small tag shows its base agent (for example "claude"). A second tag, "selected", marks the launcher that Helm uses (you choose it in Settings: Helm).
    • A status badge: Available, Not installed or Error.
    • A trash icon button (tooltip "Remove <name>").
  • The open row shows these fields:
    • Label — the launcher name.
    • Base — a list: Claude Code, Codex, Cursor, OpenCode, Antigravity. A launcher from old saved data can have no base. It shows Command (example text "gemini, /usr/bin/agent, or builtin:claude-acp") in place of Base. You cannot add such a launcher.
    • Color — color dots. The first (tooltip "Default (base color)") clears the color. The others are Blue, Violet, Pink, Rose, Amber, Green, Cyan, Orange.
    • Arguments — extra arguments (example text "extra args, e.g. --model gpt-5").
    • Environment — one line for each variable: a name field ("KEY"), a value field ("value"), a switch (name "store <name> as a secret") and a close icon button (tooltip "remove environment variable"). The button Add variable adds a line.
    • For a secret variable, a password field replaces the value field. It shows "•••• (set)" or "not set". A Save button and a trash icon button (tooltip "Clear the stored secret") follow it.
  • The button Add launcher. It adds a launcher named "New launcher" with the first base, Claude Code, and opens its row.

Group Agent status reporting

  • Let agents report their status through installed hooks — on by default. Compatible agents can use their installed hooks to report their status to Orkestra.

Group Executable resolution (collapsed at first; click its title to open it)

  • If Orkestra cannot find an agent program, enter its full path or add the folder containing it.
  • One row for each agent (Claude Code, Codex, Cursor, OpenCode, Antigravity). It has a text field (example text "Resolve from PATH") and a status badge.
  • Additional PATH directories — a text box with four lines. Enter one folder per line; Orkestra searches these folders before the usual program paths.

How to

Choose the default agent for new tasks

Before you start, open Settings.

  1. Click Task Defaults in the list on the left.
  2. In the group New task launch defaults, find the row Default launcher.
  3. Click the button of the launcher that you want.
  4. Click OK.

Result: the button stays pressed. New tasks start with this launcher. Tasks that exist keep their values.

Set the model, effort and permission mode for new tasks

Before you start, choose the Default launcher. The lists depend on it.

  1. In the row Default model, open the list.
  2. Choose a model, or keep Default (engine-managed).
  3. In the row Default effort, open the list.
  4. Choose a level, or keep Default (harness-managed).
  5. In the row Permission mode, open the list.
  6. Choose a mode.
  7. Click OK.

Result: new tasks start with these values. If you turn the Run automatically switch off, an agent gets the task prompt typed in its input but not sent.

Set the defaults for new schedules

  1. In the group New schedule defaults, click a button in the row Default launcher.
  2. In the row Repeat, click Once, Every day, Weekdays or Weekends.
  3. In the row Permission mode, open the list.
  4. Choose a mode.
  5. Click OK.

Result: a new schedule starts with this launcher, repeat and mode. Its time is the clock time of the moment that you create it. See Task window.

Add a launcher

Before you start, click Engines in the list on the left.

  1. In the group Launchers, click Add launcher.
  2. In the open row, type a new name in Label.
  3. In the list Base, choose the agent that the launcher uses.
  4. Click OK.

Result: the new launcher appears in the launch surfaces. Its icon is the mark of its base, and its color is different from the other launchers of the same base. See Starting terminals and agents.

Add an environment variable to a launcher

  1. In the group Launchers, click the arrow button of the launcher.
  2. Click Add variable.
  3. Type the name in the field "KEY".
  4. Type the value in the field "value".
  5. Click OK.

Result: Orkestra adds the variable when it starts this launcher. A name that contains TOKEN, KEY, SECRET or PASSWORD (in any letter case) turns the secret switch on. For a secret, type the value in the password field and click Save. The value is saved at once and never shown again. Turning the switch off, or removing the variable, deletes the stored value.

Remove a launcher

  1. In the group Launchers, click the trash icon button of the launcher (tooltip "Remove <name>").
  2. Click OK.

Result: the launcher is gone. The launcher that Helm uses ("selected") cannot be removed.

Re-scan the installed agents

  1. In the group Launchers, click Re-scan.

Result: the button shows "Re-scanning…", then the badges show the new state.

Point Orkestra at an agent program

  1. Click Engines in the list on the left.
  2. Click the title of the group Executable resolution to open it.
  3. In the row of the agent, click the text field.
  4. Type the full path of the program file.
  5. Click outside the field.
  6. Click Apply.
  7. In the group Launchers, click Re-scan.

Result: the badge next to the field shows Available. If the path is wrong, it shows Error. To go back to the normal search, clear the field.

Add a folder to the search path

Before you start, open the group Executable resolution in Engines.

  1. Click the box Additional PATH directories.
  2. Type one folder on each line.
  3. Click outside the box.
  4. Click Apply.
  5. In the group Launchers, click Re-scan.

Result: Orkestra looks in these folders first when it starts an agent.

Turn off agent status reporting

Before you start, open Engines.

  1. In the group Agent status reporting, click the check box "Let agents report their status through installed hooks".
  2. Click OK.

Result: Orkestra removes the entries that it added to the agent settings. A status that an agent reported before goes away at once, also "Awaiting input". Orkestra then guesses the status from the terminal output. Click the check box again to turn it on. If an agent already waits for you when you turn it on, Orkestra can miss that one wait. The next status that the agent reports is correct.

States and messages

  • Available (green dot) — Orkestra found the program.
  • Not installed (grey dot) — Orkestra cannot find the program.
  • Error (red dot) — the path that you typed does not lead to a program, or the scan failed.
  • Hover over a badge to see the reason. An open launcher row also shows the reason as a note.
  • No badge shows before the first scan, and none shows for a launcher without a base agent.
  • Re-scan shows "Re-scanning…" and is disabled while the scan runs.
  • A list shows "loading…" while it loads. On a failure the list is disabled and a text shows: "Models unavailable — retry.", "Reasoning effort unavailable — retry." or "Permission modes unavailable — retry." Click the reload icon button to try again.
  • The trash icon button of the selected launcher is disabled. Its tooltip is "Cannot remove the selected engine".
  • An empty Label is marked as not valid.
  • Save is disabled until you type a value and the variable has a name.
  • Without a system key store, a note says "Secrets are stored obfuscated, not encrypted — no system keyring is available. Install or unlock a keyring (gnome-keyring or kwallet) for OS-backed encryption."

Limits and tips

  • Defaults are copied when Orkestra creates a task or schedule. A change here does not change tasks and schedules that exist. A new schedule also copies Default model of the first group.
  • The launch buttons in the top bar do not use these defaults. The Launch dialog starts with the values that the task saved. See Starting terminals and agents.
  • A worktree that you drop on the canvas uses only Default launcher of the first group. It uses no model or permission default. When no launcher is set, or it no longer exists, a plain shell opens. See Worktrees.
  • When an agent starts a terminal through Orkestra's tools and does not name a launcher, Orkestra uses Default launcher for that agent. If it names no permission mode, Orkestra uses Permission mode of the first group.
  • When you change the launcher, the model returns to Default (engine-managed). A permission mode that the new launcher does not offer changes to the first mode of its list.
  • The model and permission mode of a launcher are not set in Engines. Helm has its own in Settings: Helm.
  • Arguments splits the text at spaces. One argument cannot contain a space. Orkestra trims spaces around each variable name and value.
  • A new base changes the icon and gives the launcher a color that no other launcher of that base has. Helm cannot use an Antigravity launcher. If you set Base to Antigravity on the launcher that Helm uses, Orkestra moves Helm to the first launcher that Helm can use.
  • Re-scan reads the saved settings, so click Apply first. The launch buttons hide an agent that is Not installed.
  • The path field has no Browse button. Type or paste the full path. An empty field clears it.
  • Status reporting changes the settings files of the agents, and only the entries of Orkestra.