Scripts
Reference for setup, run, and archive scripts
Project scripts give every Conductor workspace the same project workflow: prepare the workspace, run the project, and clean up after archive.
Configure project scripts in Conductor or in a settings file:
- In the app, open
Settings, select the project, and edit setup, run, archive, or Spotlight settings. - In the repository, add
[scripts]to.conductor/settings.tomlwhen the same workflow should be shared with teammates.
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm install"
run = "pnpm dev --port $CONDUCTOR_PORT"
archive = "./script/workspace-archive.sh"
run_mode = "concurrent"Commit .conductor/settings.toml when teammates should use the same project workflow. For settings file locations and precedence, see User and project settings. For the full key list, see Settings reference.
Script types
| Script | Setting | When it runs | Use it for |
|---|---|---|---|
| Setup | scripts.setup | After Conductor creates a workspace | Installing dependencies, generating files, creating symlinks |
| Run scripts | scripts.run | When you click the Run button | Starting apps, servers, workers, watchers, or test loops |
| Archive | scripts.archive | Before Conductor archives a workspace | Cleaning up resources outside the workspace directory |
| Run mode | scripts.run_mode | When a run script starts | Choosing whether run scripts can overlap |
Setup, run, and archive scripts run from the workspace directory, available as CONDUCTOR_WORKSPACE_PATH. Use CONDUCTOR_ROOT_PATH when a script needs a file from the repository root.
Setup scripts
The setup script prepares a new workspace after Git checks out the tracked repository files. Use it when the workspace needs commands, generated files, symlinks, or workspace-specific resources.
[scripts]
setup = """
pnpm install
cp "$CONDUCTOR_ROOT_PATH/.env" .env
pnpm run build
"""If all you need is to copy gitignored local files such as .env.local, use Files to copy instead.
Run scripts
Run scripts start your app, server, test watcher, worker, or another long-running command from the active workspace. A project can define one or more run scripts. Conductor shows them in the Run button menu.
[scripts]
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"Use CONDUCTOR_PORT when a run script starts a local server. Conductor allocates ten ports to each workspace: CONDUCTOR_PORT through CONDUCTOR_PORT+9.
Run scripts use non-interactive shells. If a tool works in your normal terminal but fails in a run script, see Shell configuration.
Multiple run scripts
Add one named run script under scripts.run for each command. Conductor uses the run script ID to match the same script across user, project, and local project settings.
[scripts]
run_mode = "concurrent"
[scripts.run.web]
available_in = [ "local", "cloud" ]
command = "pnpm dev --port $CONDUCTOR_PORT"
default = true
icon = "play"
[scripts.run.worker]
available_in = [ "local", "cloud" ]
command = "pnpm worker:dev"
icon = "server"
[scripts.run.test]
available_in = [ "local", "cloud" ]
command = "pnpm test:watch"
icon = "test-tube"Choose an ID that describes the command, such as web, worker, or test. Use letters, numbers, spaces, or hyphens. Conductor normalizes repeated spaces and treats hyphens as spaces for display.
Run script fields
| Field | Type | Description |
|---|---|---|
command | string | Shell command to run from the active workspace. Required for a runnable script. |
args | array of strings | Optional arguments passed with the command. |
options.cwd | string | Optional working directory relative to the workspace. |
default | boolean | Marks the script Conductor should select by default when more than one script exists. |
icon | string | Lucide icon name shown with the script. Invalid icon names fall back to play. |
hide | boolean | Hides the script from the Run button. Set it in .conductor/settings.local.toml to hide a shared script on your machine only. |
available_in | "local", "cloud", or an array of both | Limits where the script appears. Omit it when the script should be available locally and in cloud workspaces. |
Run script icons
icon accepts a Lucide icon name written in lowercase kebab case. Common choices for run scripts include play, terminal, square-terminal, server, globe, database, monitor, rocket, code, braces, package, test-tube, bug, wrench, settings, cloud, folder, file-code, and flame.
Legacy single run script
Older settings files may use scripts.run for a single run script:
[scripts]
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"Conductor still reads scripts.run as a string for a single run script. New settings that need more than one command should define named run scripts under scripts.run.
Where changes take effect
For where run script changes apply, when to use local overrides, and how shared project settings reach teammates, see User and project settings.
Run mode
scripts.run_mode controls whether multiple run scripts can run at once.
| Mode | Behavior |
|---|---|
concurrent | Run scripts can run in multiple workspaces at the same time. |
nonconcurrent | Starting a run script stops any other run script first. |
Use nonconcurrent when your project depends on one fixed port, one local database, one Docker stack, or another shared resource that multiple workspaces cannot use at the same time.
Archive scripts
The archive script runs before Conductor archives a workspace. Use it to clean up project-specific resources outside the workspace directory.
[scripts]
archive = "./script/workspace-archive.sh"For example, a desktop app might remove a workspace-specific application support directory:
rm -rf "$HOME/Library/Application Support/com.example.app.dev.$CONDUCTOR_WORKSPACE_NAME"Process handling
When Conductor stops a script process, it sends SIGHUP, waits up to 200ms, then sends SIGKILL if the process is still running.
Related references
- Files to copy for static gitignored files that should appear in each workspace.
- Conductor variables for workspace paths and allocated ports.
- Shell configuration for non-interactive shell behavior.
- Spotlight testing for projects that need to run from the repository root.
- Share project settings for committing
.conductor/settings.tomlwith teammates.