Cloud workspace environment variables

Cloud workspaces run in Linux sandboxes instead of on your Mac, so they expose a smaller set of environment variables than local workspaces. The variables below are available everywhere in the workspace: the setup script, agents, and terminals.

Available variables

Start with these variables when you are writing setup scripts or debugging a cloud workspace terminal. They are the stable values Conductor sets for every cloud workspace.

Variable	Value in cloud workspaces	Use it for
`CONDUCTOR_WORKSPACE_PATH`	Path to the repository checkout inside the sandbox	Finding the workspace directory from setup scripts, agents, and terminals.
`CONDUCTOR_BASE_DIR`	Directory containing the workspace	Caches and scratch files that should stay outside the repository checkout.
`CONDUCTOR_IS_LOCAL`	`0` in cloud workspaces. `1` in local workspaces.	Choosing local steps or cloud steps in one setup script.

Differences from local workspaces

Most local workspace variables exist because local workspaces share your Mac, your root checkout, and your local port range. Cloud workspaces run on isolated machines, so some of those values either are not needed or need a cloud-specific setting.

Local behavior	Cloud behavior	Configure in cloud
`CONDUCTOR_ROOT_PATH` points to the root checkout.	Cloud workspaces have one repository checkout, so `CONDUCTOR_ROOT_PATH` is not set.	Use custom variables for values that local setup reads from the root checkout.
`CONDUCTOR_PORT` gives each local workspace a port range.	`CONDUCTOR_PORT` is not set. Each cloud workspace runs on its own machine, so ports do not conflict with other workspaces.	Let servers use their normal port, or choose a fixed port in your setup or run command.
`CONDUCTOR_WORKSPACE_NAME` and `CONDUCTOR_DEFAULT_BRANCH` are set locally.	These variables are not set in cloud workspaces.	Ask Git for the default branch when a script needs it.
Setup can be rerun from the app.	The setup script runs once when Conductor creates the cloud workspace.	Put required setup in the script before creating the workspace. Create a new workspace to rerun setup from scratch.
Your local GitHub authentication comes from your Mac.	`git` and `gh` are already authenticated inside the sandbox.	Do not copy GitHub tokens into cloud workspace environment variables.

To find the default branch inside a cloud workspace, run:

git remote show origin | sed -n 's/.*HEAD branch: //p'

Write one setup script for both environments

Cloud workspaces run the same setup script as local workspaces, resolved from your settings when the workspace is created. Branch on CONDUCTOR_IS_LOCAL for steps that only make sense in one environment:

if [ "$CONDUCTOR_IS_LOCAL" = "1" ]; then
  # Local only: the root checkout exists on your Mac.
  ln -s "$CONDUCTOR_ROOT_PATH/.env" .env
fi
pnpm install

The cloud snapshot's initialization script receives the same variables as the setup script.

Use CONDUCTOR_IS_LOCAL for local only setup such as symlinking files from the root checkout. Put cloud secrets and cloud only values in settings instead.

Configure custom variables

Cloud workspaces receive the same custom variables as local ones, configured in settings. Use environment_variables.cloud for values that should only apply in the cloud:

.conductor/settings.toml

"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"

[environment_variables]
API_BASE_URL = "https://api.staging.example.com"

[environment_variables.cloud]
CI = "1"

When variables take effect

Conductor reads settings when it creates the cloud workspace and sends a snapshot to the sandbox. Changes to settings apply to new workspaces, not existing ones.

Local machine settings can hold secrets. Values from .conductor/settings.local.toml and from environment variables set in the app's settings are included in the cloud workspace snapshot, so secrets do not need to be committed to the repository.

Reserved names

Some names belong to the sandbox runtime and cannot be used for custom configuration. Avoid these names in repository settings and local machine settings.

Reserved name or prefix	Reason
`PATH`	Managed by the sandbox shell environment.
`HOME`	Managed by the sandbox user environment.
`PORT`	Reserved for platform runtime behavior.
`NODE_PATH`	Reserved for Node.js module resolution.
`CONDUCTOR_WORKSPACE_PATH`	Set by Conductor for the repository checkout path.
`CONDUCTOR_INTERNAL_*`	Reserved for Conductor internal sandbox behavior.
`CONDUCTOR_GIT_AUTH_*`	Reserved for Conductor managed Git authentication.

Variables with reserved names or prefixes cannot be overridden and may change without notice.