# Execution profiles

An execution profile decides which shell — and, on Windows, which environment — Solo uses for a project's commands and agents, and for terminals that inherit the project profile. A shell chosen explicitly when creating a terminal overrides the profile for that terminal. Every project resolves to exactly one profile, either inherited from a global default, auto-detected from the project path, or chosen manually.

## What a profile controls

When Solo starts an interactive terminal that inherits the project profile, runs a command, or launches an agent for a project, it uses the project's resolved execution profile to decide:

- Which shell program runs the session (`zsh`, `bash`, PowerShell, `cmd.exe`, and so on).
- On Windows, whether the process runs on the Windows host or inside a WSL distribution.

On macOS and Linux, a profile is essentially a shell choice, so the UI labels it **Shell**. On Windows, profiles also select between separate environments (Windows host vs. WSL distros), so the UI labels it **Execution profile**.

## Available profiles

Solo detects installed shells automatically and always includes a **System default** profile that follows your login shell (on Windows, the system `COMSPEC` shell, usually Command Prompt).

| Platform | Detected profiles |
|----------|-------------------|
| macOS / Linux | System default, plus Zsh, Bash, Fish, and sh when installed |
| Windows | System default, Command Prompt, plus PowerShell 7, Windows PowerShell, and Git Bash when found, a WSL default profile, and one profile per installed WSL distribution |

WSL distribution profiles use ids of the form `wsl:<distro>` (for example `wsl:Ubuntu`) and run everything inside that distribution via `wsl.exe --distribution <distro>`.

You can also add your own shells — see [Custom shell commands](#custom-shell-commands).

## The default execution profile

Open **Settings** (by default, `Cmd+,` on macOS or `Ctrl+,` on Windows and Linux; the shortcut can be changed or disabled under **Hotkeys**) and go to the **Terminal** tab. The **Default shell** setting (labeled **Default execution profile** on Windows) chooses the profile for new projects and for any project set to inherit the default.

- The first option is **System default**, shown with the command line it resolves to.
- Hidden or unavailable profiles are marked `(hidden)` and `(unavailable)` in the dropdown; unavailable profiles are disabled unless one is already your current default.
- Per-project overrides always take precedence over this setting.

On Windows, a WSL profile set as the global default does not carry over to projects stored on Windows drives — those projects fall back to the system default. Projects that live inside a WSL distribution are auto-detected instead (see below).

## Per-project profiles

Each project has a **Shell** (or **Execution profile**) row in its project settings, next to [Auto Start](../commands/auto-start.md) and the [editor override](../settings/tools-editors-terminals.md). The dropdown offers **Inherit default shell** (**Inherit default or auto-detect** on Windows) plus every visible profile. Unavailable profiles are listed but disabled unless they are the project's current selection.

A badge next to the control shows where the current profile came from:

| Badge | Meaning |
|-------|---------|
| **Inherited** | The project uses the default execution profile from Settings |
| **Auto** | Solo detected the profile from the project path |
| **Manual** | You picked the profile for this project |

### Auto-detection for WSL projects

On Windows, a project whose path lives inside a WSL distribution (a `\\wsl.localhost\<distro>\...` or `\\wsl$\<distro>\...` path) is automatically assigned that distribution's `wsl:<distro>` profile when it's added. You can still override it manually.

### Profile badges on projects

The project header shows a compact profile badge when the resolved profile is a Windows host shell or a WSL distribution — for example `WSL: Ubuntu`, `Git Bash`, or `PowerShell`. Local shell profiles are not badged, so the common case stays quiet. An unavailable profile is always badged, whatever its kind.

## Unavailable profiles

A profile becomes unavailable when its shell can't be found — an uninstalled WSL distribution, a removed custom shell, or a shell that no longer exists on `PATH`. When a project's selected profile is unavailable:

- The project shows an amber **Unavailable** warning badge.
- The project settings row explains which profile is unavailable.
- The selection is preserved rather than silently replaced, so reinstalling the shell (or picking a different profile) fixes it.

## Shell profiles in launch menus

Below the default setting, the **Shell profiles** section of the Terminal tab lists every detected shell and any custom shells you've added. Each row has a visibility toggle that controls whether the shell appears in launch menus — for example the shell choices offered when creating a [new terminal](../command-palette/new-tab-picker.md) from the [command palette](../command-palette/using.md).

Rows are also labeled with badges:

- **Default** — the shell backing the current default execution profile.
- **Unavailable** — the shell's command can't be found right now.
- **Custom** — a shell command you added yourself.

## Custom shell commands

To add your own shell, use the form at the bottom of the **Shell profiles** section: enter a name and a command (arguments are allowed, for example `bash --login`), then click **Add**.

Custom shells:

- Appear in launch menus and as selectable execution profiles.
- Run in the host environment for your platform (they can't target a WSL distribution).
- Can be edited or deleted from their row — built-in detected shells can only be hidden, not removed.

## Configuring a WSL root

A WSL distribution can't use a Windows host path like `C:\Users\me\repo` directly — it needs a Linux path inside the distribution. If you assign a WSL profile to a project stored on a Windows drive, Solo opens a **Configure WSL root** dialog asking where the project lives inside the distribution.

The dialog pre-fills the drive's mount path (for example `/mnt/c/Users/me/repo`). You can:

- Keep the suggested mount path (if you've edited it, **Use mount path** restores the suggestion).
- Enter a different path inside the distribution — useful when the repository is cloned natively in WSL at another path.

Click **Save WSL root** to store the root and apply the profile. From then on, commands, agents, and terminals that inherit the project profile run inside the distribution at the configured path. A terminal created with an explicitly selected shell keeps that direct shell override.

## Related pages

- [Shell environment](./shell-environment.md) — how Solo captures `PATH` and other variables for the shells it launches.
- [Version managers](./version-managers.md) — making `nvm`, `asdf`, and friends visible to Solo.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/environment/execution-profiles