Variables and connections

Use environment variables for app settings, API keys, and database connections. Locus resolves them when you deploy, so services can find each other without hardcoded addresses. Add variables in the dashboard or through the API. Redeploy after changes to make them available to your running app.

Set variables

Use PATCH to add or update values while keeping existing variables:

Update service variables

curl --fail-with-body -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"LOG_LEVEL": "info"}}' \
  "https://api.buildwithlocus.com/v1/variables/service/$SERVICE_ID"

PUT on the same route replaces all variables for the service. Keep secrets server-side and out of committed .locusbuild files.

Service-to-service references

Locus injects sibling service URLs automatically. A service named api gives other services these variables:

Variable	Use
`API_URL`	Public HTTPS requests, including browser calls
`API_INTERNAL_URL`	Internal server-to-server requests
`LOCUS_SERVICE_URL`	The current service’s own public URL

Names are uppercased, with non-alphanumeric characters replaced by underscores.

Template syntax

Use templates to connect a setting to a service or addon. 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. Wait until the addon is available before deploying a service that references it. Only services with explicit addon references receive those connection variables.

Full-stack .locusbuild example

This connects an API to Postgres and Redis, and a frontend to the API:

.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 multiple scopes, service variables take priority over environment variables, which take priority over addon variables.

Get resolved variables

Preview values before deploying:

Preview resolved variables

curl --fail-with-body \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.buildwithlocus.com/v1/variables/service/$SERVICE_ID/resolved"

Treat the response as sensitive; it can contain credentials. See the Build API reference for all variable operations.

Getting started

Features

Agent tools

Build with Locus

Checkout

Variables and connections

Set variables

Service-to-service references

Template syntax

Full-stack .locusbuild example

Variable scopes

Get resolved variables

​Set variables

​Service-to-service references

​Template syntax

​Full-stack .locusbuild example

​Variable scopes

​Get resolved variables

Set variables

Service-to-service references

Template syntax

Full-stack .locusbuild example

Variable scopes

Get resolved variables