Start here

System check

See whether this computer is ready to run Orkestra and your coding agents, and install, sign in or fix what is missing.

On this page

Orkestra starts coding agents as programs on your computer. The System check shows, in one list, if each agent program is installed and signed in, and if the tools around it work: Git, the terminal engine, secure storage and more. Use it when an agent does not start, when you set up a new computer, or to install and sign in to an agent.

The check only reads. Orkestra installs nothing unless you press Enter in the setup terminal yourself.

Where to find it

  1. Click the gear Settings button at the right of the top bar.
  2. Click System check in the list at the left of the Settings window.

Other places open the same pane:

  • The Open System check button on the "An agent is ready" item of the Getting started checklist. See Getting started.
  • The Open System check button on the "Terminal engine not available" card of a terminal. See Starting terminals and agents.

The first-run setup wizard shows the same report as its first step. See Getting started.

What you see

The report (top of the pane)

  • System check — the title. Under it: "Orkestra checks the agent CLIs and the system tools it needs. Nothing is installed without your action."
  • Age text — at the right. It reads "Not checked yet", "Checking", "Checked just now", "Checked 12 s ago", "Checked 3 min ago", "Checked 2 h ago" or "Checked 1 d ago". The text counts up each second.
  • Re-check — a button with a refresh icon. The icon spins and the button is off while a check runs.
  • Warning note — shown only when the check or a link fails. See States and messages.
  • Agents — the list of agent rows, in this order: Claude Code, Codex, Cursor, OpenCode, Antigravity.
  • System — the list of system rows, in this order: Login shell PATH, Git, Terminal engine, Secure storage, Data folder, Node.js, npm.

One row, from left to right

  • Status dot — green is good, amber is a warning or "could not tell", red is missing or failed, grey and pulsing is "checking".
  • Agent logo — a small chip. Only agent rows have it.
  • Name and state word — for example "Claude Code" and "Ready". The state word has the colour of the dot.
  • Version — agent rows only. It shows the version number only. Hover to see the full text.
  • Detail — the path of the program, or a short sentence. A path shows your home folder as "~". A long path is cut in the middle. Hover to see the full path, or a longer explanation.
  • Fix line — a line that starts with Fix:. Only the Terminal engine row has it.
  • Sign-in chip — agent rows only: Signed in, Signed out or Not checked.
  • Buttons — Install, Sign in, Open settings, Install guide, Open guide or Re-check. A button with an arrow icon opens a web page in your browser.

Below the report

  • Setup — the row "Run setup again" with the button Run setup.
  • Getting started — the row "Show checklist again" with the button Show checklist.
  • Tours — the text "Short guided tours of the main surfaces", then one row per tour. Each row has a chip (Seen or Not started) and a button (Replay or Start).

These three groups are hidden while the setup panel is open.

The setup panel (replaces the report)

  • System check — a back button with a left arrow, top left.
  • Title — "Install Claude Code" or "Sign in to Codex" (the agent name changes).
  • Command row — the command in a monospace font and an icon button with the tooltip "Copy command".
  • Terminal box — a real shell with the command already typed after the prompt.
  • Note or hint — a short message under the terminal.
  • Close and Re-check — buttons at the bottom.

How to

Open the System check

  1. Click the gear Settings button at the right of the top bar.
  2. Click System check in the list at the left.

Result: the report opens. A check starts at once if there is no report yet, or if the last report is older than one minute. A newer report shows as it is, with its age.

Re-check the computer

  1. Open System check in Settings.
  2. Click Re-check at the top right of the report.

Result: the age text reads "Checking", then "Checked just now". Every row shows its new state.

Install an agent

Before you start, find an agent row with the state word "Not installed".

  1. Open System check in Settings.
  2. Click Install in the row of the agent.
  3. Read the command in the command row.
  4. Press Enter in the terminal box.
  5. Wait until the command ends.
  6. Click Re-check at the bottom of the panel.
  7. Click Close.

Result: a green note shows "<Agent> <version> is ready.", with your agent name and its version. Close is now the main button. After you close the panel, the report shows the agent as "Ready".

If the row has no Install button, click Install guide instead. See "Open a vendor guide".

Copy a command to run it yourself

  1. Click Install (or Sign in) in an agent row.
  2. Click the icon button with the tooltip "Copy command" at the end of the command row.

Result: the command is on your clipboard. The tooltip reads "Copied" for about 1.5 seconds.

Sign in to an agent

Before you start, find an agent row with the chip Signed out.

  1. Open System check in Settings.
  2. Click Sign in in the row of the agent.
  3. Press Enter in the terminal box.
  4. Follow the questions the agent program prints in the terminal.
  5. Click Re-check at the bottom of the panel.
  6. Click Close.

