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 have to repeat the same instructions in every prompt.
Each repository has two script fields, configured under Settings → Repo → Actions:
- Setup script: installs dependencies and prepares generated files.
- Run command: starts the app, service, preview, or dev server.
Both are set separately for the repo's local checkout and its cloud environment, since the two often need different commands (a local setup script might skip a step your machine already has cached, for example).
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 setup script, Proliferate also scans the linked checkout for
common setup commands and files that are usually gitignored but still needed
in a worktree (like .env). When it finds matches, it shows suggestions you
can check on or off; selected commands are appended to the Local setup script.
Cloud setup scripts do not show these detected suggestions.
Run command
The run command is what the workspace's Run action launches: your app,
server, or preview process. It runs inside the selected workspace and gets
the same environment variables as the setup script,
minus PROLIFERATE_BASE_REF.
Use normal shell expansion in the command itself:
There's no separate test or review command field. If you want an agent to run your test suite or linter as a matter of course, 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 on their own.
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.
The variables above are metadata Proliferate injects at launch. In the cloud, scripts also run with the environment variables and secret files you configure — your repository's cloud environment, plus any personal and organization secrets. Proliferate materializes these into your per-user cloud sandbox as private files and re-applies them whenever you change them, so each run picks up the values present when it launches. They're stored encrypted as secrets; there's no separate plaintext channel beyond the metadata variables above.
What makes a good script
Good setup scripts and run commands are deterministic, fast enough for repeated use, and safe for an agent to run without extra context.
Prefer commands that:
- Fail clearly.
- Avoid destructive behavior.
- Work from a fresh checkout.
- Match the checks humans already trust.
Next: lifecycle and storage.