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.
Set each separately for local and cloud. The two often need different commands — a local script can skip what your machine already has cached.
Setup script
The setup script runs automatically:
- Local: once, inside a newly created worktree.
- Cloud: once, when a cloud workspace is created.
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:
For the Local script, 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.
Cloud scripts do not get suggestions.
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. Cloud workspaces are managed worktrees and report 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, Local or Cloud | 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. Do not use it to detect Local versus Cloud: both a local worktree and a
cloud workspace report worktree. Put target-specific behavior in the
separate Local and Cloud script fields instead.
Those variables are metadata Proliferate injects at launch. In the cloud, scripts also get the environment variables and secret files you configure: the repo's cloud environment plus your personal and organization secrets. Proliferate writes them into your sandbox as private files and re-applies them when you change them, so each run picks up the current values. They are stored encrypted.
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.