Skip to main content
Most AI applications need credentials to call external services — Hugging Face tokens for gated models, database URLs, third-party API keys, or private Docker registry credentials. Secrets let you store these values securely on fal instead of hardcoding them in your code or committing them to version control. Once set, secrets are encrypted and their values are never displayed again. Secrets are injected into your runners as environment variables when they start. You access them via os.getenv() just like any other environment variable. Secrets can be scoped to specific environments (e.g., different API keys for staging vs production) and are separate from the platform environment variables that fal injects automatically.

​
Setting Secrets

You can set secrets from the Dashboard, the CLI, or the Python SDK.

​
Dashboard

Navigate to Dashboard > Secrets to create, edit, and delete secrets. Select the environment (e.g., main, staging) from the dropdown, then add your key-value pairs. Values are encrypted and never displayed after creation.

​
CLI

fal secrets set HF_TOKEN=hf_abc123 DATABASE_URL=postgres://...
You can set multiple secrets in a single command. To target a specific environment, use the --env flag: 
fal secrets set HF_TOKEN=hf_staging_token --env staging

​
Python SDK

from fal.api import SyncServerlessClient

client = SyncServerlessClient()
client.secrets.set("HF_TOKEN", "hf_abc123")
client.secrets.set("HF_TOKEN", "hf_staging_token", environment_name="staging")

​
Accessing Secrets at Runtime

Secrets are available as standard environment variables inside your app. Use os.getenv() to read them in setup(), endpoint handlers, or anywhere else in your runner code. 
import os
import fal

class MyApp(fal.App):
    def setup(self):
        import huggingface_hub
        huggingface_hub.login(token=os.getenv("HF_TOKEN"))
        self.pipe = load_gated_model()

    @fal.endpoint("/")
    def generate(self, prompt: str) -> dict:
        result = self.pipe(prompt)
        return {"output": result}
Secrets are injected when a runner starts. If you update a secret, running runners keep the old value. Only new runners (from a new deploy or scale-up) pick up the updated value. To force all runners to use the new value, redeploy your app with fal deploy.

​
Secrets During Build

For security, secrets are not available as environment variables during the image build stage. The built image is cached and may be shared across environments, so injecting secrets into the build would risk leaking them. Instead, use the ${} substitution syntax in your requirements list. fal replaces ${SECRET_NAME} with the secret value at build time without exposing it in the cached image. 
import fal

class MyApp(fal.App):
    requirements = [
        "git+https://${GITHUB_TOKEN}@github.com/myorg/private-package"
    ]
This is the only way to use secrets during dependency installation. The substitution happens server-side before pip runs, and the token is not stored in the final image.

​
Docker Build Secrets

If you use a custom container image, you can pass build-time secrets via the secrets parameter on ContainerImage. These are mounted as Docker build secrets (via --mount=type=secret) and are available inside your Dockerfile during the build but not persisted in the final image. 
from fal.container import ContainerImage

image = ContainerImage.from_dockerfile_str(
    """
    FROM python:3.11
    RUN --mount=type=secret,id=hf_token cat /run/secrets/hf_token
    """,
    secrets={"hf_token": os.getenv("HF_TOKEN")},
)

​
Secrets Per Environment

Secrets can be scoped to specific environments, letting you use different credentials for development, staging, and production. When you deploy to an environment, the runner receives the secrets set for that environment. 
fal secrets set DATABASE_URL=postgres://prod-db.example.com/app
fal secrets set DATABASE_URL=postgres://staging-db.example.com/app --env staging
If a secret is not set for a specific environment, the runner does not fall back to the main environment’s value — the variable is simply not present.

​
Managing Secrets

​
Listing

List your secrets to see their names, environments, and creation dates. Values are never displayed. 
fal secrets list
NameEnvCreated At
HF_TOKENmain2026-01-15 10:30:00
DATABASE_URLmain2026-01-15 10:31:00
To list secrets for a specific environment: 
fal secrets list --env staging

​
Removing

Delete a secret to prevent it from being injected into new runners: 
fal secrets unset HF_TOKEN
fal secrets unset HF_TOKEN --env staging
Running runners are not affected by deletion. The secret is removed from new runners only.