Documentation
Environment Variables
Configure secrets and environment variables for your Terragon sandboxes.
When you save changes, Terragon encrypts values before storing them in its database. It decrypts them when supplying them to your selected cloud runtime. Setup-script test output masks exact configured values, but scripts and processes can transform or expose secrets in other ways. Never print secrets or write them to logs or artifacts.
Environment variables allow you to add secrets and configuration values that will be available in your sandbox. You can configure environment variables at two levels:
- Global Environment: Variables that apply to all your repositories
- Repository-Specific Environment: Variables scoped to individual repositories
Repository-specific variables take precedence over global variables when both define the same key. This allows you to set common defaults globally while overriding them per repository as needed.
Common Use Cases
Environment variables are perfect for:
- API Keys: Store credentials for third-party services
- Database URLs: Connection strings for databases
- Feature Flags: Toggle features on/off
- Configuration Values: Any settings that vary between environments
- Webhook URLs: Endpoints for external services
- SDK Keys: Authentication for various SDKs
Adding Environment Variables
Add VariableSave Environment VariablesVariable names must begin with a letter or underscore and may include only letters, numbers, and underscores. Terragon points out invalid or duplicate names before you can save. Use the visibility control beside a value only when you need to inspect it, then hide it again.
Importing from .env File
You can import multiple environment variables from a .env file in one step:
Import from .env button.env fileImport to add them all at onceTerragon shows a line-specific error when pasted content is not valid .env
format, so you can correct the source before importing.
Example .env Format
# API Keys
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
# Feature Flags
ENABLE_NEW_FEATURE=true
DEBUG_MODE=false
# External Services
WEBHOOK_URL=https://api.example.com/webhook
SLACK_TOKEN=xoxb-...Default Environment Variables
Terragon automatically sets the following environment variables in your sandbox:
| Name | Description |
|---|---|
TERRAGON | Always set to true when running in a Terragon sandbox. You can use this variable to differentiate when the agent/code is running in a Terragon sandbox versus locally. |
GH_TOKEN | GitHub access token for the gh CLI. You can override this by setting your own GH_TOKEN environment variable. |
Custom GitHub Token: If you need to use a different GitHub token (e.g., for accessing private packages or repositories), you can add your own GH_TOKEN environment variable. Your custom token will take precedence over the default token provided by Terragon.
Using Environment Variables
In Setup Scripts
Environment variables are automatically available in your terragon-setup.sh script:
#!/bin/bash
# Check required values without printing them
test -n "${MY_API_KEY:?MY_API_KEY is required}"
test -n "${DATABASE_URL:?DATABASE_URL is required}"
# Configure application with environment variables
export NODE_ENV=production
export API_ENDPOINT=$API_URLIn Your Code
Access environment variables as you normally would in your application:
// Node.js/JavaScript
const apiKey = process.env.OPENAI_API_KEY;
const dbUrl = process.env.DATABASE_URL;# Python
import os
api_key = os.environ.get('OPENAI_API_KEY')
db_url = os.environ.get('DATABASE_URL')# Shell scripts
test -n "${OPENAI_API_KEY:?OPENAI_API_KEY is required}"
psql "$DATABASE_URL"