🔧 Environment Variables Configuration Guide

May 7, 2026 · View on GitHub

This guide provides comprehensive setup instructions for all AI providers supported by NeuroLink. The CLI automatically loads environment variables from .env files, making configuration seamless.

🚀 Quick Setup

Automatic .env Loading ✨ NEW!

NeuroLink CLI automatically loads environment variables from .env files in your project directory:

# Create .env file (automatically loaded)
echo 'OPENAI_API_KEY="sk-your-key"' > .env
echo 'AWS_ACCESS_KEY_ID="your-key"' >> .env

# Test configuration
npx @juspay/neurolink status

Manual Export (Also Supported)

export OPENAI_API_KEY="sk-your-key"
export AWS_ACCESS_KEY_ID="your-key"
npx @juspay/neurolink status

🏗️ Enterprise Configuration Management

✨ NEW: Automatic Backup System

# Configure backup settings
NEUROLINK_BACKUP_ENABLED=true              # Enable automatic backups (default: true)
NEUROLINK_BACKUP_RETENTION=30              # Days to keep backups (default: 30)
NEUROLINK_BACKUP_DIRECTORY=.neurolink.backups  # Backup directory (default: .neurolink.backups)

# Config validation settings
NEUROLINK_VALIDATION_STRICT=false          # Strict validation mode (default: false)
NEUROLINK_VALIDATION_WARNINGS=true         # Show validation warnings (default: true)

# Provider status monitoring
NEUROLINK_PROVIDER_STATUS_CHECK=true       # Monitor provider availability (default: true)
NEUROLINK_PROVIDER_TIMEOUT=30000           # Provider timeout in ms (default: 30000)

Interface Configuration

# MCP Registry settings
NEUROLINK_REGISTRY_CACHE_TTL=300           # Cache TTL in seconds (default: 300)
NEUROLINK_REGISTRY_AUTO_DISCOVERY=true     # Auto-discover MCP servers (default: true)
NEUROLINK_REGISTRY_STATS_ENABLED=true      # Enable registry statistics (default: true)

# Execution context settings
NEUROLINK_DEFAULT_TIMEOUT=30000            # Default execution timeout (default: 30000)
NEUROLINK_DEFAULT_RETRIES=3                # Default retry count (default: 3)
NEUROLINK_CONTEXT_LOGGING=info             # Context logging level (default: info)

Performance & Optimization

# Tool execution settings
NEUROLINK_TOOL_EXECUTION_TIMEOUT=1000      # Tool execution timeout in ms (default: 1000)
NEUROLINK_PIPELINE_TIMEOUT=22000           # Pipeline execution timeout (default: 22000)
NEUROLINK_CACHE_ENABLED=true               # Enable execution caching (default: true)

# Error handling
NEUROLINK_AUTO_RESTORE_ENABLED=true        # Enable auto-restore on config failures (default: true)
NEUROLINK_ERROR_RECOVERY_ATTEMPTS=3        # Error recovery attempts (default: 3)
NEUROLINK_GRACEFUL_DEGRADATION=true        # Enable graceful degradation (default: true)

🆕 AI Enhancement Features

Basic Enhancement Configuration

# AI response quality evaluation model (optional)
NEUROLINK_EVALUATION_MODEL="gemini-2.5-flash"

Description: Configures the AI model used for response quality evaluation when --enable-evaluation flag is used. Uses Google AI's fast Gemini 2.5 Flash model for quick quality assessment.

Supported Models:

gemini-2.5-flash (default) - Fast evaluation processing
gemini-2.5-pro - More detailed evaluation (slower)

Usage:

# Enable evaluation with default model
npx @juspay/neurolink generate "prompt" --enable-evaluation

# Enable both analytics and evaluation
npx @juspay/neurolink generate "prompt" --enable-analytics --enable-evaluation

🌐 Universal Evaluation System (Advanced)

Primary Configuration

# Primary evaluation provider
NEUROLINK_EVALUATION_PROVIDER="google-ai"        # Default: google-ai

# Evaluation performance mode
NEUROLINK_EVALUATION_MODE="fast"                 # Options: fast, balanced, quality

