# 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](./project-customization.md) 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](../commands/file-watch-auto-restart.md).
- `env` — optional mapping of environment-variable names to string values. Quote numeric- or boolean-looking values so YAML keeps them as strings.

Example:

```yaml
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](../commands/trust-security.md) for details.
- If `solo.yml` changes, Solo shows a sync prompt so you can pull in the latest version. See [solo.yml change notifications](./yml-change-notifications.md).

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/projects/solo-yml