Creating and loading projects

A project in Solo is merely a folder on your disk. Adding a project links that folder to Solo so you can run and manage commands inside it.

Adding a project#

From the sidebar#

If the sidebar is empty, click Add a project. Otherwise, right-click empty space in the sidebar and choose Add project.... A folder picker opens. Navigate to the root of your project or repository and click Open.

Keyboard shortcut#

By default, press Cmd+O on macOS or Ctrl+O on Windows and Linux to open the folder picker directly. You can change or disable this shortcut in Settings > Hotkeys. The Add project shortcut is suspended while that Hotkeys tab is active.

Drag and drop from your file manager#

Drag one or more folders from Finder (macOS) or File Explorer (Windows) onto the sidebar. An Add project overlay appears while you hover; drop to add every dragged folder as a project. Files in the drag are ignored — only folders become projects. If you drop a single folder that's already a project, Solo selects the existing project instead of adding a duplicate.

Open in Solo from Finder (macOS)#

On macOS, Solo registers an Open in Solo item in Finder's Services menu. Select a folder in Finder, then choose Open in Solo from the right-click menu (it may appear under Services) to add that folder as a project — or jump to it if it's already one.

Solo is also registered as a folder handler, so it shows up in Finder's Open With options for folders and can be launched from the terminal:

open -a Solo /path/to/project

Both routes work even when Solo isn't running: the folder is queued and opened once Solo finishes launching. For a newly added project, Solo selects the project and focuses its window. The setup wizard appears if command detection finds suggestions for that new project.

The setup wizard#

After you pick a folder, Solo checks whether the same canonical folder is already in its project list. If it is, Solo reuses that project and does not run setup again.

For new folders without a solo.yml, Solo scans for known project structures and opens a setup wizard when it finds suggestions. The wizard:

1. Detects commands — Solo looks for files such as package.json, composer.json, Cargo.toml, requirements.txt, pyproject.toml, Gemfile, go.mod, .csproj files, mix.exs, pom.xml / build.gradle, Procfile / Procfile.dev, Docker Compose files, PM2 config, Turborepo/Nx workspace configs, and Taskfile/Justfile/Makefile targets. Suggestions that look like active development processes are usually pre-selected.

2. Lets you review and adjust — You can choose which detected commands to include and whether each one starts automatically. After onboarding, you can add, edit, or rename commands from the project pane.

3. Asks where to save — You can save the detected commands to:

   • A solo.yml file in the project root (recommended — you can commit it to version control).
   • Locally in Solo (keeps your repo clean, but teammates won't benefit).

See solo.yml overview for details on the file format.

If the folder already has a solo.yml, Solo loads that file instead of showing detection suggestions. Commands loaded from an existing solo.yml require trust review before they run.

After adding#

Once you confirm, the project appears in the sidebar with its commands listed. Commands do not run until you start them or use the project action to start commands marked as auto-start. The setup wizard also has a separate project auto-start setting that controls whether Solo starts auto-start commands for that project when appropriate.

Loading projects at startup#

Solo restores all projects and their settings on every launch. You don't need to re-add projects. If a project folder has been moved or deleted, Solo removes the stale entry at startup and shows a notification. If you moved a folder and want to retain its existing project entry and most settings, point the project at the new path with Edit directory (see below) while Solo is still running, before relaunching. Changing the path resets stored environment-root mappings and may clear an incompatible manually selected WSL execution profile.

Changing a project's directory#

If you move or rename a project folder on disk, you can point the existing project at the new location instead of removing and re-adding it:

1. Open the project from the sidebar with Edit project....
2. Find the Directory row and click the Edit directory pencil icon.
3. Type the new path, or use the folder button to pick it, then save.

The new path must exist, must be a directory, and can't already belong to another project. Commands that are already running keep their old working directory until you restart them — Solo reminds you of this when commands are running.

Removing a project#

Right-click the project name in the sidebar and choose Remove project. This removes the project from Solo's list and stops/removes its Solo-managed processes. It doesn't delete any files — your solo.yml and all your code remain intact.

Multiple projects#

You can have as many projects open simultaneously as you want. Each project runs its commands independently. The free tier supports up to four primary projects; linked-checkout project entries do not count toward that quota.

Tips#

• Point Solo at the root of your repo, not a subdirectory. Commands use the project root as their working directory by default, unless the command defines a working_dir override.
• For monorepos, adding the monorepo root works well — you can add commands for each workspace package with paths like pnpm --filter @my/app dev.
• If auto-detection misses something, skip or finish the wizard, then use Add command in the project pane or sidebar.