Help

Solo automatically inherits your shell environment when launching processes, including your PATH and any variables set by version managers like nvm, asdf, or RVM.

You can also define custom environment variables per-process in your solo.yml file. These will override any inherited variables with the same name.

Example

name: My Project
processes:
  Server:
    command: node server.js
    auto_start: true
    env:
      NODE_ENV: production
      PORT: 3000
      DATABASE_URL: postgresql://localhost/mydb

  Worker:
    command: php artisan queue:work
    auto_start: true
    env:
      QUEUE_CONNECTION: redis

How it works

When a process starts, environment variables are applied in this order:

1. Shell environment — Your full login shell environment is captured, including PATH, HOME, and version manager paths.
2. Terminal variables — Solo sets TERM=xterm-256color, FORCE_COLOR=1, and terminal dimensions automatically.
3. Your custom env vars — Variables from solo.yml are applied last, so they can override anything above.

Tips

• You don't need to set PATH or shell-related variables — Solo picks these up from your login shell automatically.
• If a process can't find a command, make sure the tool is available in your regular terminal first.
• Solo does not load .env files directly. If your framework needs a .env file, it will load it itself as usual (e.g. Laravel, Node with dotenv).

Solo captures your full shell environment — including PATH — by running your login shell (e.g. /bin/zsh -ilc env) when the app starts. This means it picks up everything from your .zshrc, .bashrc, and any version managers like nvm, asdf, or RVM.

This environment is cached for 10 minutes so processes start quickly. If you've recently installed a new tool or changed your shell config, Solo might still be using the old environment.

Force a refresh

Open the quick action palette with Cmd/Ctrl+K and search for "Refresh shell environment". This will re-capture your shell environment immediately, picking up any changes to your PATH or other variables.

After refreshing, restart the affected process for the changes to take effect.

Debugging

Under the hood, Solo runs $SHELL -ilc env to capture your environment. You can run the same command in your terminal to see exactly what Solo sees:

$SHELL -ilc env

If a variable or PATH entry is missing from that output, it won't be available in Solo either. Fix it in your shell profile and it will be picked up on the next refresh.

Still not working?

• Make sure the command works in a new terminal window (not just an existing one).
• Check that the tool is set up in your shell profile (~/.zshrc or ~/.bashrc), not just exported in a running session.
• If you use a non-standard shell location, Solo may not detect it. Reach out and we can help.

Use the restart_when_changed option in your solo.yml to automatically restart a process when specific files are modified or created.

Example

processes:
  Queue:
    command: php artisan queue:work
    auto_start: true
    auto_restart: true
    restart_when_changed:
      - app/Jobs/**/*.php
      - config/queue.php

Patterns use glob syntax relative to your project root. Some common examples:

• src/**/*.ts — Any TypeScript file under src/
• config/*.php — PHP files in the config directory
• *.env — Any .env file in the project

Solo debounces file changes, so saving multiple files in quick succession will only trigger a single restart about 500ms after the last change.

You can also configure file watching from the process settings panel in the app without editing solo.yml directly.

Global

• Cmd/Ctrl+K — Open the command palette
• Cmd/Ctrl+, — Open settings
• Cmd/Ctrl+1-9 — Jump to a project or process by position
• Ctrl+\ — Toggle focus between sidebar and terminal

Sidebar — project focused

When a project header is selected in the sidebar:

• S — Start all auto-start processes
• A — Start all processes
• P — Stop all processes
• R — Restart all running processes
• Arrow keys — Navigate and expand/collapse

Sidebar — process focused

When a process is selected in the sidebar, these single-key shortcuts work without any modifier:

• S — Start or stop the process
• R — Restart the process
• C — Clear the process output
• Arrow keys — Navigate between items

Command palette

• Arrow Up/Down — Navigate results
• Enter — Execute selected action
• Cmd/Ctrl+1-9 — Quick execute a result by position
• Escape — Close

The solo.yml file lives at your project root and defines your processes and project settings. Solo watches this file for changes and syncs automatically.

Full example

name: My Project
icon: public/favicon.png
processes:
  Server:
    command: php artisan serve
    working_dir: null
    auto_start: true
    auto_restart: false
    restart_when_changed: []
    env: {}

  Queue:
    command: php artisan queue:work
    auto_start: true
    auto_restart: true
    restart_when_changed:
      - app/Jobs/**/*.php
      - config/queue.php
    env:
      QUEUE_CONNECTION: redis

  Frontend:
    command: npm run dev
    auto_start: true

