Storing Secrets

Storing Secrets and Environment Variables

Bind workspace secrets by name. Containers/pods, functions, endpoints, task queues, and image builds receive real values as plaintext environment variables. These workloads do not require credential hosts; adding hosts does not enable proxying for them. Only VM and sandbox runtime bindings use brokered placeholders, with the explicit token exceptions below. To create a secret in the dashboard, go to Settings → Secrets, click Create secret, and enter a name and value. You can update or delete secrets from the same page. You can also manage secrets through the CLI:

$ beam secret create AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Created secret with name: 'AWS_ACCESS_KEY'

Using Secrets

Serverless functions and endpoints access the real value through an environment variable:

from beam import function


@function(secrets=["AWS_ACCESS_KEY"])
def handler():
    import os

    my_secret = os.environ["AWS_ACCESS_KEY"]
    return {"configured": bool(my_secret)}

To give a secret a different variable name, or to set secrets and other environment variables with beam deploy or the dashboard, use environment references such as ${{secret.AWS_ACCESS_KEY}}.

Passing Secrets to `on_start`

If your app used an on_start function, secrets can be passed to that function as well.

from beam import endpoint


# This has access to secrets passed down in the handler
def load_models():
    import os

    my_secret = os.environ["AWS_ACCESS_KEY"]
    return my_secret


@endpoint(
    secrets=["AWS_ACCESS_KEY"],
    on_start=load_models,
)
def handler(context):
    return {}

Brokered secrets for VMs and sandboxes

Give a runtime secret the hostnames that may receive it, then bind it by name:

beam secret create OPENAI_API_KEY "$REAL_OPENAI_API_KEY" --host api.openai.com
beam vm new agentbox --secret OPENAI_API_KEY --block-network

SDK bindings remain secrets=["OPENAI_API_KEY"]. For example:

from beam import Sandbox

sb = Sandbox(secrets=["OPENAI_API_KEY"], block_network=True).create()

Inside the VM or sandbox, the variable contains an opaque beam_secret_... placeholder. Use it directly in an HTTPS request header:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

The worker substitutes the real key only for matching credential hosts, verifies upstream TLS, and scrubs literal key values from response headers, bodies, and WebSocket messages. HTTP clients that pass the variable directly in Authorization or x-api-key headers need no auth changes; streaming responses are supported. On other hosts, the placeholder is never exchanged for the key. Repeat --host for multiple hostnames, up to 64 rules. *.example.com matches subdomains, excluding example.com itself. Credential host rules cannot contain schemes, ports, paths, IPs, or CIDRs. Existing secrets need host rules before binding to a VM or sandbox; add them with beam secret update NAME VALUE --host HOST. Brokered secret values must contain 1–16384 bytes.

Credential hosts and outbound access

Credential host rules control where a key can be substituted. Network rules control what the guest can reach:

Network setting	Behavior
Default	Outbound access stays open; credentials are substituted only on approved hosts.
`block_network=True` with brokered secrets	Only the union of bound credential hosts is reachable.
Explicit `allow_list`	Only listed destinations are reachable. Its hostname rules must cover every credential host; secrets do not widen it.

The same settings apply to sandbox networking. Both creation and per-exec bindings require hosts covered by the guest’s explicit allowlist, when present. IP/CIDR entries alone do not cover credential hostnames. Proxied private, loopback, and link-local destinations remain blocked even with an explicit IP/CIDR rule.

Rotation and compatibility

beam secret update OPENAI_API_KEY "$NEW_OPENAI_API_KEY"

The placeholder stays stable across value changes and VM restarts. New requests use the rotated value after the worker’s 15-second cache expires, without restarting the guest. Omitting --host preserves host rules; supplying it replaces them.

Substitution is literal and header-only. Query/body credentials, local signing, hashing, and encoding the placeholder are unsupported. For Basic auth, store the base64 credential and send Authorization: Basic $SECRET; do not encode the placeholder.
Brokering supports HTTPS on port 443; plain HTTP to a credential-bound host is blocked. Certificate-pinned clients cannot use this TLS interception. The guest receives trusted CA certificates automatically; Docker containers need explicit CA configuration.
Brokered WebSocket messages are limited to 16 MiB. Compressed upstream responses are rejected when they cannot be scrubbed.
Serverless and image-build secrets retain their existing plaintext behavior. Workspace callers with permission can still retrieve values using beam secret show or secret-management APIs.

VMs and sandboxes no longer inherit your workspace token. If an agent needs the Beam CLI inside the guest, explicitly bind a BETA9_TOKEN or BEAM_TOKEN secret. These token bindings are plaintext opt-ins and do not require credential host rules. Self-hosted deployments, including agent-managed workers, must upgrade worker images before using hostname allowlists or brokered secrets.

MCP tools

create_secret and update_secret accept name, value, and optional hosts, for example {"name":"OPENAI_API_KEY","value":"<real-key>","hosts":["api.openai.com"]}. On update, omit hosts to preserve the current list, supply a list to replace it, or pass [] to clear it. list_secrets returns hosts and placeholders without values. Bind VM runtime secrets under create_vm.spec.secrets or vm_exec.secrets.

CLI Commands

List Secrets

beam secret list

Lists names, allowed hosts, stable placeholders, and timestamps, without values. Use beam secret list --format json for structured output.

Create a Secret

beam secret create NAME VALUE [--host HOST ...]

$ beam secret create AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Created secret with name: 'AWS_ACCESS_KEY'

If your secret contains special characters, you may need to escape them with a backslash. For example, a$b would need to be a\$b.

Show a Secret

beam secret show [KEY]

$ beam secret show AWS_ACCESS_KEY

=> Secret 'AWS_ACCESS_KEY': ASIAY34FZKBOKMUTVV7A

Update a Secret

beam secret update NAME VALUE [--host HOST ...] [--clear-hosts]

$ beam secret update AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Modified secret 'AWS_ACCESS_KEY'

modify is an alias of update. Omit --host to preserve host rules, repeat it to replace them, or use --clear-hosts to remove them. A secret without hosts cannot be bound as a brokered runtime secret. Serverless containers pick up a changed value on their next start; brokered requests use the 15-second refresh described above.

Delete a Secret

beam secret delete [KEY]

$ beam secret delete AWS_ACCESS_KEY

=> Deleted secret 'AWS_ACCESS_KEY'

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Storing Secrets

Storing Secrets and Environment Variables

Using Secrets

Passing Secrets to `on_start`

Brokered secrets for VMs and sandboxes

Credential hosts and outbound access

Rotation and compatibility

MCP tools

CLI Commands

List Secrets

Create a Secret

Show a Secret

Update a Secret

Delete a Secret

​Storing Secrets and Environment Variables

​Using Secrets

​Passing Secrets to on_start

​Brokered secrets for VMs and sandboxes

​Credential hosts and outbound access

​Rotation and compatibility

​MCP tools

​CLI Commands

​List Secrets

​Create a Secret

​Show a Secret

​Update a Secret

​Delete a Secret

Storing Secrets and Environment Variables

Using Secrets

Passing Secrets to `on_start`

Brokered secrets for VMs and sandboxes

Credential hosts and outbound access

Rotation and compatibility

MCP tools

CLI Commands

List Secrets

Create a Secret

Show a Secret

Update a Secret

Delete a Secret