Result: a green note shows "<Agent> is signed in.", with your agent name. The row shows the chip Signed in.

Open a vendor guide

  1. Click Install guide (or Open guide) in a row.

Result: the vendor page opens in your browser. If it does not open, a warning note shows "The link could not be opened."

Set a program path or a PATH folder

  1. Click Open settings in a row.

Result: the Settings window moves to the Engines pane. Set the program path or add a folder there. See Settings: task defaults and engines.

Re-check after a row could not be checked

  1. Click Re-check in the row of an agent that shows "Could not check" or "Error".

Result: the whole report runs again, the same as the header Re-check.

Run setup, show the checklist or start a tour

  1. Click Run setup, Show checklist, Start or Replay in the groups below the report.

Result: the first-run setup, the Getting started checklist or the tour opens. A tour and the checklist appear after you close Settings. The steps are in First-run setup, Getting started and tours.

Leave the setup panel

  1. Click Close at the bottom of the panel.

Result: the report returns at the same scroll position. The terminal ends, and one new check runs by itself. The System check back button at the top of the panel does the same.

States and messages

Agent rows

  • Ready means Orkestra found a program it can launch. The chip also shows whether sign-in was detected: Signed in, Signed out or Not checked. Only Claude Code, Codex and Cursor provide a readable sign-in state; Not checked for OpenCode or Antigravity does not mean signed out.
  • Not installed means the program is missing or its saved path is invalid. Use Install, Install guide or Open settings, depending on the row.
  • Could not check means Orkestra could not determine the state, for example because the login-shell PATH is unavailable, a Windows command shim cannot be inspected, or the version command timed out (5 seconds). Error means the program failed to start or returned an error. Use Re-check after addressing the cause.
  • If the sign-in probe times out or returns an unreadable result, the program may still be launchable. The row remains Ready with an amber or red dot and offers Re-check.

System rows

  • Login shell PATH — Captured means Orkestra read the PATH from your login shell. Unknown means agents installed only for that shell may appear missing; restart Orkestra after fixing the shell or PATH.
  • Git — Found, Missing, Error or Unknown reports whether Git answered successfully. Install guide appears when Git is missing.
  • Terminal engine — Loaded means terminals can start. If it shows Error or Unknown, follow the Fix: guidance and restart Orkestra. A missing system library may require an OS update or a compatible Orkestra build; a blocked or damaged engine may need its permissions fixed or Orkestra reinstalled.
  • Secure storage — Available means the system keyring is ready. No keyring means saved secrets are stored without encryption; on Linux, install and unlock a keyring such as GNOME Keyring or KWallet.
  • Data folder — Writable means Orkestra can store its projects and settings. Error or Unknown includes the folder and the system reason.
  • Node.js and npm show their versions when found. Missing identifies which one an install command needs; Unknown or Error means Orkestra could not check it. Use Install guide or Open settings when offered.
  • During the first check, rows show Checking. If an internal check fails or exceeds 25 seconds, the row is Could not check (agents) or Unknown (system).

Other messages

  • An amber warning above the report means the check or a vendor link could not complete. The last good report stays visible when a check fails; click Re-check to try again.
  • In the setup panel, press Enter in the terminal to run the suggested command, then click Re-check. If no command is available, use Open install guide. If the terminal engine is unavailable, copy the command and run it in your own terminal.
  • A green note confirms the agent was installed or signed in. Seen in the Tours list means the first callout appeared; otherwise the tour is Not started. Automatic tours are unavailable on a computer where first-run setup was not run, but Start and Replay still work.

Limits and tips

  • The check does not change anything. Nothing here is a setting, so this pane never changes the Settings draft.
  • Orkestra looks for an agent the same way a terminal launch does. "Ready" means a launch can start the program. A program path you set in Engines counts. See Settings: task defaults and engines.
  • Sign-in is read with one read-only command, and only for Claude Code, Codex and Cursor. For OpenCode and Antigravity the chip stays Not checked.
  • The report is not saved. It is a reading of this computer for this session. A check takes up to 25 seconds in total.
  • The setup terminal is a plain shell in your home folder. It is not a window on the canvas and is not saved. It ends when you leave the panel, close Settings or switch to another Settings pane.
  • Orkestra types the command after the prompt. It does not press Enter. You decide when it runs.
  • Each way out of the setup panel starts one new check, so the report is current when you return.
  • The Install button shows only when Orkestra has an install command for your system. On Windows, Cursor, OpenCode and Antigravity have only Install guide.
  • Settings is a modal window. A tour or the checklist you request here starts only after you close Settings.