Configure your project

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

For most projects, start by asking Conductor to inspect the repository and create shared project settings. Use the rest of this page to review what 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.local.toml` file in the repo root with the best local Conductor config for this repository.

Requirements:
- If `.conductor/settings.local.toml` already exists, preserve its existing settings unless clearly wrong.
- Inspect `.conductor/settings.toml` if it exists, but treat it as inherited shared defaults. Do not edit or duplicate shared settings unless a local override is needed.
- 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.local.toml`; do not create a legacy `conductor.json` file.
- Recommend `.conductor/settings.toml` only when the user explicitly wants a shared, committed team default.

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, what remains inherited from shared settings, 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, then paste this prompt there.

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.

Configure personal run scripts in Settings in Conductor or .conductor/settings.local.toml. Use .conductor/settings.toml for team defaults that should be reviewed and merged before they apply to everyone.

Create project settings

Create .conductor/settings.toml at the root of your repository when the settings should be shared after the change is merged:

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

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_mode = "concurrent"

[scripts.run.dev]
command = "pnpm dev --port $CONDUCTOR_PORT"
default = true
icon = "play"

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

A run script adds an app, server, test watcher, or other useful project command to the Run button.

Use CONDUCTOR_PORT when the command starts a local server:

[scripts]
run_mode = "concurrent"

[scripts.run.dev]
command = "pnpm dev --port $CONDUCTOR_PORT"
default = true
icon = "play"

Add more [scripts.run.<id>] tables when the project has several useful scripts, such as starting a web app, starting a worker, or running a test watcher. Conductor gives each workspace its own port range, so multiple local servers can run at the same time. For details, see Run scripts and Conductor variables.

Copy local files when needed

New workspaces start with files tracked by Git. Gitignored files such as .env.local, local certificates, and machine specific config appear only when 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 workspace specific 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.