Secrets & Environment Variables

Declare environment variables in your manifest, store secrets locally, and Runtime injects them at deploy time.

How it works

Secrets are never stored in Runtime’s database. Values pass directly from your machine to Fly.io.

Declaring environment variables

Define env vars in runtm.yaml:

env_schema:
  - name: DATABASE_URL
    type: url
    required: true
    secret: true
    description: "PostgreSQL connection string"
  
  - name: STRIPE_API_KEY
    type: string
    required: true
    secret: true
    description: "Stripe secret key"
  
  - name: LOG_LEVEL
    type: string
    required: false
    default: "info"
    description: "Logging verbosity"

Field reference

Field	Type	Description
`name`	string	Variable name (UPPER_SNAKE_CASE)
`type`	enum	`string`, `url`, `number`, `boolean`
`required`	boolean	Deployment fails without it
`secret`	boolean	Redact from logs
`description`	string	Human-readable description
`default`	string	Default value (not allowed for secrets)

Managing secrets

Set a secret

runtm secrets set DATABASE_URL=postgres://user:pass@host:5432/db

Secrets are stored in .env.local in your project directory.

List secrets

runtm secrets list

Environment Variables

  NAME           TYPE     REQUIRED  SECRET  STATUS
  DATABASE_URL   url      ✓         ✓       ● set
  STRIPE_API_KEY string   ✓         ✓       ● set
  LOG_LEVEL      string   -         -       ○ default (info)

Get / remove

runtm secrets get DATABASE_URL
runtm secrets unset OLD_API_KEY

Security

Automatic protection

.env.local is automatically added to both .gitignore and .cursorignore:

# Secrets - DO NOT COMMIT
.env.local

This means:

Secrets are never committed to git
AI assistants cannot read secret values

Log redaction

Secrets marked secret: true appear as [REDACTED] in logs:

Setting environment variables...
  DATABASE_URL = [REDACTED]
  LOG_LEVEL = info

Connections

Group related env vars as named connections:

env_schema:
  - name: SUPABASE_URL
    type: url
    required: true
  - name: SUPABASE_ANON_KEY
    type: string
    required: true
    secret: true

connections:
  - name: supabase
    env_vars: [SUPABASE_URL, SUPABASE_ANON_KEY]

Connections help organize which env vars belong together.

Using in code

Python
Node.js

import os

DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///./data/app.db")
STRIPE_API_KEY = os.environ["STRIPE_API_KEY"]

Or with Pydantic:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///./data/app.db"
    stripe_api_key: str

settings = Settings()

// Server-side
const STRIPE_API_KEY = process.env.STRIPE_API_KEY!;

// Client-side (must prefix with NEXT_PUBLIC_)
const API_URL = process.env.NEXT_PUBLIC_API_URL;

Troubleshooting

Missing required environment variable

Set the missing variable:

runtm secrets set VAR_NAME=value

Secret env var cannot have default

Secrets can’t have defaults. Remove the default field:

- name: API_KEY
  secret: true
  required: true  # no default

Secret value not updating

Redeploy after changing secrets:

runtm deploy

Open Source

Guides

Features

OSS Templates

CLI Reference

Self-Hosting

OSS API

Deployments

Logs

Domains

User

Secrets & Environment Variables

How it works

Declaring environment variables

Field reference

Managing secrets

Set a secret

List secrets

Get / remove

Security

Automatic protection

Log redaction

Connections

Using in code

Troubleshooting

​How it works

​Declaring environment variables

​Field reference

​Managing secrets

​Set a secret

​List secrets

​Get / remove

​Security

​Automatic protection

​Log redaction

​Connections

​Using in code

​Troubleshooting

How it works

Declaring environment variables

Field reference

Managing secrets

Set a secret

List secrets

Get / remove

Security

Automatic protection

Log redaction

Connections

Using in code

Troubleshooting