Settings

System settings

Turn on diagnostics and crash report offers, tune the performance guard and terminal history, save and restore the whole system state, manage the license, and read the About pane.

On this page

Purpose

These five Settings panes help you keep Orkestra healthy. Diagnostics controls the local logs and crash report offers. Performance controls when idle terminals sleep and how much terminal history Orkestra keeps. System State saves versions of your whole layout and rolls back to one. License shows the license and can activate a key. About names the app. Use them when something goes wrong, when Orkestra uses too much memory, or when you need to go back to an earlier state.

Where to find it

Click the gear Settings button at the right of the top bar. In the list at the left, click Diagnostics, Performance, System State, License or About. You can also type the pane name in Search settings. The window, the search field and the Reset, Cancel, Apply and OK buttons are in Settings: the window, appearance, terminal, workbench and notifications.

What you see

Diagnostics pane (three groups; the switches, the checkbox and the level buttons are saved with Apply or OK; the two buttons act at once)

Group Debug Mode

  • Enable Debug Mode — off by default. Turn it on to record more detail for troubleshooting; it can slow Orkestra, so leave it off during normal use.
  • Minimum log level — choose Debug, Info (default), Warn or Error. This sets how much detail is recorded outside Debug Mode. Errors and unusual events are always recorded.
  • Capture raw terminal content in Debug Mode (privacy-sensitive) — a checkbox. Off by default. It records terminal text, so it can capture secrets. It has an effect only while Enable Debug Mode is on.

Group Crash reports

  • Offer to send crash reports from a previous session — off by default. When enabled, Orkestra offers a redacted report the next time it starts after a crash. Nothing is sent without your explicit action, and crash files are not read while this is off. See Feedback, errors and notices.

Group Logs

  • Diagnostics are stored locally. Orkestra removes secrets and full paths before recording them; nothing leaves your computer unless you choose to send a report.
  • Open logs folder — a button. It opens the folder with the log files in the file manager of your computer.
  • Export support bundle — a button. While it works, it reads Exporting… and is grey.
  • Saved: <path> — small text. It shows after a successful export. It names the file.
  • session <id> · install <id> — small text at the bottom. It names this run of Orkestra and this installation. Quote both ids when you report a problem.

Performance pane (six groups; all values here are saved with Apply or OK)

Group Performance guard

  • Choose which conditions the guard watches. Idle time can trigger sleep on its own; resource indicators act when the computer or app is under pressure. The idle-hours value is also the minimum idle time for every resource trigger. When a limit is reached, the least recently used eligible terminal sleeps; its window and output stay available, and you can click it to wake it. Current output or a recent working status keeps a terminal awake, but an old working status may be treated as idle. Terminals waiting for your input are never put to sleep.
  • Enable performance guard — a checkbox. On by default. When it is off, no indicator puts a terminal to sleep.
  • Mode — two buttons: Sleep automatically (the default) and Notify only. In Notify only the guard shows a notice and sleeps nothing.

Group Indicators — each row has a switch and a number field. Orkestra takes a number when you leave the field. Orkestra changes a number outside the range to the nearest limit. Text that is not a number returns to the old value. A row keeps its number while its switch is off.

  • Sleep terminals unused for (hours) — on by default; default 24 hours; range 1–720, including decimals. This is also the minimum idle time required before any resource limit can put a terminal to sleep, even if this indicator is off.
  • Max live agent terminals — off by default; default 8; range 1–200 whole terminals. When the count is higher, the guard sleeps the least recently used eligible terminal.
  • Max app memory (MB) — off by default; default 8192 MB; range 256–262144 MB. Counts Orkestra and the full process trees started by terminals.
  • Min system memory available (%) — off by default; default 5%; range 1–99%. Triggers when available system memory falls below the chosen percentage.

