Environments & Variables

Runeya provides a hierarchical and flexible environment variable system, allowing you to cleanly manage dev, staging, and production configurations from a single interface.

Concepts

Variable

A variable is a KEY=VALUE pair identified internally by a UUID. It is always defined within an environment.

Global Environment

A global environment is a named group of variables (e.g. dev, production). It is shared across all services that reference it.

Service-scoped Environment

Each service can have its own overrides. These overrides apply on top of the attached global environment.

Variable Resolution

Resolution follows a strict priority order (highest to lowest):

Service-scoped overrides
        ▼
Variables from the attached global environment
        ▼
System environment variables (explicit passthrough)

TIP

If the same key appears at multiple levels, the highest value in the hierarchy wins.

Creating a Global Environment

1. Go to Settings → Environments
2. Click "+ Environment"
3. Name it (e.g. development, production)
4. Add variables

Attaching an Environment to a Service

In the service configuration, Environment tab:

1. Select the global environment to activate
2. Set the activateOn option: when this environment activates
3. Add service-specific overrides as needed

Secret Variables

Values marked as secret are:

• Encrypted with AES-256-GCM before being written to disk
• Masked in the interface (••••••••)
• Never sent in plaintext in logs

To create a secret variable, enable the Secret toggle during creation.

DANGER

Never commit your services.json file if it contains unencrypted secrets. Runeya encrypts them automatically — don't bypass this mechanism.

System Environment Passthrough

By default, Runeya does not inject system variables (process.env) into child processes. Only variables explicitly defined in Runeya environments are passed through, plus an explicit allowlist of safe system variables.

This approach prevents accidental leaks of tokens, API keys, or credentials present in the shell environment.

Complete Configuration Example

Global environment "development":
  DATABASE_URL = postgres://localhost:5432/myapp_dev
  REDIS_URL    = redis://localhost:6379
  LOG_LEVEL    = debug

Service "api" — overrides:
  PORT         = 3000
  LOG_LEVEL    = verbose   ← overrides the global value
  API_SECRET   = ••••••••  ← encrypted secret value

Result injected into the process:

DATABASE_URL=postgres://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
LOG_LEVEL=verbose
PORT=3000
API_SECRET=<decrypted value>