solo.yml overview

solo.yml is a configuration file that lives in your project root and defines the commands Solo should load and run. It lets you share your project's command setup with teammates through the repository.

What it's for#

• Keeping command setup in version control so it doesn't live only on your machine.
• Sharing project command definitions with teammates — they add the project and everything is already configured.
• Bootstrapping Solo's project config directly from a file in the repo.

Typical fields#

At the top level, solo.yml can include:

• name — optional display name used when the project is first loaded from the file.
• icon — optional image path relative to the project root.
• icon_initials — optional 1-2 characters shown on the project's swatch icon in the sidebar. Values outside 1-2 characters are rejected when the file is synced. For a primary project with an existing solo.yml, editing swatch initials in the app writes them back to this field; linked-checkout swatch overrides remain local.
• processes — command definitions keyed by the command name shown in Solo.

A process entry includes:

• command — the shell command to run.
• working_dir — optional working directory. Relative paths are resolved from the project root. For a local project root, an absolute path is accepted only when it resolves inside the project. For a WSL UNC project root, use a relative path that stays inside the project; absolute paths are rejected.
• auto_start — optional; defaults to true when omitted in YAML.
• auto_restart — optional; defaults to false.
• restart_when_changed — optional list of glob patterns used for file-watch restarts.
• env — optional mapping of environment-variable names to string values. Quote numeric- or boolean-looking values so YAML keeps them as strings.

Example:

name: storefront
icon: assets/project-icon.png
icon_initials: SF
processes:
  Web:
    command: npm run dev
    working_dir: null
    auto_start: false
    auto_restart: false
    restart_when_changed: []
    env: {}

Important notes#

• Solo syncs file-based config into local app state. File-backed commands use solo.yml as the shared config while Solo keeps runtime state locally.
• Empty or comment-only solo.yml files are treated as empty config.
• solo.yml is limited to 1 MB.
• File-backed command names can be renamed during sync when Solo sees an unambiguous remove/add pair with the same command string; the existing command row and trust status are preserved when security-relevant fields are unchanged.
• Solo skips YAML command entries whose names collide with existing non-command rows such as terminals or agents.
• Trust can be required before file-defined commands run. See Trust and security for details.
• If solo.yml changes, Solo shows a sync prompt so you can pull in the latest version. See solo.yml change notifications.