Group Offscreen terminals

  • A terminal off screen can pause output processing and keep a smaller live scrollback buffer to save memory. No process is stopped, and output catches up when you bring the terminal back into view.
  • Pause output processing for terminals that are off screen — a checkbox. On by default.
  • Scrollback lines (on screen) — live history kept for a visible terminal; default 5000; range 100–100000. More lines use more memory per terminal.
  • Scrollback lines (off screen) — live history kept for a terminal out of view; default 1500; range 100–100000. Lowering it frees memory immediately but permanently removes the oldest lines. It cannot exceed the on-screen value.

Group Scrollback history

  • Save full terminal history in a local file so you can still read older output after the live scrollback is trimmed. Scroll to the top of a terminal to open its history. Clear or starting a fresh session deletes that terminal's saved history.
  • Keep full scrollback history on disk — a checkbox. On by default.
  • Max history per terminal (MB) — per-terminal disk limit; default 8 MB; range 1–1024 MB. Older history is removed when the limit is exceeded (about 8 MB is 60,000 lines).

Group Current usage (read only)

  • "App + terminals: <n.n> GB memory · <n> processes across <n> terminals · CPU <n>%".
  • "Process usage incomplete for <n> terminal(s)." — shows only when Orkestra could not read some terminals.
  • "System: <n.n> GB of <n.n> GB available".

Group Guard activity (read only)

  • One line per action, newest first, at most 50: the time of day, then Slept "<terminal name>" — <cause>, <reason>, Woke "<terminal name>" or Threshold breached — <reason> (no eligible terminal / notify-only). The cause is "auto", "manual" or "budget". Reason examples are in Feedback, errors and notices.

System State pane — group System state versions (these controls act at once; they do not use Apply)

  • Text: "Snapshots of your whole layout (projects, tasks, workbenches, windows and settings). A snapshot is captured at startup and whenever you create a checkpoint; if your state ever becomes damaged you can roll back to a previous, known-good version. The oldest are pruned automatically."
  • Create checkpoint — a button. While it works, it reads Creating… and is grey.
  • One row for each saved version, newest first. The row title is the date and time, then "·", then the kind: Startup, Checkpoint or Before restore. The line under it reads, for example, "2 projects · 5 terminals · 1 file window · 3.2 KB" (sizes read B, KB or MB).
  • Restore — a button at the right of each row.

License pane — group License (these controls act at once). Rows show only when they have a value.

  • Status — Not activated, Active or Deactivated. Orkestra blocks access only after the license server explicitly deactivates the key; an outage or network error does not lock you out.
  • Key — the saved key in a shortened form. Orkestra never shows the whole key.
  • Plan — the plan name from the license server.
  • Seats in use — shows how many installations currently use this key. It is informational, not a seat limit.
  • Enforcement — off, observe or enforce. This setting comes from the COCKPIT_LICENSE environment variable.
  • Last checked — the time of the last successful contact with the license server.
  • Activate — appears only while Status is Not activated. Enter the license key you were issued, then click Activate. The button is disabled when the field is empty and reads Activating… while it works.
  • Actions — shows in every other case. It has Re-check and Sign out buttons.
  • A red message line under the group shows an activation error.

Access deactivated screen — a box over the whole window, with a bolt icon.

  • Title Access deactivated.
  • A reason text. It is the reason from the license server, or "This license has been deactivated by the operator."
  • Text: "If you believe this is a mistake, contact your administrator, then re-check."
  • Re-check — a button with a refresh icon. The screen has no other button and no close control.

About pane — group About: the name Orkestra and the line "Orchestrate AI coding agents across terminals, worktrees and projects." It shows no version number.

How to

Turn on Debug Mode

  1. Click the gear Settings button at the right of the top bar.
  2. Click Diagnostics in the list at the left.
  3. Click the Enable Debug Mode switch.
  4. Click Apply.

Result: Orkestra records detailed traces at once. It needs no restart.

Turn on crash report offers

  1. Click the gear Settings button at the right of the top bar.
  2. Click Diagnostics in the list at the left.
  3. Click the Offer to send crash reports from a previous session switch.
  4. Click Apply.

