Variables & Secrets

Configure your services with environment variables and securely store sensitive data like API keys, passwords, and tokens.

Overview

Every application needs configuration — API endpoints, feature flags, database passwords, third-party API keys. Variables & Secrets let you manage all of this without hardcoding values in your code.

Cerebrum manages variables. Just say “add the OpenAI API key” or “set DEBUG to true” — Cerebrum will configure it. The details below explain how variables and secrets work.

Variables

Plain text configuration visible in the UI. Use for non-sensitive settings like endpoints, flags, and paths.

Secrets

Encrypted values hidden from view. Use for passwords, API keys, tokens, and anything sensitive.

Variables and Secrets are configured per service and injected as environment variables at runtime — both in dev containers and production deployments.

Why Use Variables & Secrets

Keep secrets out of code

Never commit passwords or API keys to your repository. Store them securely in Ardor.

Environment-specific config

Same code, different configs. Switch between dev/staging/prod without changing code.

Easy updates

Change a value once in the UI — no redeployment needed for dev containers.

Team-friendly

Share configuration without sharing actual secret values. Team members see masked data.

Variables vs Secrets

	Variables	Secrets
Visibility	Visible in UI	Masked (••••••••)
Storage	Plain text	Encrypted
Use for	Endpoints, flags, paths	Passwords, API keys, tokens
Editable	View and edit freely	Edit without seeing current value

Rule of thumb: Passwords, API keys, tokens? Always a Secret. They’re stored encrypted in Ardor and never touch your code — only references to them do. Your GitHub repo stays clean.

System Variables

At runtime, Ardor may add system variables based on your service settings. These variables are managed by Ardor and cannot be edited or overridden from Variables & Secrets.

Common system variables include:

Variable	Description
ARDOR_SERVICE_ID	ID of the current service
ARDOR_ENVIRONMENT_ID	ID of the current environment
ARDOR_PRIVATE_HOST	Private hostname for reaching the service inside the environment

System variables are injected automatically when they apply to the service. They may not all be present for every service configuration.

Adding Variables & Secrets

1. Open Service Settings

   Navigate to your service and open the Variables & Secrets section

2. Add Variable or Secret

   Click Add Variable or Add Secret, enter a name and value

3. Save

   Changes apply to dev container immediately. For production, redeploy your service.

Variable References

A variable or secret value can include references to variables from the current service or another service. Type @ in the value field and select a variable from the list. Ardor inserts a reference token for you, including references to system variables such as ARDOR_PRIVATE_HOST.

You can also click to create a reference directly.

A single value can combine static text and multiple references. For example, a DATABASE_URL can be assembled from database credentials and the database service private host:

postgresql://{{ postgres-db.POSTGRES_USER }}:{{ postgres-db.POSTGRES_PASSWORD }}@{{ postgres-db.ARDOR_PRIVATE_HOST }}:5432/{{ postgres-db.POSTGRES_DB }}

References are resolved when Ardor injects environment variables at runtime, so the consuming service receives one final value.

Naming Conventions

Environment variable names should be:

• UPPERCASE with underscores: DATABASE_URL, API_KEY, DEBUG_MODE
• Descriptive: POSTGRES_PASSWORD not PW
• Prefixed for clarity: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD

Some names are reserved by the system (like PORT). Ardor will warn you if you try to use a reserved name.

Common Use Cases

Database Connection

Connect to PostgreSQL, MySQL, or other databases:

Variable	Type	Example
DATABASE_HOST	Variable	postgres-service.internal
DATABASE_PORT	Variable	5432
DATABASE_NAME	Variable	myapp
DATABASE_USER	Variable	admin
DATABASE_PASSWORD	Secret	••••••••

import os

db_url = f"postgresql://{os.environ['DATABASE_USER']}:{os.environ['DATABASE_PASSWORD']}@{os.environ['DATABASE_HOST']}:{os.environ['DATABASE_PORT']}/{os.environ['DATABASE_NAME']}"

Third-Party APIs

