Variables and connections

Use environment variables for app settings, API keys, and database connections. Locus resolves them when you deploy, so services find each other without hardcoded addresses.

How it works

Each service gets its sibling services’ URLs automatically. To reach an addon or another setting, a service references it with a template, and Locus fills in the value at deploy time.

Set variables

Add variables in the dashboard or through the API, then redeploy so your running app picks them up.

PATCH /v1/variables/service/{serviceId} adds or updates values and keeps the rest.
PUT on the same route replaces every variable for the service.
Keep secrets server-side and out of committed .locusbuild files.

Service-to-service references

For a service named api, other services get:

API_URL for public HTTPS requests, including browser calls.
API_INTERNAL_URL for internal server-to-server requests.

Every service also gets LOCUS_SERVICE_URL, its own public URL. Names are uppercased, with non-alphanumeric characters replaced by underscores.

Template syntax

For example, set DATABASE_URL to ${{db.DATABASE_URL}} to connect to a Postgres addon named db.

Template	Value
`${{serviceName.URL}}`	Public service URL
`${{serviceName.INTERNAL_URL}}`	Internal service URL
`${{serviceName.PORT}}`	Service port
`${{addonName.DATABASE_URL}}`	Postgres connection string
`${{addonName.REDIS_URL}}`	Redis connection string

Addon templates also expose HOST and PORT; Postgres adds USERNAME and DATABASE.
Only services with an explicit addon reference receive its connection variables.
Wait until the addon is available before deploying a service that references it.

Full-stack .locusbuild example

This connects an API to Postgres and Redis, and a frontend to the API, as in the diagram above:

.locusbuild

{
  "services": {
    "api": {
      "path": "backend",
      "port": 8080,
      "healthCheck": "/health",
      "env": {
        "DATABASE_URL": "${{db.DATABASE_URL}}",
        "REDIS_URL": "${{cache.REDIS_URL}}",
        "FRONTEND_URL": "${{web.URL}}"
      }
    },
    "web": {
      "path": "frontend",
      "port": 8080,
      "healthCheck": "/",
      "env": {
        "API_URL": "${{api.URL}}",
        "API_INTERNAL_URL": "${{api.INTERNAL_URL}}"
      }
    }
  },
  "addons": {
    "db": { "type": "postgres" },
    "cache": { "type": "redis" }
  }
}

Variable scopes

When the same name exists in more than one scope, service variables win over environment variables, which win over addon variables.

Get resolved variables

To preview the final values before deploying, use GET /v1/variables/service/{serviceId}/resolved. Treat the response as sensitive: it can contain credentials. See the Build API reference for every variable operation.

Getting started

Features

Agent tools

Build with Locus

Checkout

Variables and connections

How it works

Set variables

Service-to-service references

Template syntax

Full-stack .locusbuild example

Variable scopes

Get resolved variables

Next steps

Addons

Services

​How it works

​Set variables

​Service-to-service references

​Template syntax

​Full-stack .locusbuild example

​Variable scopes

​Get resolved variables

​Next steps

Addons

Services

How it works

Set variables

Service-to-service references

Template syntax

Full-stack .locusbuild example

Variable scopes

Get resolved variables

Next steps