NEUROLINK_EVALUATION_PROVIDER: Primary AI provider for evaluation

Options: google-ai, openai, anthropic, vertex, bedrock, azure, ollama, huggingface, mistral
Default: google-ai
Usage: Determines which AI provider performs the quality evaluation

NEUROLINK_EVALUATION_MODE: Performance vs quality trade-off

Options: fast (cost-effective), balanced (optimal), quality (highest accuracy)
Default: fast
Usage: Selects appropriate model for the provider (e.g., gemini-2.5-flash vs gemini-2.5-pro)

Fallback Configuration

# Enable automatic fallback when primary provider fails
NEUROLINK_EVALUATION_FALLBACK_ENABLED="true"     # Default: true

# Fallback provider order (comma-separated)
NEUROLINK_EVALUATION_FALLBACK_PROVIDERS="openai,anthropic,vertex,bedrock"

NEUROLINK_EVALUATION_FALLBACK_ENABLED: Enable intelligent fallback system

Options: true, false
Default: true
Usage: When enabled, automatically tries backup providers if primary fails

NEUROLINK_EVALUATION_FALLBACK_PROVIDERS: Backup provider order

Format: Comma-separated provider names
Default: openai,anthropic,vertex,bedrock
Usage: Defines the order of providers to try if primary fails

Performance Tuning

# Evaluation timeout (milliseconds)
NEUROLINK_EVALUATION_TIMEOUT="10000"             # Default: 10000 (10 seconds)

# Maximum tokens for evaluation response
NEUROLINK_EVALUATION_MAX_TOKENS="500"            # Default: 500

# Temperature for consistent evaluation
NEUROLINK_EVALUATION_TEMPERATURE="0.1"           # Default: 0.1 (low for consistency)

# Retry attempts for failed evaluations
NEUROLINK_EVALUATION_RETRY_ATTEMPTS="2"          # Default: 2

Performance Variables:

TIMEOUT: Maximum time to wait for evaluation (prevents hanging)
MAX_TOKENS: Limits evaluation response length (controls cost)
TEMPERATURE: Lower values = more consistent scoring
RETRY_ATTEMPTS: Number of retry attempts for transient failures

Cost Optimization

# Prefer cost-effective models and providers
NEUROLINK_EVALUATION_PREFER_CHEAP="true"         # Default: true

# Maximum cost per evaluation (USD)
NEUROLINK_EVALUATION_MAX_COST_PER_EVAL="0.01"    # Default: \$0.01

NEUROLINK_EVALUATION_PREFER_CHEAP: Cost optimization preference

Options: true, false
Default: true
Usage: When enabled, prioritizes cheaper providers and models

NEUROLINK_EVALUATION_MAX_COST_PER_EVAL: Cost limit per evaluation

Format: Decimal number (USD)
Default: 0.01 ($0.01)
Usage: Prevents expensive evaluations, switches to cheaper providers if needed

Complete Universal Evaluation Example

# Comprehensive evaluation configuration
NEUROLINK_EVALUATION_PROVIDER="google-ai"
NEUROLINK_EVALUATION_MODEL="gemini-2.5-flash"
NEUROLINK_EVALUATION_MODE="balanced"
NEUROLINK_EVALUATION_FALLBACK_ENABLED="true"
NEUROLINK_EVALUATION_FALLBACK_PROVIDERS="openai,anthropic,vertex"
NEUROLINK_EVALUATION_TIMEOUT="15000"
NEUROLINK_EVALUATION_MAX_TOKENS="750"
NEUROLINK_EVALUATION_TEMPERATURE="0.2"
NEUROLINK_EVALUATION_PREFER_CHEAP="false"
NEUROLINK_EVALUATION_MAX_COST_PER_EVAL="0.05"
NEUROLINK_EVALUATION_RETRY_ATTEMPTS="3"

Testing Universal Evaluation

# Test primary provider
npx @juspay/neurolink generate "What is AI?" --enable-evaluation --debug

# Test with custom domain
npx @juspay/neurolink generate "Fix this Python code" --enable-evaluation --evaluation-domain "Python expert"

