Environment Variables

Hyphen Deploy provides your application with environment variables at runtime. These include system-injected variables that provide deployment context and metadata, as well as user-defined secrets that you manage through Hyphen's ENV service.

Table of Contents

• HYPHEN_ System Variables
• ENV Secrets
  • Managing ENV Secrets
• Accessing Variables in Your Application
• Variable Precedence
• Best Practices
• Next Steps

HYPHEN_ System Variables

Hyphen automatically injects environment variables prefixed with HYPHEN_ into your application at runtime. These variables provide deployment metadata and context that your application can use for logging, monitoring, feature flagging, or environment-specific behavior.

The following variables are automatically available to your application:

These variables are managed by Hyphen. You cannot modify or override them.

ENV Secrets

In addition to the system-injected HYPHEN_ variables, you can define your own environment variables and secrets using Hyphen's ENV service. These are the variables you manage with the hx push and hx pull commands.

ENV Secrets are:

• User-defined: You control which variables exist and their values
• Encrypted: Stored securely with end-to-end encryption
• Environment-specific: Different values for development, production, etc.
• Version-controlled: Track changes and roll back if needed
• Automatically loaded: Injected into your application at runtime alongside HYPHEN_ variables

Common use cases for ENV Secrets include:

• API keys and tokens
• Database connection strings
• Third-party service credentials
• Feature flags
• Application configuration

Managing ENV Secrets

To work with ENV Secrets, use the Hyphen CLI:

# Push local .env files to Hyphen
hx push

# Pull encrypted variables from Hyphen
hx pull

# Push a specific environment
hx push --environment production

ENV Secrets are stored in .env.[environment_name] files locally (e.g., .env.development, .env.production) and synchronized with Hyphen's secure storage.

For detailed information about managing ENV Secrets, see:

• ENV Secrets Management
• Using ENV with Docker
• Rotating Encryption Keys

Accessing Variables in Your Application

All environment variables (both HYPHEN_ system variables and your ENV Secrets) are available through your programming language's standard environment variable access mechanisms:

Node.js:

const appId = process.env.HYPHEN_APP_ID;
const apiKey = process.env.MY_API_KEY;

Python:

import os
app_id = os.environ.get('HYPHEN_APP_ID')
api_key = os.environ.get('MY_API_KEY')

Go:

import "os"
appID := os.Getenv("HYPHEN_APP_ID")
apiKey := os.Getenv("MY_API_KEY")

Variable Precedence

Warning: If you define an ENV Secret with the same name as a HYPHEN_ system variable, your ENV Secret will override the system variable. This may cause unexpected issues with deployment metadata and application behavior. We recommend not creating ENV Secrets that start with HYPHEN_.

Best Practices

• Use HYPHEN_ system variables for deployment context, logging, and monitoring
• Use ENV Secrets for sensitive data like credentials and API keys
• Never commit secrets to version control (add .env.* files to .gitignore)
• Use different values for different environments (development, staging, production)
• Rotate credentials regularly using Hyphen's key rotation features

Next Steps

• Learn about ENV Secrets Management
• Understand the build process
• Set up GitHub Actions deployment
• Explore deployment run methods