Environment variables and secrets

Declare non-sensitive environment variables in squid.yaml. Store credentials, private RPC URLs, and API keys as organization secrets.

Variable scopes

Location	Available to
`deploy.env`	`init`, all processors, and API
`deploy.init.env`	Initialization and migrations only
`deploy.processor.env`	A single processor service
Each named processor’s `env`	That named processor only
`deploy.api.env`	API service only

Service-level values override deployment-level values.

squid.yaml

deploy:
  env:
    NETWORK: ethereum-mainnet
  init:
    cmd: ["sqd", "migration:apply"]
    env:
      SQD_INFO: "sqd:migration"
  processor:
    cmd: ["sqd", "process:prod"]
    env:
      SQD_INFO: "sqd:processor"
  api:
    cmd: ["sqd", "serve:prod"]
    env:
      SQD_INFO: "sqd:graphql-server"

Organization secrets

Secrets belong to one organization. A deployment can only reference secrets from its own organization. Create or update a secret in the Cloud console or CLI:

sqd secrets set FAST_RPC_ENDPOINT_URL <value> -o <organization>

The published CLI currently requires the positional value. Use the Cloud console when the secret must not appear in a command or shell history. Reference the secret from an environment variable:

squid.yaml

deploy:
  processor:
    cmd: ["sqd", "process:prod"]
    env:
      RPC_ENDPOINT: "${{ secrets.FAST_RPC_ENDPOINT_URL }}"

Access it in application code:

const endpoint = process.env.RPC_ENDPOINT
if (endpoint == null) {
  throw new Error('RPC_ENDPOINT is required')
}

Do not commit secret values to squid.yaml, .env, examples, logs, or support messages.

Apply a changed secret

Creating, updating, or removing a secret does not change the environment of a running process. Restart each affected slot:

sqd restart -n <name> -s <slot>

If several slots are running, restart each one that consumes the secret. Restarting by tag only affects the slot currently carrying that tag.

Missing secret behavior

A deployment fails if its manifest references a secret that does not exist in the selected organization. Check the organization and secret names:

sqd secrets list -o <organization>

Secret and environment-variable names must start with a letter or underscore and contain only letters, numbers, or underscores.

Cloud-provided database variables

When the Postgres addon is enabled, Cloud injects and overrides:

DB_SSL
DB_HOST
DB_PORT
DB_NAME
DB_USER
DB_PASS
DB_URL

Do not set these variables to an external database in the same deployment. Remove the Postgres addon if the squid should use a separately managed database.

Works locally, but the variable is missing in Cloud

Local .env files are not automatically published. Check:

The variable exists in the appropriate manifest env section.
Sensitive values use an organization secret.
The secret exists in the deployment’s organization.
The running slot was restarted after a secret change.
The processor or API command does not load a different local-only .env path.

Log whether a required variable is present, but never log its value.

Managed

Self-Hosting

Environment variables and secrets

Variable scopes

Organization secrets

Apply a changed secret

Missing secret behavior

Cloud-provided database variables

Works locally, but the variable is missing in Cloud

​Variable scopes

​Organization secrets

​Apply a changed secret

​Missing secret behavior

​Cloud-provided database variables

​Works locally, but the variable is missing in Cloud

Variable scopes

Organization secrets

Apply a changed secret

Missing secret behavior

Cloud-provided database variables

Works locally, but the variable is missing in Cloud