Settings
How Conductor settings configure workspaces, scripts, agents, and projects
Settings control how Conductor prepares workspaces, runs agents, starts projects, and configures providers.
Use the Settings screen or .conductor/settings.local.toml for project changes that should apply on your Mac. Use .conductor/settings.toml only for shared project defaults; Conductor reflects those changes after they are merged to the repository's default branch, usually main. For a step-by-step setup flow, see Configure settings.
Quickstart: project scripts
Create .conductor/settings.toml at the repository root when the setup and run scripts should be shared with the team:
your-repo/
├── .conductor/
│ └── settings.toml
├── package.json
└── ..."$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm i"
run_mode = "concurrent"
[scripts.run.dev]
command = "pnpm dev --port $CONDUCTOR_PORT"
default = true
icon = "play"This example is for a Node project. The setup script installs dependencies for the new workspace. Use the commands your project already uses. Use CONDUCTOR_PORT in run scripts so multiple Conductor workspaces can run dev servers at the same time.
Commit the shared project settings:
git add .conductor/settings.toml
git commit -m "Add Conductor settings"How settings are layered
Conductor layers settings like VS Code: user settings apply across repositories, project settings apply to one repository, and local project settings override that repository on one machine. If two layers set the same value, Conductor uses the highest layer that applies.
Settings precedence, highest first
1
Managed settings
Organization-controlled values. Most users do not edit this layer.
2
Project overrides
Your overrides for one project in
.conductor/settings.local.toml.3
Repository shared settings
Project defaults committed in
.conductor/settings.toml.4
User shared settings
Personal defaults in
~/.conductor/settings.toml.5
Built-in defaults
Conductor's fallback behavior when no settings file defines the value.
Choose the right settings file
| Scope | File | Use it for |
|---|---|---|
| User settings | ~/.conductor/settings.toml | Your defaults across all repositories |
| Project overrides | <repo>/.conductor/settings.local.toml | Your machine's override for one project |
| Project settings | <repo>/.conductor/settings.toml | Shared setup, run, archive, prompts, environment, provider, and Git behavior after the change is merged |
| Managed settings | ~/.conductor/settings.managed.toml | Organization-controlled values |
Next steps
- Follow Configure settings for a step-by-step setup flow.
- Use User and project settings for file locations, scope, and precedence.
- Use Settings reference for the complete key reference.
- Use Managed settings for organization-controlled settings.
- Browse Sample settings configurations for copyable examples.
- Migrating from legacy
conductor.json? See conductor.json.