> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables and References

> Connect apps, databases, and secrets without copying credentials

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:

```bash theme={null}
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}}'
```

```python theme={null}
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()`.