Environment Variables and References

Apps read configuration from environment variables. A variable can hold a plain value, such as LOG_LEVEL=info, or a reference that Beam fills in when you deploy, such as a secret, a database connection string, or another app’s URL.

Create a Secret

Store API keys and other credentials as workspace secrets so they stay out of your code. In the dashboard, go to Settings → Secrets, click Create secret, and enter a name and value. Or create one from the CLI:

beam secret create OPENAI_API_KEY sk-...

See Storing Secrets to list, update, and delete secrets.

Set Environment Variables

Set variables in your code or when you deploy. To pass a secret, use ${{secret.NAME}} as the value:

from beam import endpoint


@endpoint(
    name="web",
    env={
        "LOG_LEVEL": "info",
        "OPENAI_API_KEY": "${{secret.OPENAI_API_KEY}}",
    },
)
def handler():
    ...

beam deploy app.py:handler \
  --env LOG_LEVEL=info \
  --env OPENAI_API_KEY='${{secret.OPENAI_API_KEY}}'

Single-quote references in shell commands so the shell passes them unchanged. Values from --env are added to the env in your code and replace any variable with the same name. Your app reads them like any other environment variable:

import os

api_key = os.environ["OPENAI_API_KEY"]

To change the variables of a deployed app in the dashboard, open the deployment and go to the Config tab. Edit Environment variables, one KEY=VALUE per line, such as OPENAI_API_KEY=${{secret.OPENAI_API_KEY}}. Stage the change, then click Deploy changes to deploy a new version.

To expose a secret under its own name, you can pass secrets=["OPENAI_API_KEY"] to the decorator instead of setting env.

Reference Databases and Apps

References also connect an app to a database or another app. Beam checks references when you deploy, so create the database or deploy the other app first.

Reference	Value
`${{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 stable URL, which routes to its latest deployment

Database fields are case-sensitive, so write them in uppercase. URL is an alias for the connection string.

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 be the entire value. App URLs and randomInt() can be part of a longer value, such as ${{app.api.URL}}/health.

Generated Values

${{secret(32)}} generates a 32-character secret on the first deploy and saves it as a workspace secret named after the app and the variable. For example, SESSION_KEY on the web app is saved as WEB_SESSION_KEY. Later deploys reuse it. The length can be 1–512, and an optional second argument sets the alphabet, as in ${{secret(16, "abcdef0123456789")}}. ${{randomInt(10, 100)}} inserts an integer from 10 through 99, picked again on every deploy. randomInt(100) and randomInt() both use 0–99.

Update Variables and Secrets

You can also change variables with MCP’s set_env and connect_services tools, which deploy a new version. A new secret value, set in the dashboard, with beam secret update, or with MCP’s update_secret, takes effect the next time a serverless container starts. Brokered VM/sandbox runtime secrets refresh on the next request after the worker’s 15-second cache expires, without restarting the guest. For plaintext build-time secrets, use Image.with_secrets().

Start Here

Sandboxes

Virtual machines

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Environment Variables and References

Create a Secret

Set Environment Variables

Reference Databases and Apps

Generated Values

Update Variables and Secrets

​Create a Secret

​Set Environment Variables

​Reference Databases and Apps

​Generated Values

​Update Variables and Secrets

Create a Secret

Set Environment Variables

Reference Databases and Apps

Generated Values

Update Variables and Secrets