Project settings

• name — Display name in Solo. Defaults to the folder name if omitted.
• icon — Path to a project icon (relative to project root). Supports png, jpg, gif, ico, and webp.

Process options

• command — Required. The shell command to run.
• working_dir — Working directory relative to the project root. Defaults to the project root.
• auto_start — Start automatically when the project opens. Defaults to true.
• auto_restart — Automatically restart if the process exits. Defaults to false.
• restart_when_changed — Glob patterns for file watching. Process restarts when matching files change.
• env — Custom environment variables as key-value pairs.

You can also configure all of these options from the process settings panel in the app. Changes made in the app are written back to solo.yml.

Solo supports light, dark, and system themes. The system option follows your OS preference automatically.

You can switch themes in two ways:

• Open Settings (Cmd/Ctrl+,) and choose your theme under Appearance.
• Open the command palette (Cmd/Ctrl+K) and search for "light theme", "dark theme", or "system theme".

Solo watches your solo.yml file for changes and will prompt you to sync when it detects a modification. Look for the sync banner at the top of the sidebar — click it to apply the new config.

Syncing will add any new processes, update changed settings, and remove processes that are no longer in the file. Running processes are not interrupted unless their configuration changed.

Changes made through the Solo UI (like toggling auto-start or adding file watch patterns) are written back to solo.yml automatically — no manual sync needed.

Solo requires you to trust a process before it can run. This is a security measure to prevent unknown commands from executing automatically when you open a project.

When new processes are synced from solo.yml, Solo will ask you to review and trust each command before it can be started. Once trusted, a process stays trusted until its command changes. Processes added through the Solo UI are trusted automatically.

This also applies to auto-restart and file-watch restarts — untrusted processes won't be restarted automatically, even if auto_restart or restart_when_changed is configured.

If Solo quits unexpectedly (crash, force quit, etc.), your processes may continue running in the background. The next time you open Solo, it will detect these orphaned processes and show a dialog asking what you'd like to do.

You can either stop all orphaned processes or dismiss the dialog to let Solo adopt them. Adopted processes will appear as running in the sidebar and can be stopped or restarted normally, though their previous output won't be available.

When Solo shuts down normally, it gracefully stops all running processes before exiting.

Solo sends notifications when a process crashes (exits with a non-zero exit code). If the app is in the background, you'll get a native desktop notification. If the app is in the foreground, you'll see an in-app toast instead.

Clicking a native notification will bring Solo to the front and navigate to the crashed process.

Terminal notifications

Processes can also trigger notifications through terminal escape sequences (OSC 9, OSC 777, OSC 99). Some tools use these to notify when long-running tasks complete. These are routed intelligently — if you're already viewing that process, the notification is suppressed.

Configuration

• App notifications (crash alerts) can be toggled per-project from the project settings.
• Terminal notifications can be toggled per-process from the process settings.

Open the command palette with Cmd/Ctrl+K and choose "Add project", or use Cmd/Ctrl+O. Select your project folder and Solo will add it to the sidebar.

If your project already has a solo.yml file, Solo will sync its processes automatically. Otherwise, Solo will detect your project type (Laravel, Node.js, Rails, Go, Python, Rust, etc.) and suggest processes for you.

New projects appear at the top of the sidebar. You can reorder them anytime from the Projects > Reorder Projects menu.

You can add a process two ways:

• In the app — Open the command palette (Cmd/Ctrl+K), search for your project, and select "Add new process". Processes added through the UI are trusted automatically.
• In solo.yml — Add a new entry under processes: in your solo.yml file. Solo will detect the change and ask you to sync. Processes added from YAML need to be trusted before they can run.

Processes can be stored in two places:

• In solo.yml — Part of your project config file. Can be version-controlled and shared with your team.
• Local only — Stored locally by Solo. Only exists on your machine, not in your project files.

When you add a process through the UI, you can choose whether to save it to solo.yml. You can also move a process between local and yml at any time from the process settings.

