Circuitry Logo
Circuitry
Open Circuitry

Environment Variables - Secure Configuration

Environment Variables are a secure way to store configuration values and sensitive information like API keys, database connection strings, and authentication tokens. They keep these secrets out of your code and away from version control, preventing security breaches and unauthorized access.

Your values are encrypted at rest and are not visible to Circuitry in the database.

🔐 What Are Environment Variables?

Environment variables are key-value pairs that exist outside your application code. They provide:

  • Security: Keep sensitive data like API keys and passwords out of your codebase
  • Flexibility: Different values for development, staging, and production environments
  • Portability: Same code runs in different environments with different configurations
  • Protection: Prevent accidental exposure of secrets in git repositories

Why Use Environment Variables?

Instead of hardcoding sensitive values:

// ❌ Never do this!
const apiKey = "sk-1234567890abcdef";
const dbPassword = "mySecretPassword123";

Read them in a Code node with Circuitry's env() helper:

// ✅ Safe and secure
const apiKey = env('API_KEY');
const dbPassword = env('DB_PASSWORD');

Note: There are two ways to read a variable, depending on where you are. In Code and Condition nodes (anywhere you write JavaScript) use the env('NAME') function — there is no process.env in the sandbox. In configuration fields — agent prompts, Action headers/URLs, Database settings — use the {{env.NAME}} template, which is replaced with the value before the node runs.

🚀 Setting Up Environment Variables

In Circuitry Settings

  1. Navigate to Settings in the top navigation
  2. Click on the Environment Variables tab
  3. Add your variables as key-value pairs
  4. Click Save to store them securely

Variable Format

Environment variables follow these conventions:

  • Names: Use UPPERCASE with underscores (e.g., API_KEY, DATABASE_URL)
  • Values: Can be strings, numbers, or URLs
  • No spaces: Don't use spaces in variable names

Common Examples

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/db

# Service URLs
API_BASE_URL=https://api.example.com
WEBHOOK_URL=https://yourapp.com/webhooks

# Authentication
AUTH_SECRET=your-secret-key-here
JWT_SECRET=your-jwt-secret
OAUTH_CLIENT_ID=123456789
OAUTH_CLIENT_SECRET=abcdef123456

# Feature Flags
ENABLE_DEBUG=true
MAX_RETRIES=3
TIMEOUT_SECONDS=30

🌐 Where Variables Live (Scope & Sync)

Environment variables are tied to your account, not to the device you're using. Set a variable once and it's available everywhere you sign in — your laptop, your desktop, your tablet. There's no need to re-enter them on each device.

Global vs. Project Variables

Variables come in two scopes:

  • Global — available to every workflow across all your projects. Use these for credentials you reuse everywhere (e.g. OPENAI_API_KEY).
  • Project — scoped to a single project. Use these for values that differ per project (e.g. a project-specific DATABASE_URL).

A project sees both its own variables and your global ones. If a project variable and a global variable share the same name, the project variable wins for workflows in that project — letting you override a global default on a per-project basis without deleting it.

💡 Using Environment Variables in Workflows

In Template Variables

In any configuration field, reference environment variables with the {{env.VARIABLE_NAME}} syntax. The value is substituted before the node runs:

{{env.API_BASE_URL}}
{{env.DATABASE_URL}}
{{env.COMPANY_NAME}}

In Agent Nodes

Use environment variables to feed configuration into AI prompts — values that vary between environments or deployments:

You are operating in the {{env.ENVIRONMENT}} environment for {{env.COMPANY_NAME}}.
Look up records using the catalogue at {{env.CATALOGUE_URL}}.

Don't put secrets in prompts. Prompt text is sent to the AI model provider, so an API key or password placed here is exposed to a third party — and the model can't use it anyway. Keep secrets in Action node auth headers (which go to the target service, not the model) or read them inside a Code node with env().

In Action Nodes

Configure HTTP requests with environment variables:

Headers:

{
  "Authorization": "Bearer {{env.API_TOKEN}}",
  "X-API-Key": "{{env.SERVICE_API_KEY}}"
}

URL:

{{env.API_BASE_URL}}/users/{{input.userId}}

In Code Nodes

Read environment variables with the env('NAME') function:

const apiKey = env('API_KEY');
const baseUrl = env('API_BASE_URL');
const maxRetries = parseInt(env('MAX_RETRIES')) || 3;

