On macOS and other Unix-like hosts, Solo works with shell-configured version managers by capturing your login shell environment. If that shell adds a version manager to PATH, an explicit shell-environment refresh makes the updated shims and exported variables available to newly launched Solo processes. Processes that are already running keep the environment they started with.
This works best for tools that initialize from your shell startup files, including asdf, mise, pyenv, Ruby managers, Homebrew-installed language tools, and virtualenv tooling initialized by your shell.
What Solo captures
On Unix-like hosts, Solo runs your resolved shell as an interactive login shell and captures the environment it exports. Version-manager setup therefore needs to live in a startup file that shell actually loads.
Solo caches that environment for 10 minutes. Refresh shell environment in the command palette recomputes and replaces the cache immediately. Otherwise, the next request after the cache becomes stale recomputes it; expiry by itself does not update the cache or any running process. Later Unix-host launches receive the recomputed values.
Windows-host processes follow a different path: Solo does not capture an interactive login shell or inject its normalized shell-environment cache into managed Windows PTYs. Make the required paths and variables available in the system or user environment that launches Solo, then relaunch Solo after changing them. The refresh command does not import Windows shell startup files. WSL profiles use the distribution's own shell environment, so configure the version manager inside that distribution.
Troubleshooting
If a managed runtime isn't found in Solo:
- Confirm it works in a normal terminal in the same host or WSL environment first.
- On Unix-like hosts, make sure the init code is in a startup file loaded by your interactive login shell. In WSL, put it in the distribution's shell configuration.
- On Unix-like hosts, run Refresh shell environment, or wait until the cache is stale and start a process that requests it. On Windows hosts, update the system or user environment and relaunch Solo instead.
- Start or restart the affected process after the environment has been updated. Existing processes do not receive later changes.
For nvm in a Unix-like or WSL environment, make sure your shell startup files export the paths needed for non-interactive command launches. If nvm only exists as a shell function in your interactive session, Solo may not be able to use it for managed commands.
For a step-by-step comparison of your normal shell and Solo's captured environment, see Commands can't find tools (PATH issues).