If solo.yml is deleted externally, Solo converts all yml processes to local-only so nothing is lost.

Auto-start works at two levels:

• Project-level — Controls whether the project's processes start when Solo opens. You can enable or disable a project from the command palette or context menu.
• Process-level — Controls whether an individual process is included in the auto-start batch. Set auto_start: true in solo.yml or toggle it in the process settings.

When Solo launches, it starts processes where both the project and the process have auto-start enabled (and the process is trusted).

The command palette offers both "Start auto-start processes" (respects per-process auto-start settings) and "Start all processes" (starts everything that's trusted, regardless of auto-start).

When auto_restart: true is set on a process, Solo will automatically restart it if it exits. This is useful for long-running services like queue workers or WebSocket servers that should stay alive.

processes:
  Queue:
    command: php artisan queue:work
    auto_restart: true

Auto-restart defaults to false. You can toggle it per-process in solo.yml or from the process settings panel.

Solo includes a built-in MCP server (Model Context Protocol) that lets AI coding tools manage your processes. Enable it in Settings > Integrations > MCP Server.

Once enabled, AI tools can list projects, start/stop/restart processes, read process output, search logs, check ports, and monitor resource usage — all through the MCP protocol. For the bigger picture, see how Solo works as an AI agent workspace.

Setup

The MCP server runs on localhost:45678 by default. Add it to your AI tool:

# Claude Code
claude mcp add solo --transport http --scope user http://localhost:45678/

# Amp
amp mcp add solo http://localhost:45678/

Setup commands for other tools (Cursor, Windsurf, Codex, Claude Desktop) are shown in Settings after enabling the MCP server.

If you're comparing agent workflows, see Solo vs Cursor, Solo vs Windsurf, or Solo vs Warp.

Yes. Solo has a REST API you can enable in Settings > Integrations > HTTP API. It runs on localhost:24678 by default and can be used from scripts, Raycast extensions, or any HTTP client.

The API supports listing projects and processes, starting/stopping/restarting processes, checking ports, and focusing the Solo window. Read endpoints are open; mutating endpoints require a X-Solo-Local-Auth: 1 header.

You can toggle these in Settings (Cmd/Ctrl+,):

• Project quick actions — The "Open in editor", "Open in terminal", and "Reveal in file manager" buttons on project headers. Each can be shown or hidden independently. They're always available from the command palette even when hidden.
• Settings footer — The Settings button at the bottom of the sidebar. You can always open settings with Cmd/Ctrl+, or from the command palette.

The "Cmd/Ctrl+K to launch actions" hint at the bottom of the sidebar goes away automatically after you've used the command palette five times.

Set your default editor and terminal in Settings (Cmd/Ctrl+,). Solo supports VS Code, Cursor, Zed, PhpStorm, WebStorm, IntelliJ IDEA, Sublime Text, Fleet, and custom editors.

For terminals, Solo supports Terminal, iTerm, Warp, Ghostty, Alacritty, Kitty, Hyper, and custom terminals.

You can also set a per-project editor override if different projects use different editors. The terminal setting is global.

Solo checks for updates automatically in the background every 30 minutes. When an update is available, a small "Update" button appears in the top bar.

Click it to see the release notes and install. The update downloads in the background, then Solo restarts automatically. You can also check manually from Settings > About > Check for updates.

Updates are always free, regardless of your license status.

For the latest shipped changes, read the changelog.

Solo is free forever for up to 4 projects and 20 processes. No license key required.

If you need more, purchase a license from the pricing section and activate it in Settings > Manage license. Your license key looks like SOLO-XXXX-XXXX-XXXX.

Licensed users can work offline for up to 14 days between server check-ins. If you hit the free tier limit without a license, all processes are paused until you activate a license or reduce your projects and processes.

If you're just getting started, grab the latest build from the download page.

Team licenses use centralized billing and claim links. A billing manager buys seats, generates a claim link from Account > Team, and shares it in Slack or email.

Anyone with the link can claim while seats remain and the pool is active. Claiming creates a normal Solo Pro license on that person's account.

Billing managers can view claimed seats and revoke them from the team dashboard. Team licensing v1 does not include domain gating, SSO, assigned seats, or directory sync. Read the team license docs for the full flow.