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 the setup or archive script on the Scripts tab. Edit actions and Spotlight testing on the Actions tab.
• In the repository, add [scripts] to .conductor/settings.toml when 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

Setup scripts, archive scripts, and actions 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.

Actions

Actions start your app, server, test watcher, worker, or another long-running command from the active workspace. A project can define one or more actions. Conductor shows them in the Run button menu, and you can edit them under Custom actions on the repository's Actions settings tab. In settings files, actions are defined under scripts.run.

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

Use CONDUCTOR_PORT when an action starts a local server. Conductor allocates ten ports to each workspace: CONDUCTOR_PORT through CONDUCTOR_PORT+9. Use shell arithmetic to select another port in that range:

[scripts.run.api]
available_in = [ "local" ]
command = "pnpm api --port $((CONDUCTOR_PORT + 1))"

CONDUCTOR_PORT is not set in cloud workspaces, so keep actions that depend on it local-only.

Actions use non-interactive shells. If a tool works in your normal terminal but fails in an action, see Shell configuration.

Multiple actions

Add one named action under scripts.run.<id> for each command. Conductor uses the action ID to match the same action 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.

Action fields

Action icons

icon accepts a Lucide icon name written in lowercase kebab case. Common choices for actions 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 action

Older settings files may use scripts.run for a single action:

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

Conductor still reads scripts.run as a string for a single action. New settings that need more than one command should define named actions under scripts.run.

Where changes take effect

For where action 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 actions can run at once.

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 you click Stop for an action in a local workspace on macOS, Conductor sends SIGTERM to the action's process group. After five seconds, it sends SIGKILL to that group, even if the top-level process has already exited. The five-second grace period is not configurable.

Conductor does not recursively walk the descendant process tree. Descendants that move into another process group or session can survive and keep ports open, so their launcher must stop them during the grace period.

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.toml with teammates.