Settings
How Conductor settings configure workspaces, scripts, agents, and projects
Settings control how Conductor prepares workspaces, runs agents, starts projects, and configures providers.
Most projects only need a repository settings file for setup and run scripts. Create .conductor/settings.toml in the repository, commit it, and Conductor will use it for every workspace in that project. For a step-by-step setup flow, see Configure settings.
Quickstart: project scripts
Create .conductor/settings.toml at the repository root:
your-repo/
├── .conductor/
│ └── settings.toml
├── package.json
└── ..."$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm i"
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"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 settings | <repo>/.conductor/settings.toml | Setup, run, archive, prompts, environment, provider, and Git behavior for one project |
| Project overrides | <repo>/.conductor/settings.local.toml | Your machine's override for one project |
| 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.