solo.yml overview

solo.yml defines a project's commands in a file at the repository root. Commit it to share the command definitions with your team. Solo keeps process status and other runtime state locally.

The file configures command processes. Agent sessions launch through the agent picker.

For a setup guide, see Run a Laravel dev stack.

Project fields#

At the top level, solo.yml can include:

• name: Optional display name used when Solo first loads the project from the file.
• icon: Optional image path relative to the project root.
• icon_initials: Optional text for the project's swatch icon. Solo rejects values outside 1-2 characters during sync. For a primary project with an existing solo.yml, edits to swatch initials in the app update this field. Linked-checkout overrides remain local.
• processes: Command definitions keyed by the name shown in Solo.

Command fields#

Each entry under processes has these fields:

• command: The shell command to run.
• working_dir: Optional working directory. Relative paths resolve from the project root. Local projects accept absolute paths only when they resolve inside the project. WSL UNC projects accept only relative paths that stay inside the project.
• auto_start: Optional. Defaults to true when omitted in YAML.
• auto_restart: Optional. Defaults to false. When enabled, restarts the command after it exits on its own, subject to a rate limit. An explicit stop keeps it stopped.
• restart_when_changed: Optional list of glob patterns for file-watch restarts. Changes to the pattern list take effect after the command restarts.
• env: Optional mapping of environment-variable names to string values. Numeric and boolean values need quotes to remain strings in YAML.

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: {}

Sync and limits#

• Empty or comment-only solo.yml files are treated as empty config.
• solo.yml is limited to 1 MB.
• Solo can detect a command rename during sync when one removed entry and one added entry have the same command string. Solo preserves the command row and trust status when security-relevant fields are unchanged.
• Solo skips YAML command entries whose names collide with existing non-command rows such as terminals or agents.
• File-defined commands may require trust before they can run.
• Changes to solo.yml trigger a configuration sync prompt.