Shell environment

On macOS and Linux, Solo captures your login shell environment so newly launched PTY-backed terminals, commands, and agents receive the captured PATH, version-manager exports, and related variables. On Windows, Solo does not run a login shell; managed PTYs inherit the app environment, while other subprocess paths that request Solo's cached shell map receive a normalized copy.

Desktop apps do not always inherit the same environment as a terminal launched from your shell. Solo compensates by resolving your login shell where available and caching the resulting variables.

This is what makes shell-configured tools and version managers visible to Solo-launched terminals, commands, and other subprocesses.

Capture behavior#

Solo resolves the login shell from, in order:

1. SHELL, when present.
2. The user's passwd entry on Unix.
3. /bin/sh as a fallback.

On Unix-like systems, Solo runs the shell with -ilc env, parses the output, and caches it for 10 minutes. When capture fails, Solo falls back to the app process environment and, on macOS, prepends common Homebrew paths to PATH (/opt/homebrew/bin:/opt/homebrew/sbin on Apple Silicon, /usr/local/bin:/usr/local/sbin on Intel).

Solo also ensures a UTF-8 character type locale when neither LC_ALL nor LC_CTYPE is set and LANG is not already UTF-8.

Windows behavior#

Windows has no interactive-login-shell convention, so Solo does not run a shell to capture environment variables there. PTY-backed terminals, commands, and agents inherit the app's own environment; Solo does not inject its cached normalized shell map into those managed PTYs.

Subprocess paths that do consume Solo's cached shell map start from the app environment, apply the UTF-8 locale fallback described above, and add these Windows-specific fallbacks when the variables are missing:

• HOME is filled from USERPROFILE when USERPROFILE is nonempty.
• SHELL is filled from COMSPEC. If COMSPEC is absent, the cached map falls back to cmd.exe.

Because there is no shell-capture step, changing Windows shell startup files does not require a refresh. Windows child processes begin with the app environment inherited from system and user settings; managed launches can then add Solo identity, terminal-capability, and configured variables.

Processes launched into a WSL distribution are different: they run inside the distribution and pick up its own shell configuration. See Execution profiles for how Solo chooses between Windows shells and WSL distros.

Variables Solo sets#

Solo injects a few reserved variables into each PTY-backed process it manages — commands, interactive terminals, and terminal-backed agents — regardless of whether the process was started from the UI, command palette, MCP, or a restart:

These make it easy for scripts and shell startup files to detect that they're running inside Solo:

if [ -n "$SOLO_PROCESS_ID" ]; then
  # Running inside a Solo-managed session
  export MY_TOOL_QUIET=1
fi

Agents connected to Solo's MCP server also use SOLO_PROCESS_ID to identify their own session.

If PATH or tooling looks wrong#

• Verify the tool works in a normal terminal first.
• Confirm the relevant initialization is in files loaded by an interactive login shell for your shell.
• Run Refresh shell environment from the command palette.
• Restart affected terminals, commands, or terminal-backed agents after changing shell configuration; rerun any affected agent-installation health check.

Changing shell startup files does not update already-running child processes. New processes use the refreshed or next uncached environment.

If the environment looks correct but a Solo command still cannot find a tool, follow the focused PATH troubleshooting guide.