Result: after a run that crashed, the next start shows the crash report offer. See Feedback, errors and notices.

Open the logs folder

  1. Click the gear Settings button at the right of the top bar.
  2. Click Diagnostics in the list at the left.
  3. Click Open logs folder.

Result: the file manager of your computer opens the folder with the log files.

Export a support bundle

  1. Click the gear Settings button at the right of the top bar.
  2. Click Diagnostics in the list at the left.
  3. Click Export support bundle.

Result: the button reads Exporting…. Then the line "Saved: <path>" shows, and the file manager shows the new file. The bundle holds the session facts, the counts (not the content) of your saved state, and recent redacted log events.

Change when idle terminals sleep

  1. Click the gear Settings button at the right of the top bar.
  2. Click Performance in the list at the left.
  3. Click the number field in the row Sleep terminals unused for (hours).
  4. Type the number of hours.
  5. Press Tab.
  6. Click Apply.

Result: Orkestra uses the new number for automatic sleep. The idle-sleep button in the Agents panel uses the same number. See Agents panel and agent status.

Make the guard only notify

  1. Click the gear Settings button at the right of the top bar.
  2. Click Performance in the list at the left.
  3. Click Notify only next to Mode.
  4. Click Apply.

Result: when a limit is reached, Orkestra shows a notice and puts no terminal to sleep.

Turn on a resource limit

  1. Click the gear Settings button at the right of the top bar.
  2. Click Performance in the list at the left.
  3. Click the switch in the row Max live agent terminals.
  4. Click the number field in the same row.
  5. Type the limit.
  6. Press Tab.
  7. Click Apply.

Result: when more live agents run than the limit, the guard puts the least recently used eligible terminal to sleep, one terminal at a time. The rows Max app memory (MB) and Min system memory available (%) work the same way.

Change the scrollback lines of terminals on screen

  1. Click the gear Settings button at the right of the top bar.
  2. Click Performance in the list at the left.
  3. Click the number field in the row Scrollback lines (on screen).
  4. Type the number of lines.
  5. Press Tab.
  6. Click Apply.

Result: terminals you look at keep this many lines in the live view. The row Scrollback lines (off screen) works the same way.

Create a checkpoint

Before you start, click Apply or OK for any change you want in the checkpoint. A checkpoint holds only the saved state, not edits that wait in the Settings window.

  1. Click the gear Settings button at the right of the top bar.
  2. Click System State in the list at the left.
  3. Click Create checkpoint.

Result: a new row with the kind Checkpoint shows at the top of the list.

Restore a saved version

  1. Click the gear Settings button at the right of the top bar.
  2. Click System State in the list at the left.
  3. Find the row with the date and time you want.
  4. Click Restore in that row.
  5. Read the dialog "Restore this version?".
  6. Click Restore & restart.

Result: Orkestra saves the present state first, as a version of the kind Before restore. Then it restarts and loads the chosen version. Terminals come back without a running process. See Terminal states, reconnect and history. To change your mind, click Cancel in the dialog. Nothing changes.

Activate a license key

Before you start, look at Status. The Activate row shows only when it reads "Not activated".

  1. Click the gear Settings button at the right of the top bar.
  2. Click License in the list at the left.
  3. Click the License key field in the row Activate.
  4. Type or paste your key.
  5. Click the Activate button.

Result: the field empties, Status reads "Active", and the rows Key, Plan, Seats in use and Last checked can show. A red message shows when the key does not work. See "States and messages".

Re-check the license

  1. Click the gear Settings button at the right of the top bar.
  2. Click License in the list at the left.
  3. Click Re-check in the row Actions.

Result: Orkestra asks the license server again. It shows no message. Last checked shows the new time when the server answered.

Sign out of the license

  1. Click the gear Settings button at the right of the top bar.
  2. Click License in the list at the left.
  3. Click Sign out in the row Actions.

