Environments & Variables

An environment is a named set of variables, such as dev, staging or production. It belongs to a project and sets the variables that services receive at startup.

Two scopes

• Global: the project's variables, shared by its services. A global environment can also name the default agent for services that specify none.
• Service: variables belonging to one service. They attach to a global environment and apply only while that one is active.

An environment can inherit from others. The values it redefines take precedence, and the other values come from its parents.

Resolution order

Strongest first:

Machine-local overrides
        ▼
Service-scoped variables
        ▼
Global environment, then its parents

Machine-local overrides stay on the machine and are never synced. Use them to change a value on your machine without changing it for the whole team.

Composing a value

A variable has three parts: prefix, value and suffix. Runeya joins them end to end. Each part can reference another variable of the environment with {{environment.NAME}}:

DB_HOST      = db.local
DATABASE_URL = postgres://{{environment.DB_HOST}}:5432/app

Store a shared value once, then reference it: changing it in one place changes it everywhere. A reference that leads nowhere is passed to the service as written, so the mistake shows.

Variables provided by Runeya

Runeya fills these references itself, in the same places as yours:

Reference	Value
{{service.NAME}}, {{service.ID}}	The service
{{service.PORT}}, {{service.PORT_2}}…	Its declared ports, in order
{{service.URL}}, {{service.URL_2}}…	One address per port: the local domain declared on that port, otherwise the machine address and the port (http://localhost:3000 on your machine, the machine IP in local network mode)
{{service.BASE_URL}}	The "base URL" entered in its configuration
{{service.CWD}}	Its working directory
{{project.NAME}}	The project
{{runeya.ENV_NAME}}	The active environment
{{runeya.HOST}}	The address Runeya listens on
{{agent.NAME}}	The agent's name
{{agent.HOST_LAN}}, {{agent.OS}}, {{agent.HOME}}	The machine's local network IP, operating system and home directory
{{services.<name>.PORT}}, .URL, .BASE_URL, .NAME, .ID	Another service of the same project

Agent values and {{service.CWD}} come from the machine that runs the service.

For another service, <name> is its name in lowercase with dashes: "API Gateway" gives {{services.api-gateway.PORT}}. If two services of the project give the same name, neither can be referenced this way.

The dashboard also uses these references to draw the links between services: a service that references services.api depends on api.

Variables to fill in

Two boxes say a variable must have a value:

• Required: a service of this environment does not start while the final value is empty. Runeya names the missing variables.
• Override-only: the variable has no shared value. Each machine provides its own, such as a local path or a personal token.

When you activate an environment, or after a refused start, an assistant asks for the missing values. A variable's description helps whoever has to fill it in.

Secrets

A variable marked secret is encrypted on disk, masked in the UI, and never logged. It is decrypted only when the process is about to start. What an AI tool can read of it is described in External AI tools.

System variables

Runeya does not copy your shell's variables into the processes it starts. A service gets the variables its environments declare, plus the ones you explicitly allow. Tokens and keys set in your terminal are therefore not passed to your services unless you allow them.