Environment Variables

Every DevBox you launch receives environment variables from three sources, all managed in the app. This page is the canonical reference: where each variable comes from, which one wins on a name collision, which tokens the services you use require, and what happens when a required token is missing.

Sources & precedence

Variables are assembled at launch time in this order — later sources override earlier ones when names collide:

1. Service access tokens — the provider credentials from Settings → Environment Variables, injected under well-known names (GH_TOKEN, AZURE_DEVOPS_EXT_PAT, …; see the table below).
2. Global variables — your free-form user-scope variables from Settings → Environment Variables → Global variables. Injected into every DevBox you launch.
3. Project variables — the project’s env vars, injected into every DevBox launched in that project. Project always wins: a project variable with the same name overrides your global value — and can even override a credential-mapped name like GH_TOKEN.

Tip

The override chain is intentional. Set your personal default globally, then override it per project where a specific effort needs a different value — for example a project-specific GH_TOKEN for a repo that lives in another GitHub org.

Service access tokens

Tokens for the repository and ticket services your runs touch. Set them once under Settings → Environment Variables → Service access (the per-worker agent sign-in wizard links here from its summary); they’re injected under these names:

Credential	Injected as	Required scopes	Used for
GitHub Personal Access Token	GH_TOKEN	Contents (read/write), Issues	GitHub CLI (gh) — clone, push, PRs, issues
Azure DevOps PAT	AZURE_DEVOPS_EXT_PAT	Work Items (Read), Code (Read & Write)	Azure DevOps repos and work items
GitLab Personal Access Token	GITLAB_TOKEN	api	GitLab CLI (glab) — issues, MRs
Jira API Token	JIRA_API_TOKEN	— (token from id.atlassian.com)	Jira CLI (jira). Also set JIRA_SERVER and your login email as project env vars

Global variables

Free-form variables under Settings → Environment Variables → Global variables — injected into every DevBox you launch, regardless of project. Use them for personal defaults you’d otherwise paste into each launch: a database URL, a feature flag, an API key for a tool your agents always use.

Each variable can be marked secret:

• Secret values are encrypted at rest and write-only — once saved they’re never shown back to you (paste a new value to replace; leaving the masked field untouched keeps the existing value).
• Secret values are redacted from run traces: the agent gets the variable in its environment, but the value is masked in the event stream and in what the model sees, so it can’t leak into a summary or a commit.

Run readiness & skip reasons

Before a run or schedule execution starts, ClusterCode checks that the service tokens it will need are configured — derived from the repository and ticket URLs the run targets. If a required token is missing, the run skips before any AI tokens are spent, with one of these reasons:

Skip reason	Meaning	Fix
missing_github_pat	The run targets a GitHub repository or issue, but no GitHub PAT is set	Add a PAT with Contents (read/write) and Issues scopes under Settings → Environment Variables, then re-trigger
missing_azure_devops_pat	The run targets an Azure DevOps repository or work item, but no Azure DevOps PAT is set	Add a PAT with Work Items (Read) and Code (Read & Write) scopes, then re-trigger
missing_gitlab_pat	The run targets a GitLab repository, but no GitLab PAT is set	Add a PAT with api scope, then re-trigger

The same check runs advisory in the run and schedule create panels (a warning row before you save) and powers the remediation banner on a skipped execution’s detail page — the banner re-checks live and flips to a success state as soon as you add the missing token, so you can re-trigger without leaving the page.

Note

A Jira token is only ever a warning, never a skip: an image containing the Jira CLI doesn’t prove the run uses it, so Jira-related runs are never blocked — you just see a hint if jira_api_token isn’t set.

Agent secrets

Credentials for the agents themselves — all four live under Settings → Environment Variables → Agent Secrets. The Claude OAuth token and Anthropic API key additionally carry a Use for DevBox authentication toggle, which injects the key into the DevBoxes you launch; the OpenAI and Copilot tokens are plain injected tokens.

Running the platform’s own agents on your Claude credential — Nova, Nucleus and the prompt improver — is a separate switch, and it is not on the credential row: it lives under Settings → App AI Assistants, where one control covers all three (and lets you pick the Claude model they run on). Alternatively, sign in interactively inside a DevBox — those logins persist across DevBox recreation via shared config volumes, encrypted end-to-end with a per-user key.

Variable	Agent	Description
ANTHROPIC_API_KEY	Claude Code	API key from console.anthropic.com (pay-as-you-go). Injected only when Use for DevBox authentication is enabled on the credential
CLAUDE_CODE_OAUTH_TOKEN	Claude Code	Long-lived OAuth token from claude setup-token — uses your Claude Pro/Max subscription. Injected only when Use for DevBox authentication is enabled on the credential
OPENAI_API_KEY	Codex	API key from platform.openai.com. Or run codex login --device-auth inside a DevBox to use a ChatGPT subscription
COPILOT_GITHUB_TOKEN	GitHub Copilot	Optional fine-grained PAT with Copilot Requests (Account permission). Set it if your GitHub PAT is a classic token (ghp_) or lacks Copilot access; falls back to GH_TOKEN

Worker

The clustercode CLI sets the worker up for you — run clustercode worker to select a tenant and start it, or clustercode onboard for guided setup.

Its preferences are set with clustercode config, not environment variables: the worker’s display name, how much memory the container runtime is allowed to use, and — on Windows — whether memory reclaim has been measured working on this machine.

clustercode config set WORKER_NAME my-worker
clustercode config set RUNTIME_MEMORY_MB 24576
clustercode config set RUNTIME_RECLAIM_VERIFIED yes

See CLI: config and Sizing container runtime memory for details.

Host memory protection (Windows)

On Windows with a local Podman machine on the WSL backend, the worker frees the WSL VM’s page cache when Windows runs low on memory. Two environment variables control that. The worker reads them at startup, so set them in the environment you start clustercode worker from, then restart the worker.

Variable	Default	Description
WORKER_HOST_RECLAIM	on	Unset, empty, on, true, 1, yes or enabled keeps the automatic cache drop on. Set to off, false, 0, no or disabled to turn it off. Any other value also turns it off, with a warning in the worker log.
WORKER_HOST_RECLAIM_FLOOR_MB	4096	Windows available memory, in MiB, below which the worker drops the cache. Accepts a whole number from 1 to 1048576; anything else is ignored with a warning, and the default applies.

These are read by the worker on your machine; they are not DevBox environment variables, and setting them in Settings → Environment Variables has no effect. See The worker drops the cache itself for when it acts and what it never does.

Worker disk hygiene

Two optional overrides for the worker’s disk hygiene inside the Podman machine on Windows. Leave them unset unless you have a reason to change the defaults. The worker reads them at startup, so set them in the environment you start clustercode worker from (the CLI passes its environment on to the agent), then restart the worker.

Variable	Default	Description
WORKER_GUEST_CLEAN	on	Unset, empty, on, true, 1, yes or enabled keeps the in-machine cleanup on. Set to off, false, 0, no or disabled to stop the agent capping the machine’s journal and removing leftover build scratch. Any other value also turns it off, with a warning in the worker log. It does not affect the cleanup of images a failed build or a rebuild left behind.
WORKER_GUEST_CLEAN_SCRATCH_AGE_HOURS	3	Minimum age, in whole hours, before leftover build scratch is removed. Accepts 1 to 168; anything else is ignored with a warning, and the default applies.

Like the host memory variables, these are read by the worker on your machine; setting them in Settings → Environment Variables has no effect.