Environment Variables

The environment variables the hub reads at boot. Set them in your .env file (or your platform’s secret store). The agent reads its connection details from the enrollment flow, not from these — the one exception is DOCKER_HOST, which tells the agent which Docker daemon to drive.

Required

| Variable | Default | Purpose | |---|---|---| | RUNAWAY_MASTER_KEY | — | A 32-byte key, base64-encoded, used to encrypt your GitHub tokens and other secrets at rest (AES-256-GCM). Generate it with openssl rand -base64 32. | | BETTER_AUTH_SECRET | — | A random string of 32 or more characters used to sign your login session cookie. Generate it with openssl rand -base64 32. |

Caution

Back up RUNAWAY_MASTER_KEY. It is the only thing that can decrypt the GitHub tokens, registry passwords, and webhook secrets stored in your database. If you lose it, every stored secret becomes unreadable and you’ll have to re-enter all of them. Keep a copy somewhere safe — see Backups.

Required in production

| Variable | Default | Purpose | |---|---|---| | RUNAWAY_HUB_URL | unset (dev) | The canonical public URL of your hub. Required in production, and it must be an https:// URL — the hub refuses to boot otherwise. The three parties that reach the hub — browser, GitHub, and agents — all default to this one URL. It gates the session cookie’s Secure flag and is the trusted origin for CSRF checks. |

If sign-in succeeds but you’re bounced back to the login page, the auth origin doesn’t match the URL in your browser. Set RUNAWAY_HUB_URL (or RUNAWAY_APP_URL, if the browser reaches a different origin) to the exact user-facing HTTPS URL and restart. See TLS and reverse proxy.

Optional

| Variable | Default | Purpose | |---|---|---| | PORT | 3000 | The port the hub’s API and web UI listen on. | | RUNAWAY_LOCAL_AGENT_TOKEN | unset | A pre-shared key the compose-bundled local agent uses to auto-enroll on first boot. When set, the hub seeds a local host carrying this token’s hash. Leave it unset for an orchestrator-only hub that enrolls only remote agents. Generate it with openssl rand -base64 32. | | RUNAWAY_APP_URL | falls back to RUNAWAY_HUB_URL | Override for the browser/auth origin only — the auth baseURL and CSRF trusted origin. Set it only when the browser reaches the hub at a different origin than the canonical URL. Must be https:// in production. | | RUNAWAY_WEBHOOK_URL | falls back to RUNAWAY_HUB_URL | Override for the public origin the GitHub webhook receiver registers deliveries under. Set it only when your webhook-ingress hostname differs from the canonical URL (a split-hostname reverse-proxy deploy). Must be https:// in production. See Webhooks. | | RUNAWAY_AGENT_URL | falls back to RUNAWAY_HUB_URL | Override for the address agents dial back on, baked into the enrollment snippet shown when you add a host. Set it only when agents reach the hub at a different address (e.g. an internal LAN). May be a plain http:// URL — unlike the others, it is not https-gated in production. | | RUNAWAY_AGENT_IMAGE | the agent image pinned to the hub’s version | The container image named in the enrollment snippet shown when you add a host. Override it only if the agent image is published under a different registry or namespace. | | LOG_LEVEL | info | Log verbosity. One of fatal, error, warn, info, debug, trace. | | DATABASE_URL | file:./data/app.db | The path to the SQLite database file. Keep it on the persistent /app/data volume so state survives upgrades. | | DOCKER_HOST | /var/run/docker.sock | The Docker daemon endpoint the agent drives. The hub holds no Docker socket of its own; this is the agent’s daemon. |

Generating secrets

Seed a fresh .env with all three secrets at once:

{
  echo "RUNAWAY_MASTER_KEY=$(openssl rand -base64 32)"
  echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)"
  echo "RUNAWAY_LOCAL_AGENT_TOKEN=$(openssl rand -base64 32)"
} >> .env

Note

RUNAWAY_LOCAL_AGENT_TOKEN is only needed when you run the bundled local agent (the single-machine compose stack). An orchestrator-only hub that enrolls remote agents can leave it unset.