// Use them in your logic
const response = await fetch(`${baseUrl}/data`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

In Guard & Condition Nodes

Gate a branch by comparing the incoming data (input) against an environment variable. A guard condition is a JavaScript expression that must evaluate to true or false — so you have the full language available (operators, parseInt, method calls, regex). Read variables with the env('NAME') function and read upstream data with input:

// Continue only if the request carries the expected token
input.token === env('API_TOKEN')

// Continue only if the value is under a configured limit
input.value < parseInt(env('MAX_VALUE'))

Inside conditions and code, the available helpers are input (data from the previous node) and env() (your environment variables). This lets the same workflow take different paths depending on the data or your configuration.

In Plugin Configurations

Plugins can use environment variables for authentication:

{
  "apiKey": "{{env.SLACK_API_KEY}}",
  "webhookUrl": "{{env.SLACK_WEBHOOK_URL}}"
}

🛡️ Security Best Practices

1. Never Commit Secrets

Never commit environment variables to version control:

  • Don't include .env files in git
  • Add .env to .gitignore
  • Use environment variable management in Circuitry

2. Use Descriptive Names

Clear naming prevents confusion:

# Good ✅
OPENAI_API_KEY=sk-...
STRIPE_WEBHOOK_SECRET=whsec_...
DATABASE_CONNECTION_STRING=...

# Bad ❌
KEY=sk-...
SECRET=whsec_...
DB=...

3. Separate by Environment

Use different variables for different environments:

# Development
DEV_API_URL=http://localhost:3000
DEV_DATABASE_URL=sqlite://./dev.db

# Production
PROD_API_URL=https://api.production.com
PROD_DATABASE_URL=postgresql://prod-server/db

4. Rotate Secrets Regularly

  • Change API keys periodically
  • Update passwords and tokens
  • Remove unused variables

5. Limit Access

  • Only share credentials with team members who need them
  • Use different keys for different team members when possible
  • Revoke access when team members leave

🔧 Managing Environment Variables

Adding Variables

  1. Go to Settings → Environment Variables
  2. Click Add Variable
  3. Enter the name (uppercase with underscores)
  4. Enter the value (encrypted at rest, and hidden in the UI once saved)
  5. Click Save

Editing Variables

  1. Find the variable in your list
  2. Click the Edit button
  3. Update the value
  4. Click Save

Deleting Variables

  1. Find the variable to remove
  2. Click the Delete button
  3. Confirm deletion

Viewing Variables

  • Variable names are always visible
  • Values are hidden by default (shown as ••••••)
  • Click the eye icon to reveal a value temporarily

📚 Common Use Cases

API Integration

Store API credentials securely:

# Third-party APIs
OPENAI_API_KEY=sk-...
STRIPE_API_KEY=sk_live_...
TWILIO_AUTH_TOKEN=...
SENDGRID_API_KEY=SG....

# Internal APIs
INTERNAL_API_KEY=...
SERVICE_ACCOUNT_KEY=...

Database Connections

Keep database credentials safe:

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=dbuser
POSTGRES_PASSWORD=dbpass
POSTGRES_DB=myapp

# MongoDB
MONGO_URI=mongodb://user:pass@host:27017/db

OAuth Configuration

Store OAuth credentials:

# Google OAuth
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# GitHub OAuth
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Feature Configuration

Control features and limits:

# Features
ENABLE_BETA_FEATURES=true
DEBUG_MODE=false
LOG_LEVEL=info

# Limits
MAX_UPLOAD_SIZE=10485760
RATE_LIMIT=100
TIMEOUT_MS=30000

🐛 Troubleshooting

Variable Not Found

If {{env.VARIABLE_NAME}} (or env('VARIABLE_NAME') in code) isn't working:

  1. Check the variable exists in Settings
  2. Verify the exact spelling (case-sensitive)
  3. Make sure the variable is saved
  4. Confirm you're using the right form for the node — env('NAME') in Code/Condition nodes, {{env.NAME}} in configuration fields
  5. Refresh the workflow editor

Value Not Updating

If changes aren't reflected:

  1. Save the environment variable
  2. Refresh the workflow
  3. Re-run the workflow

Special Characters

If values with special characters cause issues:

  • Wrap values in quotes if needed
  • Escape special characters with backslash
  • Use URL encoding for URLs with special characters

🎯 Tips and Tricks

1. Group Related Variables

Use prefixes to organize:

# Database variables
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp

# API variables
API_KEY=...
API_SECRET=...
API_BASE_URL=...

2. Document Your Variables

Keep a secure record of:

  • What each variable is for
  • Where it's used
  • Who has access
  • When to rotate

3. Use Fallback Values

In Code nodes, provide defaults:

const apiUrl = env('API_URL') || "https://api.default.com";
const retries = parseInt(env('MAX_RETRIES')) || 3;

4. Test with Different Values

  • Use test API keys for development
  • Use sandbox environments when available
  • Never use production credentials in testing

🔗 Related Documentation