# 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](./version-managers.md) 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](./execution-profiles.md) 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:

| Variable | Value |
|----------|-------|
| `SOLO_PROCESS_ID` | The Solo-managed process ID for this session. This is Solo's own identifier, not the operating system PID. |
| `SOLO_PROJECT_ID` | The ID of the project the process belongs to. |
| `SOLO_PROCESS_KIND` | What kind of process this is, such as `command`, `terminal`, or `agent`. |

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

```bash
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](../integrations/mcp-server.md) 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](../command-palette/using.md).
- 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](../troubleshooting/path-issues.md).

---

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