# Test Lighthouse-style evaluation
npx @juspay/neurolink generate "Business analysis" --lighthouse-style --evaluation-domain "Business consultant"

🏢 Enterprise Proxy Configuration

Proxy Environment Variables

# Corporate proxy support (automatic detection)
HTTPS_PROXY="http://proxy.company.com:8080"
HTTP_PROXY="http://proxy.company.com:8080"
NO_PROXY="localhost,127.0.0.1,.company.com"

Variable	Description	Example
`HTTPS_PROXY`	Proxy server for HTTPS requests	`http://proxy.company.com:8080`
`HTTP_PROXY`	Proxy server for HTTP requests	`http://proxy.company.com:8080`
`NO_PROXY`	Domains to bypass proxy	`localhost,127.0.0.1,.company.com`

Authenticated Proxy

# Proxy with username/password authentication
HTTPS_PROXY="http://username:password@proxy.company.com:8080"
HTTP_PROXY="http://username:password@proxy.company.com:8080"

All NeuroLink providers automatically use proxy settings when configured.

For detailed proxy setup → See Enterprise & Proxy Setup Guide

Tier	Description
`free`	Free tier with limited access
`pro`	Claude Pro subscription (default for OAuth)
`max`	Claude Max subscription
`max_5`	Claude Max with 5x usage
`max_20`	Claude Max with 20x usage
`api`	Standard API key access (default without OAuth)

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	*	-	Anthropic API key (required if not using OAuth)
`ANTHROPIC_OAUTH_TOKEN`	*	-	OAuth access token, plain string or JSON (required if not using API key)
`CLAUDE_OAUTH_TOKEN`	*	-	Alternative OAuth token env var (same format as `ANTHROPIC_OAUTH_TOKEN`)
`ANTHROPIC_MODEL`	No	`claude-3-5-sonnet-20241022`	Default model to use
`ANTHROPIC_SUBSCRIPTION_TIER`	No	Auto-detected (`pro` or `api`)	Subscription tier override: `free`, `pro`, `max`, `max_5`, `max_20`, `api`
`ANTHROPIC_ENABLE_BETA_FEATURES`	No	`true` (OAuth) / `false` (API key)	Enable Anthropic beta headers (OAuth beta, extended thinking)
`ANTHROPIC_OAUTH_REFRESH_TOKEN`	No	-	OAuth refresh token (used for automatic token renewal)
`ANTHROPIC_AUTH_METHOD`	No	Auto-detected	Force auth method: `api_key` or `oauth`

Variable	Required	Default	Description
`AWS_ACCESS_KEY_ID`	✅	-	AWS access key for authentication
`AWS_SECRET_ACCESS_KEY`	✅	-	AWS secret key for authentication
`AWS_REGION`	✅	us-east-1	AWS region where endpoint is deployed
`SAGEMAKER_DEFAULT_ENDPOINT`	✅	-	SageMaker endpoint name
`SAGEMAKER_TIMEOUT`	❌	30000	Request timeout in milliseconds
`SAGEMAKER_MAX_RETRIES`	❌	3	Number of retry attempts for failed requests
`AWS_SESSION_TOKEN`	❌	-	Session token for temporary credentials
`SAGEMAKER_MODEL`	❌	sagemaker-model	Model identifier for logging
`SAGEMAKER_CONTENT_TYPE`	❌	application/json	Request content type
`SAGEMAKER_ACCEPT`	❌	application/json	Response accept type

Variable	Required	Default	Description
`AZURE_SPEECH_KEY`	✅	-	Azure Speech Services API key
`AZURE_SPEECH_REGION`	✅	-	Azure region (e.g., `eastus`, `westeurope`)
`GOOGLE_AI_API_KEY`	❌	-	Canonical Google API key (Google STT / Gemini Live)
`GEMINI_API_KEY`	❌	-	Accepted alias for `GOOGLE_AI_API_KEY`
`GOOGLE_API_KEY`	❌	-	Legacy alias for `GOOGLE_AI_API_KEY`
`ELEVENLABS_API_KEY`	❌	-	ElevenLabs key, if using ElevenLabs alongside
`DEEPGRAM_API_KEY`	❌	-	Deepgram key, if using Deepgram alongside