Variables & Wiring

Variables are set per-service and injected as environment variables into the container at deploy time. Locus also auto-injects service-to-service URLs and addon connection strings — no manual wiring needed.

Set variables

Replace all (PUT)

Replaces all existing variables on the service.

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"LOCUS_API_KEY": "claw_...", "LOG_LEVEL": "info"}}' \
  "https://api.buildwithlocus.com/v1/variables/service/$SERVICE_ID"

Merge (PATCH)

Adds or updates variables while keeping existing ones.

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

After setting variables, trigger a new deployment for them to take effect.

Get resolved variables

Returns all variables with addon connection strings and auto-injected sibling service URLs resolved.

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

{
  "variables": {
    "LOCUS_SERVICE_URL": "https://svc-abc123.buildwithlocus.com",
    "API_URL": "https://svc-def456.buildwithlocus.com",
    "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
  }
}

Variable scopes

Variables are resolved in this order — higher priority wins when the same key exists at multiple scopes:

Scope	Priority	Description
Service variables	Highest	Set directly on a service via PUT or PATCH
Environment variables	Medium	Shared across all services in an environment
Addon variables	Lowest	Auto-injected connection strings (e.g. `DATABASE_URL`, `REDIS_URL`)

Service-to-service references

When an environment has multiple services, Locus automatically injects URL variables for every sibling service at deploy time. No manual wiring or linking is needed.

Auto-injected variables

For each sibling service in the same environment:

Variable	Value	Use case
`{SERVICE_NAME}_URL`	`https://svc-{id}.buildwithlocus.com`	Public URL for browser/client-side calls
`{SERVICE_NAME}_INTERNAL_URL`	`http://service-{id}.locus.local:{port}`	Internal URL for server-to-server calls (faster, no TLS overhead)
`LOCUS_SERVICE_URL`	`https://svc-{id}.buildwithlocus.com`	The current service’s own public URL (useful for CORS config, callback URLs)

The service name is uppercased with non-alphanumeric characters replaced by underscores. For example, a service named api produces API_URL and API_INTERNAL_URL.

Template syntax

You can reference sibling services and addons in variable values using template syntax. Templates are resolved at deployment time.

Service templates

Template	Resolves to	Example
`${{serviceName.URL}}`	Public URL	`https://svc-xxx.buildwithlocus.com`
`${{serviceName.INTERNAL_URL}}`	Internal URL	`http://service-xxx.locus.local:8080`
`${{serviceName.PORT}}`	Service port	`8080`

Addon templates

Template	Type	Example
`${{addonName.DATABASE_URL}}`	Postgres	`postgresql://user:pass@host:5432/dbname`
`${{addonName.HOST}}`	Postgres / Redis	Managed host endpoint
`${{addonName.PORT}}`	Postgres / Redis	`5432` or `6379`
`${{addonName.USERNAME}}`	Postgres	`appuser`
`${{addonName.DATABASE}}`	Postgres	`appdb`
`${{addonName.REDIS_URL}}`	Redis	`redis://host:6379/0`

Addon templates (e.g., ${{db.DATABASE_URL}}) require the addon status to be available before deployment. Use GET /v1/variables/service/:id/resolved to preview resolved values.

Full-stack .locusbuild example

A .locusbuild file using all template types together:

{
  "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" }
  }
}

Addon variables require explicit references. To connect a service to an addon, add the addon’s variables to your service’s env using template syntax: "DATABASE_URL": "${{addonName.DATABASE_URL}}". Only services that explicitly reference an addon will receive its connection variables.

Getting started

Features

Agent tools

Build with Locus

Checkout

Set variables

Replace all (PUT)

Merge (PATCH)

Get resolved variables

Variable scopes

Service-to-service references

Auto-injected variables

Template syntax

Service templates

Addon templates

Full-stack .locusbuild example

​Set variables

​Replace all (PUT)

​Merge (PATCH)

​Get resolved variables

​Variable scopes

​Service-to-service references

​Auto-injected variables

​Template syntax

​Service templates

​Addon templates

​Full-stack .locusbuild example

Set variables

Replace all (PUT)

Merge (PATCH)

Get resolved variables

Variable scopes

Service-to-service references

Auto-injected variables

Template syntax

Service templates

Addon templates

Full-stack .locusbuild example