# Agent installation health Solo checks whether each agent tool's CLI is actually installed and working, and shows the result in **[Settings → Agents](./setting-up-tools.md)**. Health helps decide which agents are offered for launch. The installation rows show CLI health details, while project and execution-profile settings cover environment mismatches and invalid project roots. ## Health statuses Every agent tool has an installation record per environment it can run in. Each record carries one of four statuses: | Status | Meaning | Launchable? | |--------|---------|-------------| | **Ready** | The CLI was found and responded to a version check. | Yes | | **Not checked** | Solo hasn't checked this installation yet, or the last check timed out before finishing. | Yes | | **Missing** | The CLI was not found on `PATH` in that environment. | No | | **Broken** | The CLI was found but its version check failed, or the environment itself couldn't be checked. | No | Two things to note: - **Not checked** installations stay launchable. Solo only blocks an agent once a check has actually proven something is wrong, so a slow or never-run check won't lock you out. Timed-out checks are treated as inconclusive and stay **Not checked** rather than turning **Broken**. - **Missing** and **Broken** installations are hidden from agent launch menus until a re-check succeeds. A globally disabled tool is marked **Hidden**. Its default host installation also shows **Disabled**; a separately enabled WSL installation can continue to show its stored health status, but the global switch still prevents the tool from launching. ## What a check does For each tool and environment, Solo runs the tool's command with `--version` and classifies the result: - On macOS and Linux, the check runs through your shell — the shell backing your default [execution profile](../environment/execution-profiles.md), or your login shell — so the result matches what a Solo terminal would see. If a tool works in your terminal but shows **Missing**, see [Shell environment](../environment/shell-environment.md). - On Windows, the check runs on the Windows host through your configured shell, plus inside each WSL distribution (see below). When a check succeeds, the tool's row can show: - **Detected version** — the version string when the CLI reports a non-empty version line. A row can still be **Ready** without one. - **Config path** — the tool's configuration directory or file, when Solo finds one (for example Claude's config folder in your home directory). When a check fails, the row carries a health message explaining what happened — for example that the command wasn't found on `PATH`, or that it was found but exited with an error. If a failed CLI invocation produces output, the message includes a bounded excerpt. Spawn, timeout, missing-command, and unavailable-environment failures may have no CLI output to include. ## Re-checking Health checks only run when you ask for them. Click **Refresh health** in the **Agent tools** header to re-check every tool in every environment. Checks run concurrently, so one slow tool doesn't hold up the rest. Refreshing health also re-checks each agent's [Solo MCP connection status](../integrations/mcp-server.md). Typical flow after installing a new CLI: install it in your terminal, then click **Refresh health**. Once the row turns **Ready**, the agent appears in launch menus. ## Environments on Windows On macOS and Linux there is a single local environment. On Windows, agent CLIs can be installed in more than one place, so Solo tracks each environment separately: - **Windows** — the Windows host itself. - **WSL: \** — each installed WSL distribution. Service distributions (like Docker Desktop's internal distros) are skipped. Environment tabs above the tool list let you switch between environments. Their badges summarize verified installation health, which is not quite the same as launchability because **Not checked** installations remain launchable: | Badge | Meaning | |-------|---------| | **Ready** | At least one enabled installation has verified **Ready** health. | | **Needs check** | No installation is verified **Ready**, and all enabled installation issues are **Not checked**. Those unchecked tools can still launch. | | **Needs repair** | No installation is verified **Ready**, and at least one enabled installation is **Broken**. A different **Not checked** installation may still launch. | | **Missing** | No installation is verified **Ready**, and at least one enabled installation is **Missing**. A different **Not checked** installation may still launch. | | **Needs install** | Every issue in the environment is for a tool without an installation. | | **No ready tools** | The environment has another mixed or disabled non-ready state. | A few Windows-specific behaviors: - Checking a WSL distribution may have to boot it first, so WSL checks can take noticeably longer than host checks. - Built-in first-party tools are checked in every detected WSL distribution automatically. Custom tools get host installation records by default; if a custom tool already has a WSL installation record, **Refresh health** rechecks that installation too. - A stopped but still registered WSL distribution may be booted and checked. Its installations show **Broken** as unavailable when the distribution is no longer discovered, or when WSL discovery itself fails. - When a tool is missing from the selected environment and Solo has an install URL for that tool type, its row offers an **Install in \** link. Amp and Generic tools do not currently have this link. ## Runtime doctor At the top of the **Agent tools** section, the **Runtime Doctor** panel summarizes launch readiness across every runtime target — one tool in one environment — as "N of M runtime targets can launch." A target is launchable when all of these hold: - The tool is enabled. - The installation for that environment is enabled. - Health is **Ready** or **Not checked**. - When evaluated against a specific project, the environment matches that project's execution profile. - When evaluated against a matching WSL project profile, the project's environment root inside that distribution is configured and usable. Runtime Doctor displays only the aggregate launchable count; it does not expand the reason or repair action for each target. Use the installation row and the relevant project or execution-profile settings to troubleshoot a lower count: | Condition to check | What it means | How to fix it | |--------------------|---------------|---------------| | Tool disabled | The tool is hidden from agent creation UIs. | Turn the tool's toggle back on. | | Installation disabled | The tool is switched off for that environment. | Enable the installation. | | CLI missing | The command wasn't found on `PATH` in that environment. | Install the CLI there, then **Refresh health**. | | CLI broken | The command's check failed, or the environment or shell itself could not be checked. | Read the health message, fix the underlying problem, then **Refresh health**. | | Not checked | Solo hasn't verified this installation yet. | **Refresh health** (the agent can still launch in the meantime). | | Environment mismatch | The installation targets one environment (say, Windows) but the selected project runs in another (say, WSL). | Switch the project's [execution profile](../environment/execution-profiles.md), or install the tool in the project's environment. | | Invalid environment root | The project uses a WSL profile but its path inside the distribution isn't configured or usable. | Configure the project's environment root — see [Execution profiles](../environment/execution-profiles.md). | MCP setup — whether the agent is connected to Solo's tools — is checked separately and doesn't affect launchability. ## How health affects launching When you launch an agent in a project (see [Launching agents](./launching-agents.md)), Solo only offers tools that are enabled and launchable in that project's environment. A tool that is **Ready** on the Windows host but **Missing** in the project's WSL distribution won't appear for that project until you install it inside the distribution. --- Are you a human? Read this doc on the web: https://soloterm.com/docs/agents/installation-health