Custom Environment Variables

Custom env is a JSON record of extra environment variables Runaway injects into every runner. You set it on a runner profile, so every workload referencing that profile shares the same variables. The common use is pointing package managers at your own registry proxies, so jobs pull dependencies from your network instead of the public internet.

{
  "npm_config_registry": "http://verdaccio.lan:4873",
  "PIP_INDEX_URL": "http://devpi.lan:3141/root/pypi/+simple/",
  "GOPROXY": "http://athens.lan:3000"
}

Validation rules

Runaway validates the record when you save the runner profile:

• Keys must match ^[A-Za-z_][A-Za-z0-9_]*$ — a letter or underscore followed by letters, digits, or underscores.
• Each value is at most 4 KB.
• At most 32 keys.
• At most 32 KB total across all keys and values.
• Reserved keys — keys that control runner registration or carry credentials are refused at validation, then filtered again at spawn time.

Merge order

Runaway builds each runner’s environment in three layers, last writer wins:

Note

1. Runaway’s base runner contract — the variables the runner image needs to register and run.
2. Ecosystem cache defaults — the variables that point yarn, npm, pnpm, pip, Go, and cargo at the persistent /cache volume.
3. Your custom env — applied last, so you win on any key you set.

Reserved keys are the one exception: filtered out regardless of layer, so custom env cannot override the base contract’s auth or registration variables.

Do not put secrets here

Custom env is stored as plaintext and logged keys-only. It is the right place for registry URLs, proxy hosts, and non-sensitive tuning — not for tokens, passwords, or API keys.

Caution

A dedicated secrets store is not supported yet. Until it lands, keep secrets out of custom env. For private runner-image pulls, use the encrypted credential flow in Private runner images instead.

Pointing tools at your own registries

Runaway doesn’t bundle a registry proxy — it composes with whatever you already run. The recipes walk through wiring each one through custom env:

npm / pnpm via Verdaccio

pip via devpi

Go modules via Athens