Configure settings
Set personal defaults, project settings, and local project overrides in Conductor
Use this guide when you want to configure the settings most people edit directly: your global defaults, a project's shared settings, and your local overrides for one project.
Conductor has a layered settings model: user settings apply to all projects, project settings apply to one repository, and local project settings override on a single machine. Organization-managed settings take precedence, if configured.
Before you start
You need:
- A repository already added to Conductor.
- A terminal open at the repository root if you are configuring project settings.
- The commands your project uses to install dependencies and start the app.
Use the in-app Settings page when you want Conductor to write settings for you. Open it from the File menu or the Settings button in the side nav.
Find project-level settings in Settings > Repo, then select your project from the dropdown. You can also configure project settings as code in .conductor/settings.local.toml.
Choose the settings layer
Pick the file that matches who should receive the setting:
| Scope | Git | File |
|---|---|---|
| You, across all repositories | Do not commit | ~/.conductor/settings.toml |
| Only you, in one repository | Add to .gitignore | <repo>/.conductor/settings.local.toml |
Everyone after merge into main | Commit and open a PR | <repo>/.conductor/settings.toml |
Repository local settings win over repository shared settings. Repository shared settings win over user settings.
The easiest way to edit run scripts is in Conductor app settings. The UI updates settings files without needing to edit configuration manually.
Use <repo>/.conductor/settings.local.toml when a run script should apply only on your Mac. Changes there are reflected in this repository's workspaces on your machine.
Use <repo>/.conductor/settings.toml only when a run script should become a shared team default. Conductor reflects those changes after the settings change is merged to the repository's default branch, usually main.
If your organization manages Conductor settings, those values sit above the normal user and project stack. See Managed settings for that separate flow.
Configure your user defaults
Use user settings for personal defaults that should follow you across projects, such as model choices and reasoning defaults.
Create the user settings file
Create the settings directory if it does not exist:
mkdir -p ~/.conductorThen create or edit ~/.conductor/settings.toml:
"$schema" = "https://conductor.build/schemas/settings.schema.json"
[models]
default = "gpt-5.5"
review = "sonnet"
default_plan_mode = true
[models.codex]
default_thinking_level = "high"
personality = "direct"
[models.claude_code]
default_effort_level = "normal"Adjust the values
Keep only the defaults you actually want everywhere. For example, if you only want Codex sessions to start with higher reasoning, keep this smaller file:
"$schema" = "https://conductor.build/schemas/settings.schema.json"
[models.codex]
default_thinking_level = "high"Configure shared project settings
Use shared project settings for repository behavior that should travel with the project, such as setup scripts, run scripts, Files to copy patterns, prompts, environment variables, and Git behavior.
Create the project settings file
From the repository root, create the settings directory if it does not exist:
mkdir -p .conductorThen create or edit .conductor/settings.toml:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm install"
run_mode = "concurrent"
[scripts.run.dev]
command = "pnpm dev --port $CONDUCTOR_PORT"
default = true
icon = "play"Use your project's real setup and run commands. Use CONDUCTOR_PORT when the development server can accept a custom port, so multiple workspaces can run at the same time.
This shared file affects the Run menu only after the change is merged to the repository's default branch. Use Settings for immediate configuration, or .conductor/settings.local.toml for a local-only override.
Choose the run mode
Keep run_mode = "concurrent" when each workspace can run independently.
Use run_mode = "nonconcurrent" when the project depends on one fixed port, one local database, one Docker stack, or another shared resource:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm install"
run_mode = "nonconcurrent"
[scripts.run.dev]
command = "pnpm dev"
default = true
icon = "play"Add project-specific details
Add sections only when the project needs them. For example, this project also copies gitignored environment files, sets an agent prompt, and customizes branch names:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
file_include_globs = ".env*\nconfig/*.local.json\n"
[scripts]
setup = "pnpm install"
run_mode = "concurrent"
[scripts.run.dev]
command = "pnpm dev --port $CONDUCTOR_PORT"
default = true
icon = "play"
[prompts]
general = "Prefer small, reviewable changes and run the narrowest relevant tests."
[git]
branch_prefix_type = "custom"
branch_prefix = "agent"Commit the shared settings
Commit .conductor/settings.toml when the settings should apply to the project:
git add .conductor/settings.toml
git commit -m "Add Conductor project settings"Configure a local project override
Use .conductor/settings.local.toml for machine-specific overrides, such as a local run script or provider URL.
Ignore the local override file
From the repository root, add the local settings file to .gitignore:
touch .gitignore
grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignoreAdd your local overrides
For example, override the Run button command and a local provider URL on your machine:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
run_mode = "concurrent"
[scripts.run.dev]
command = "pnpm dev --host 127.0.0.1 --port $CONDUCTOR_PORT"
default = true
icon = "play"
[environment_variables]
ANTHROPIC_BASE_URL = "http://127.0.0.1:4000"This file overrides matching values from .conductor/settings.toml only for your local checkout.
Verify the settings
Create a new workspace from the repository. Conductor should run the setup script from .conductor/settings.toml and use the shared Run button command unless your local override replaces it.
For a quick check, click Run in the workspace and confirm the command starts with the expected port behavior. If you configured CONDUCTOR_PORT, create a second workspace and confirm both workspaces can run at the same time.