Setup & action scripts
Define the setup script and run command agents should use for your repository.
Setup scripts and run commands teach Proliferate how your repository works, so you don't repeat the same instructions in every prompt.
Each repository has two fields under Settings → Repo → Actions:
- Setup script installs dependencies and prepares generated files.
- Run command starts the app, service, or dev server.
Setup script
The setup script runs automatically once, inside a newly created worktree.
It gets the environment variables below, including
PROLIFERATE_BASE_REF, which only the setup script sees.
A typical setup script installs packages and generates anything the repo needs before an agent starts working:
Proliferate scans your checkout for common setup commands and for gitignored
files a worktree still needs, like .env. Matches appear as suggestions you can
tick; the ones you pick are appended to the script.
Run command
The run command is what the Run action launches. It runs inside the
workspace and gets the same environment variables as
the setup script, minus PROLIFERATE_BASE_REF.
Use normal shell expansion in the command itself:
There is no test or review command field. Say so in your prompt, or fold the command into the run script. Agents are also good at finding a repo's existing test and lint commands themselves.
Environment variables
| Variable | Set for | Description |
|---|---|---|
PROLIFERATE_WORKSPACE_ID | Always | Unique id of the workspace. |
PROLIFERATE_WORKSPACE_DIR | Always | Absolute path to the workspace. |
PROLIFERATE_WORKSPACE_KIND | Always | local for a linked checkout or worktree for a managed worktree. |
PROLIFERATE_REPO_ROOT_ID | Always | AnyHarness id of the registered repository root. |
PROLIFERATE_REPO_DIR | Always | Absolute path to the source repo. |
PROLIFERATE_REPO_NAME | Always | Repo name. |
PROLIFERATE_RUNTIME_HOME | Always | Absolute path to the AnyHarness runtime's data directory. |
PROLIFERATE_BRANCH | When known | Workspace branch, omitted for a detached checkout. |
PROLIFERATE_WORKTREE_DIR | Worktree workspaces | Same path as PROLIFERATE_WORKSPACE_DIR. |
PROLIFERATE_BASE_REF | Setup script only, when known | The ref this workspace branched from. |
PROLIFERATE_GIT_PROVIDER | Repo has a remote | e.g. github. |
PROLIFERATE_GIT_OWNER | Repo has a remote | Remote owner or org. |
PROLIFERATE_GIT_REPO | Repo has a remote | Remote repo name. |
PROLIFERATE_WORKSPACE_KIND describes the checkout shape, not the execution
target.
Those variables are metadata Proliferate injects at launch.
What makes a good script
Deterministic, fast enough to run often, and safe for an agent to run unattended. Prefer commands that:
- Fail clearly.
- Avoid destructive behavior.
- Work from a fresh checkout.
- Match the checks humans already trust.
Next: lifecycle and storage.