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 | |---|---|---| | BETTER_AUTH_URL | http://localhost:5173 (dev) | The public URL of your hub. Required in production, and it must be an https:// URL — the hub refuses to boot otherwise. It builds login callback URLs, 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, BETTER_AUTH_URL doesn’t match the URL in your browser. Set it 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_PUBLIC_URL | falls back to BETTER_AUTH_URL | The public URL the GitHub webhook receiver registers deliveries under. Set it only when your public webhook-ingress hostname differs from your auth hostname (a split-hostname reverse-proxy deploy). Must be https:// in production. See Webhooks. | | 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.