Environment Variables and References

You can connect apps to databases, secrets, and other apps using environment references. Create the referenced resource first.

Reference	Value
`${{secret.API_KEY}}`	A workspace secret
`${{db.web-db.DATABASE_URL}}`	Database connection string
`${{db.cache.REDIS_URL}}`	Redis connection string
`${{db.web-db.HOST}}`	Database gateway hostname
`${{db.web-db.PORT}}`	Database gateway port
`${{db.web-db.USERNAME}}`	Database username
`${{db.web-db.PASSWORD}}`	Database password
`${{db.web-db.DATABASE}}`	Database name, where supported
`${{app.api.URL}}`	An app’s active deployment URL

Database fields are case-insensitive. URL is an alias for the connection string.

Pass References from the CLI or SDK

Single-quote references in shell commands so the shell passes them unchanged:

beam deploy --name web --dockerfile Dockerfile --port 8000 \
  --env DATABASE_URL='${{db.web-db.DATABASE_URL}}' \
  --env API_URL='${{app.api.URL}}' \
  --env API_KEY='${{secret.API_KEY}}'

from beam import Service

web = Service.from_dockerfile(
    "Dockerfile",
    name="web",
    port=8000,
    env={
        "DATABASE_URL": "${{db.web-db.DATABASE_URL}}",
        "API_URL": "${{app.api.URL}}",
        "API_KEY": "${{secret.API_KEY}}",
    },
)

Secret and database references must fill the entire value. App URLs can include a suffix, such as ${{app.api.URL}}/health.

Generated Values

${{secret(32)}} generates a 32-character secret and reuses it on later deployments. The length can be 1–512; an optional second argument sets the alphabet. ${{randomInt(10, 100)}} generates an integer from 10 through 99. With no arguments, randomInt() uses 0–99.

Update an Existing App

Edit references in the dashboard, or use MCP’s set_env and connect_services tools. Both deploy a new version. update_secret takes effect on the next container start. For build-time secrets, use Image.with_secrets().

Start Here

Customizing Container Images

Managing Data

Scaling & Performance

Sandboxes

Endpoints and Web Servers

Task Queues

One-Off Functions

Hosting Containers

Operations

Advanced Topics

Self-Hosting

Resources

Security

Environment Variables and References

Pass References from the CLI or SDK

Generated Values

Update an Existing App

​Pass References from the CLI or SDK

​Generated Values

​Update an Existing App

Pass References from the CLI or SDK

Generated Values

Update an Existing App