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).

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.

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 and the editor override. 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:

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 from the command palette.

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 — how Solo captures PATH and other variables for the shells it launches.
• Version managers — making nvm, asdf, and friends visible to Solo.