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 a
[scripts]table 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.run | When you click the Run button | Starting an app, server, worker, watcher, or test loop |
| 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
The run script starts your app, server, test watcher, worker, or another long-running command from the active workspace.
[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.
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.