Last updated 2026-05-07

Runner Configuration

Every runner setting is an environment variable. There are no config files. Set them when starting the process:

PORT=5000 RUNNER_WORKSPACE=/repos/my-project stax runner start

Variables

Variable	Default	Description
`PORT`	`4800`	HTTP server port.
`RUNNER_WORKSPACE`	`process.cwd()`	Path to the project containing `.github/workflows/`.
`RUNNER_SECRETS_KEY`	(none)	Master password for AES-256-GCM secrets at rest.
`RUNNER_NO_CACHE`	`0`	Set to `1` to skip the action cache and re-download each time.
`RUNNER_CACHE_TTL_MS`	`86400000` (24h)	Maximum age of cached marketplace actions, in milliseconds.
`RUNNER_ACTIONS_CACHE`	`~/.local/share/local-runner/actions-cache/`	Cache directory for marketplace actions.
`RUNNER_SANDBOX_DIR`	`/tmp/runner-sandboxes`	Base directory for sandbox workspaces.
`RUNNER_WORKFLOW_CACHE`	`~/.local/share/local-runner/workflow-cache/`	Cache directory for remote reusable workflows.
`GITHUB_TOKEN` / `GH_TOKEN`	(none)	Token for downloading private actions / workflows and populating `secrets.GITHUB_TOKEN`.
`RUNNER_R2_ACCOUNT_ID`		Activates the Cloudflare R2 secrets backend.
`RUNNER_R2_ACCESS_KEY_ID`		R2 access key ID.
`RUNNER_R2_SECRET_ACCESS_KEY`		R2 secret access key.
`RUNNER_R2_BUCKET`	`stax-secrets`	R2 bucket name.
`RUNNER_R2_ENDPOINT`	derived from account ID	Override the R2 endpoint URL.
`RUNNER_GITHUB_REPO`	derived from `git remote`	Repo for the GitHub secrets backend, in `owner/repo` form.
`SOPS_BINARY`	auto-detected	Override the `sops` binary used by the SOPS + age backend.
`SOPS_AGE_KEY`	(none)	Inline age private identity used by SOPS. Useful for CI-only identities.
`SOPS_AGE_KEY_FILE`	standard SOPS paths	Age identity file used by SOPS and Stax.
`SOPS_AGE_KEY_CMD`	(none)	Command that prints an age identity, for remote key brokers or password managers.
`STAX_GH_WEBHOOK_SECRET`	(none)	HMAC secret for `POST /api/sync/inbox` GitHub webhook verification.

Default directories

~/.local/share/local-runner/
├── actions-cache/      Marketplace action clones
├── cache/              actions/cache filesystem cache
├── secrets/            <hash>.json per workspace
└── workflow-cache/     Remote reusable workflow clones

/tmp/runner-sandboxes/
└── <run-id>/           Per-run sandbox workspaces (auto-cleaned)

Workspace-local state

.stax/
├── vault.json           Repo-backed SOPS / vault binding, committed when used
├── sync.json            GitHub sync + deployment ledger config
├── issues.json          Local GitHub issue cache
├── sync-log.jsonl       Sync audit log
└── deployments.jsonl    Deployment ledger records

Multi-workspace setups

Each instance of the runner serves exactly one workspace. To support several at once, run multiple instances on different ports:

PORT=4800 RUNNER_WORKSPACE=/repos/web   stax runner start
PORT=4801 RUNNER_WORKSPACE=/repos/api   stax runner start
PORT=4802 RUNNER_WORKSPACE=/repos/infra stax runner start

Each instance has its own .artifacts/ directory, its own secrets file, and its own sandbox tree (the sandbox base directory is shared, but per-run subdirectories never collide).