Configure your project

Conductor can prepare each new workspace the same way, run your project from the Run button, and copy local files that Git does not track.

Most projects should start by asking Conductor to inspect the repository and create the shared project settings for you. Then use the rest of this page to review what it changed or make manual edits.

Quick start: ask Conductor

Use the bundled Conductor skill to configure this repository for Conductor.

Inspect the project, create or update `.conductor/settings.toml` with the shared setup this repo needs, migrate legacy `conductor.json` if present, and keep the configuration simple and workspace-safe. After editing, summarize what changed and one quick Conductor test I can run.

If you have more than one repository in Conductor, create a workspace in the project you want to configure and paste this prompt instead.

Review the diff before committing the settings file. The agent should explain why it chose each setup script, run script, file-copy pattern, or run mode.

Create project settings

Create .conductor/settings.toml at the root of your repository:

your-repo/
├── .conductor/
│   └── settings.toml
├── package.json
└── ...

If you prefer to configure the project manually, add the commands your project needs:

"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"

[scripts]
setup = "pnpm install"
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"

Commit this file when teammates should use the same setup:

git add .conductor/settings.toml
git commit -m "Add Conductor project settings"

Add a setup script

The setup script runs when Conductor creates a workspace.

Use it for commands that prepare the workspace:

• Install dependencies.
• Generate files.
• Create symlinks.
• Initialize local project state.

For details, see Setup scripts.

Add a run script

The run script starts your app, server, test watcher, or another long-running command from the workspace.

Use CONDUCTOR_PORT when the command starts a local server:

[scripts]
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"

Conductor gives each workspace its own port range, so multiple workspaces can run at the same time. For details, see Run scripts and Conductor variables.

Copy local files when needed

New workspaces start with Git-tracked files. Gitignored files such as .env.local, local certificates, and machine-specific config do not appear unless Conductor copies them or your setup script creates them.

Use Files to copy for static gitignored files that every local workspace needs.

Use a setup script when the workspace needs commands, generated files, symlinks, or per-workspace values.

Add project overrides to gitignore

Use .conductor/settings.local.toml for project settings that only apply on your machine.

Add it to .gitignore:

touch .gitignore
grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore

Know where settings live

Conductor layers settings from broad to specific:

For precedence, schemas, managed settings, and supported keys, see Settings and User and project settings.

Next steps

• Use Setup scripts, Files to copy, and Shell configuration when you need workspace setup details.
• Use Run scripts when you need to run the project from Conductor.
• Use Settings reference when you need the exact TOML keys Conductor supports.