Result: Orkestra removes the saved key from this computer. The rows Key, Plan, Seats in use and Last checked go away. When Enforcement reads "observe" or "enforce", Status reads "Not activated" and the row Activate returns.

Close the Access deactivated screen

Before you start, ask your administrator to reactivate the license.

  1. Click Re-check on the screen Access deactivated.

Result: when the server confirms the reactivation, the screen closes. Your layout is as you left it. If the license is still deactivated, the screen stays and shows no message.

States and messages

  • Diagnostics. Exporting… — the export runs. "Saved: <path>" — the export worked. If the export fails, Orkestra shows no message and no "Saved" line. If the logs folder does not open, Orkestra shows no message.
  • Performance, Current usage. "Measuring current usage…" — the first measurement is not ready. The numbers update while the pane is open.
  • Performance, Guard activity. "No guard actions yet." — the list is empty. The list starts empty at each start of Orkestra.
  • System State. "No saved versions yet." — no snapshot exists. Creating… — a checkpoint is in progress. "Could not create a checkpoint — see Diagnostics for details." — the checkpoint failed. "Restore failed: <reason>" — the restore stopped before the restart; the present state is not changed.
  • License status badge. "Not activated" — no key is accepted yet. "Active" — the app runs. "Deactivated" — the server turned off this license and Enforcement is "enforce".
  • License activation errors (red line under the group):
    • "That key was not recognized by the server."
    • "Saved your key, but the license server could not be reached — it will be verified automatically on the next check." — the key is saved. Status stays "Not activated" until a check reaches the server.
    • "Invalid license activate request" — the key is too long (over 512 bytes).
    • "Activation failed." — a general failure.
  • Access deactivated screen. It shows only when Enforcement is "enforce" and the server reports the license as deactivated. A license that is only "Not activated" never shows it. While the screen shows, the first-run setup and the guided tours do not show.

Limits and tips

  • Save rules differ by pane. Diagnostics and Performance values wait for Apply or OK. The buttons in System State and License, and Open logs folder and Export support bundle, act at once. Reset in the Settings window changes the drafts of Diagnostics and Performance too.
  • Sleeping and off-screen processing are two separate things. Sleep stops a terminal process. Off-screen processing stops no process. Enable performance guard and Mode control only sleep. The checkbox Pause output processing for terminals that are off screen and the Scrollback history group work on their own. See Terminal states, reconnect and history. A terminal you put to sleep by hand uses Sleep in the terminal info menu. See The terminal info menu.
  • The hours value always counts. It is the minimum idle time for every automatic sleep, also when its own switch is off. By default only this indicator is on. The three resource indicators are off.
  • The guard does not sleep everything. The group text says it never touches a terminal that waits for you. A terminal with output now or a fresh working report stays awake. Notices for guard actions are in Feedback, errors and notices.
  • Scrollback. The off-screen value never exceeds the on-screen value. Lowering a limit cuts the oldest lines for good. The find bar searches only the live text. See Terminal windows. The text of Scrollback history says "its History button". A live terminal has no such button. Scroll up past the oldest line to open the history.
  • Debug Mode costs speed. Leave it off for normal use. Do not switch on the raw terminal content capture unless a developer asks for it.
  • Logs stay on your computer unless you click Send on a crash report offer or send a report. Orkestra redacts secrets and absolute paths from the logs.
  • System State keeps the newest 10 versions. Orkestra drops the oldest when a new one is saved. It skips a Startup version when nothing changed since the newest version. A restore changes only the saved Orkestra state, not your project files.
  • License. Enforcement is set outside the app, by an environment variable. When it is not set, Enforcement reads "off". Then Status always reads "Active", no call goes to a license server, Re-check does nothing visible, and the row Activate does not show. Under "observe" Orkestra checks the license but never blocks. Under "enforce" only an explicit deactivation by the server blocks the app. A server outage, a timeout or a wrong key never blocks it. Under "observe" and "enforce", Orkestra checks a saved key at start and then about every 6 hours.