Connect to OpenAI, Stripe, Twilio, etc:

Variable	Type	Example
OPENAI_API_KEY	Secret	••••••••
OPENAI_MODEL	Variable	gpt-4
STRIPE_SECRET_KEY	Secret	••••••••
STRIPE_WEBHOOK_SECRET	Secret	••••••••

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['OPENAI_API_KEY'])

Feature Flags

Toggle features without code changes:

Variable	Type	Example
DEBUG_MODE	Variable	true
ENABLE_ANALYTICS	Variable	false
MAX_UPLOAD_SIZE	Variable	10485760

import os

debug = os.environ.get('DEBUG_MODE', 'false').lower() == 'true'
if debug:
    print("Debug mode enabled")

Service URLs

Connect services within your solution:

Variable	Type	Example
API_BASE_URL	Variable	https://api.example.com
REDIS_URL	Variable	redis://redis-service.internal:6379
WEBHOOK_URL	Variable	https://myapp.ardor.cloud/webhook

Reading Variables in Code

Variables and Secrets are injected as environment variables. Here’s how to read them:

Python

import os

# Required variable (raises error if missing)
api_key = os.environ['API_KEY']

# Optional with default
debug = os.environ.get('DEBUG', 'false')
port = int(os.environ.get('PORT', 8080))

Node.js

// Required variable
const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error('API_KEY is required');

// Optional with default
const debug = process.env.DEBUG || 'false';
const port = parseInt(process.env.PORT || '8080');

Go

import "os"

// Required variable
apiKey := os.Getenv("API_KEY")
if apiKey == "" {
    panic("API_KEY is required")
}

// Optional with default
debug := os.Getenv("DEBUG")
if debug == "" {
    debug = "false"
}

Frontend Services

For frontend services (React, Vue, Next.js, etc.), variables and secrets are composed into a .env file at build time. Use them in your Dockerfile:

COPY .env .

RUN npm run build

Frontend variables typically need a prefix depending on your framework:

• Vite: VITE_
• Create React App: REACT_APP_
• Next.js: NEXT_PUBLIC_

Frontend variables are embedded in the built code and visible to users. Never put secrets in frontend variables!

When Changes Apply

In	Variables	Secrets
Dev Container	Restart container	Restart container
Deployment	Redeploy service	Redeploy service

Dev containers restart automatically when you save variable changes. For deployed service, you need to trigger a new deployment.

Security

How Secrets Are Protected

• Encrypted at rest — Secrets are stored encrypted
• Masked by default — Shown as ••••••••, but you can reveal them by clicking the eye icon

Best Practices

Use secrets for anything sensitive

API keys, passwords, tokens, private keys — if it grants access to something, it’s a secret.

Don't log secrets

Be careful with debug logging. Never print environment variables that might contain secrets.

Rotate regularly

Change passwords and API keys periodically. Update the secret in Ardor, redeploy, done.

Use descriptive names

STRIPE_SECRET_KEY is better than KEY1. Future you will thank present you.

Minimum access principle

Only add secrets that a service actually needs. Don’t share database passwords with services that don’t use the database.

Troubleshooting

Variable not available in my code

Cause: Container hasn’t restarted after adding the variable.

Solution: Restart the dev container or redeploy the service.

Variable has wrong value

Cause: Typo in variable name or old cached value.

Solution:

• Check the exact variable name (case-sensitive!)
• Restart container to pick up latest values

Secret visible in logs

Cause: Your code is logging environment variables.

Solution: Review your logging code. Never log os.environ or similar dumps.

Frontend can't access variable

Cause: Missing framework prefix or variable added after build.

Solution:

• Add required prefix (VITE_, REACT_APP_, etc.)
• Rebuild and redeploy the frontend

What’s Next

Service Configuration

Learn about all service settings including resources and networking

Development Container

Use the dev container to test your variables in real-time

Connecting Services

Connect multiple services and share configuration

Build with Cerebrum

Let Cerebrum set up variables and secrets for you automatically