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.

Read the relevant docs:
- https://www.conductor.build/docs/reference/settings
- https://www.conductor.build/docs/reference/scripts

Inspect this repo and create or update the `.conductor/settings.toml` file in the repo root with the best shared Conductor config.

Requirements:
- If `.conductor/settings.toml` already exists, preserve its existing settings unless clearly wrong.
- Stamp the schema at the top for validation: `#:schema https://conductor.build/schemas/settings.repo.schema.json`.
- Configure the `[scripts]` table as fully as makes sense; baseline is a setup script with `scripts.setup`, plus `scripts.run` and `scripts.archive`.
- Follow the repo's existing package manager, scripts, and setup conventions.
- Keep commands simple, non-interactive, non-destructive, and workspace-safe.
- Use `CONDUCTOR_PORT` for run scripts when the project supports configurable ports.
- Set `scripts.run_mode` if concurrency behavior is clear.
- Use the `[scripts]` table in `.conductor/settings.toml`; do not create a legacy `conductor.json` file.

Inspect the usual sources: package files, lockfiles, README/contributing docs, Makefile/justfile/taskfile, Docker/Procfile config, and existing `scripts/` or `bin/`.

After editing, validate the TOML and summarize what you configured, why, 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.