Environment variables vx reads

Every setting has a variable derived from its path (run.timeout → VX_RUN_TIMEOUT), beating .vx/workspace and beaten by the flag; the table in docs/schema.md § Settings gives each value’s form and default. Each is checked once before any verb runs: an empty one is unset, a value its kind does not take is refused naming the form, and a variable vx does not read is ignored. A plugin’s own (the REAPI endpoints, the GitHub token) are in its README; what a TASK sees is exec.env in docs/schema.md.

Variable	Setting	What it does
VX_BASE_BRANCH	baseBranch	The default branch: a run on it has no cache scope and a bare --affected no base; elsewhere both use the merge base with origin/<baseBranch>.
VX_AFFECTED_BASE	affectedBase	The commit a bare --affected compares with, on the base branch too. --affected=<base> beats it; it beats a plugin’s base commit. Env only: a committed base would be stale on the next push.
VX_RUN_CONCURRENCY	run.concurrency	Tasks at once: a positive integer, or a share of the cores ('50%').
VX_RUN_SCHEDULE	run.schedule	Which ready task starts first when there are more than workers.
VX_RUN_BRANCH	run.branch	The branch a run records in its history and forecasts from. Flag and env only: a committed branch would be wrong on every other branch.
VX_RUN_TIMEOUT	run.timeout	A task’s time limit, for tasks without their own exec.timeout ('30m').
VX_RUN_RETRIES	run.retries	Re-runs of a failed task, for tasks without their own exec.retries.
VX_RUN_CONTINUE	run.continue	What a failed task takes down: never stops the run, deps-ok skips its dependents, always runs them too.
VX_RUN_OUTPUT_LOGS	run.outputLogs	Which task output the run prints. Chosen before the workspace loads, so flag and env only.
VX_RUN_RULES_EXCLUSIVE_OUTPUTS	run.rules.exclusiveOutputs	Refuse two tasks whose outputs overlap even when an edge orders them.
VX_CACHE_DIR	cache.dir	Where the cache lives, relative to the workspace root; named, it holds the whole cache.
VX_CACHE_POLICY	cache.policy	Which layers a run reads and writes ('local:rw,remote:r'); --no-cache and --force apply on top.
VX_CACHE_SCOPE	cache.scope	The branch scope plugin entries are keyed under ('vznjs/vx:feat-x'); task keys never carry it. Empty: no scope.
VX_CACHE_CONCURRENCY_DOWNLOAD	cache.concurrency.download	Remote downloads at once.
VX_CACHE_CONCURRENCY_UPLOAD	cache.concurrency.upload	Uploads at once, per remote.
VX_CACHE_CONCURRENCY_RESTORE	cache.concurrency.restore	Local hits restoring outputs at once.
VX_CACHE_DOWNLOAD	cache.download	Which remote hits land on disk: every one, only the requested tasks, or none.
VX_CACHE_INPUT_STABILITY_STRATEGY	cache.inputStability.strategy	What a write to an input during the command means for the save, for tasks without their own.
VX_CACHE_INPUT_STABILITY_SEVERITY	cache.inputStability.severity	Whether a skipped save warns or fails the task, for tasks without their own.
VX_CACHE_STORE_EMBEDDINGS	cache.store.embeddings	Keep an entry up to this size inside the cache index, one zstd tar, rather than as files; false keeps none.
VX_CACHE_STORE_DECOMPRESS	cache.store.decompress	Keep a larger entry as its plain files, which a hit copies or clones out; off, as one .tar.zst.
VX_LOCK_REVIEW_FILES	lock.reviewFiles	vx lock writes each project’s resolved config, pretty, to vx.lock.json beside its vx.config, for review; vx never reads it.
VX_WATCH_POLL	watch.poll	Poll for changes from the start instead of the OS watcher.
VX_CONFIG_WORKER_TIMEOUT	config.workerTimeout	How long one config evaluation may take.
VX_DEBUG_TIMING	debug.timing	Print the run’s stage timings to stderr.
VX_DEBUG_WATCH	debug.watch	vx watch: say on stderr each time the loop arms, with the projects it watches.
VX_DEBUG_DUMPABLE	debug.dumpable	Linux: keep vx dumpable, so strace or a debugger can read its memory and /proc/<pid>/fd, and an unsandboxed task its env.
VX_HANDED_OFF	—	Set by a global vx that hands the call to the project’s own (§ Which vx runs): the path of the vx that handed off, so the receiver does not hand off again.
VX_RUN_WORKSPACE, VX_RUN_TASK	—	Set by vx on every task (below); a vx run a task starts reads them back.

vx sets two variables on every task’s environment: VX_RUN_WORKSPACE (the workspace root) and VX_RUN_TASK (project#task). A vx run a task starts reads them back: one in the same workspace is refused, since a nested run is invisible to the outer graph and a loop back to its own task forks without bound (docs/schema.md § env).

Colors are the two conventions in § Output format › Colors (NO_COLOR, FORCE_COLOR). A truthy CI picks the CI output flow and GITHUB_ACTIONS its ::group:: framing (§ Output); the run’s invocations row records the provider, the first truthy of GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, CIRCLECI, then CI. Core never reads GITHUB_STEP_SUMMARY; the job summary is @vzn/vx-ci’s. A sandboxed task’s temp dir sits under CLAUDE_CODE_TMPDIR (else CLAUDE_TMPDIR, else /tmp/claude), the sandbox runtime’s own convention (docs/modules/sandbox-runtime.md).