Secrets and registries

Credentials are saved under Credentials in the dashboard and encrypted with your organization’s own key, as described in How keys are stored. They cannot be viewed after you save them. A value is decrypted only when a replica starts.

Private images

Save a registry login under Credentials → Docker registries: a name, the registry host such as ghcr.io, a username, and a password or token. Surfra checks the login when you save it.

Attach it by name:

import surfra

app = surfra.App("private-model")
app.deploy(
    image="ghcr.io/me/private-model:1",
    entrypoint="app.py",
    registry=surfra.Credentials.Docker("ghcr"),
    autoscale={...},
)

In the dashboard, choose the registry next to Container image.

Not every provider can pull private images. The dashboard shows which rows block it, and Machines and providers lists them.

Credential stores

A credential store copies secrets into the replica’s environment when it starts. Save one under Credentials → Credential stores.

Kind	What it does
Doppler	Downloads the config for a project and environment at start
Cloudflare	Uses a Cloudflare token
Generic	Copies the saved values as environment variables

app.deploy(
    ...,
    registry=surfra.Credentials.Doppler("prod-secrets"),
)

Credentials.Doppler, Credentials.Cloudflare, and Credentials.Generic all take the name you saved. An app can have one registry login and one credential store. To attach both, pass a dict:

registry={"docker_secret_id": "ghcr", "secret_id": "prod-secrets"}

Plain environment variables

env sets string variables on every replica. It suits configuration such as a model id. For tokens, prefer a credential store. The dashboard and the generated SDK code mask values whose names look like secrets, such as HF_TOKEN or OPENAI_API_KEY.

app.deploy(..., env={"MODEL_ID": "Qwen/Qwen3-0.6B", "HF_TOKEN": "hf_..."})

API keys

API keys authenticate the SDK, the CLI, and gateway calls. Create them under Credentials → API Keys. A replica never receives your API key. It gets a token that can only report on its own work.