🔧 Environment Variables Configuration Guide

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

The CLI loads environment variables from the .env file in your current directory (or from the file named by DOTENV_CONFIG_PATH) at startup:

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

# Test configuration
npx @juspay/neurolink status

The SDK does not read .env when it is imported. A library must not pick up files from whatever directory the host process happens to run in — a cloned repository's .env could otherwise set ANTHROPIC_BASE_URL and send your real key to a host of its choosing. An application that wants the CLI's behaviour opts in explicitly, either way:

import { loadDotenv, NeuroLink } from "@juspay/neurolink";

await loadDotenv(); // same rules as the CLI, see below
const neurolink = new NeuroLink();

NEUROLINK_DOTENV=1 node app.js   # the SDK loads .env at import

Endpoint overrides need a trustworthy file. dotenv never overrides a variable that is already set, but it sets every one that is not — including the variables that decide where a request goes: every provider *_BASE_URL / *_ENDPOINT(S) variable, the NEUROLINK_*_DIR directories and DOTENV_CONFIG_PATH. For exactly those names the .env file must be owned by the current user and must not be group- or world-writable; otherwise they are removed again and named in a stderr line (Refused 1 endpoint override(s) from … ANTHROPIC_BASE_URL). When they are kept, a one-line notice lists them (.env at … set endpoint override(s): ANTHROPIC_BASE_URL), with a reminder when the file is outside your home directory. Export such a variable in your shell to use it regardless.

Variable	Effect
`NEUROLINK_DOTENV=0`	Disable `.env` loading everywhere (CLI included).
`NEUROLINK_DOTENV=1`	Make the SDK load `.env` when imported. Must be set in the real environment — it cannot come from the file it enables.
`DOTENV_CONFIG_PATH`	Load this file instead of `./.env`. `DOTENV_CONFIG_PATH=/dev/null` is the documented way to run a test with no `.env` at all.

Project MCP configuration (`.mcp-config.json`)

A project .mcp-config.json names commands to run and URLs to connect to, so it is treated like .env — a directory is not a trust boundary:

The SDK never loads it from the working directory on its own. Pass new NeuroLink({ mcp: { configPath: "./.mcp-config.json" } }) to name a file, or mcp: { trustProjectConfig: true } for a directory you control.
The CLI loads it only after you have trusted that exact content: the file's SHA-256 is recorded in ~/.neurolink/trusted-mcp-configs.json (mode 0600). In a terminal you are shown the servers and asked; non-interactively the command refuses with exit status 1 until you decide.

Variable / flag	Effect
`--trust-mcp-config`	Trust the working directory's `.mcp-config.json` as it is now, and remember its hash.
`NEUROLINK_TRUST_MCP_CONFIG=1`	Same as the flag, for non-interactive runs (CI).
`NEUROLINK_TRUST_MCP_CONFIG=0`	Run without the project config.
`NEUROLINK_SKIP_MCP=true`	Skip MCP initialisation entirely (built-in and external servers alike).

See MCP Integration for what the file may contain and how ${VAR} references, the stdio environment and transport URLs are checked.

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`

The shared HTTP proxy fetch accepts comma- or whitespace-separated NO_PROXY entries. Entries are case-insensitive: * bypasses all; example.com, .example.com and *.example.com cover the host and its subdomains; example.com:8443 restricts a match to that effective port (HTTP defaults to 80, HTTPS to 443). One trailing dot is normalized for domain names. IPv4/IPv6 literals match exactly, including [::1]:8080; IPv4 CIDR entries apply only to literal IPv4 targets, and IPv6 CIDR is unsupported. Dot-only entries (. or ..) match nothing.

These rules apply to request paths that use NeuroLink's HTTP proxy fetch. Native AWS handlers, Gemini Live WebSockets and Vertex ADC token requests use separate transports/dependency rules. See Enterprise & Proxy Setup for those limits. The legacy AWS proxy selector uses a smaller comma-separated matcher; it supports exact hosts, leading-dot subdomain suffixes and *, without the full port/wildcard/CIDR syntax. It is not automatically injected into the native Bedrock constructors.

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

🤖 Provider Configuration

1. OpenAI

Required Variables

OPENAI_API_KEY="sk-proj-your-openai-api-key"

Optional Variables

OPENAI_MODEL="gpt-4o-mini"              # Default: gpt-4o-mini
OPENAI_BASE_URL="https://api.openai.com" # Default: OpenAI API

How to Get OpenAI API Key

Visit OpenAI Platform
Sign up or log in to your account
Navigate to API Keys section
Click Create new secret key
Copy the key (starts with sk-proj- or sk-)
Add billing information if required

Supported Models

Examples, not the full list. The OpenAI guide lists every model the SDK names, including the GPT-6 and gpt-5.4-nano models.

gpt-5.4 - GPT-5.4 model
gpt-5.4-mini - Faster, cost-effective GPT-5.4 option
gpt-4o-mini (default) - Cost-effective, fast
gpt-4o - Previous generation multimodal model
gpt-4-turbo - High-performance model
gpt-3.5-turbo - Legacy cost-effective option

With no model set, NeuroLink uses the explicit model option, then OPENAI_MODEL, then the default in the model configuration (MODEL_CONFIG_URL, otherwise the repository's config/models.json), then the registry default gpt-4o-mini. Constructing OpenAIProvider directly with none of these falls back to gpt-5.4.

2. Amazon Bedrock

Required Variables

AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="your-secret-key"
AWS_REGION="us-east-1"

Model Configuration (⚠️ Critical)

# Use full inference profile ARN for Anthropic models
BEDROCK_MODEL="arn:aws:bedrock:us-east-2:<account_id>:inference-profile/us.anthropic.claude-3-7-sonnet-20250219-v1:0"

# OR use simple model names for non-Anthropic models
BEDROCK_MODEL="amazon.titan-text-express-v1"

Optional Variables

AWS_SESSION_TOKEN="IQoJb3..."           # For temporary credentials

How to Get AWS Credentials

Sign up for AWS Account
Navigate to IAM Console
Create new user with programmatic access
Attach policy: AmazonBedrockFullAccess
Download access key and secret key
Important: Request model access in Bedrock console

Bedrock Model Access Setup

Go to AWS Bedrock Console
Navigate to Model access
Click Request model access
Select desired models (Claude, Titan, etc.)
Submit request and wait for approval

Supported Models

Anthropic Claude:
- arn:aws:bedrock:<region>:<account_id>:inference-profile/us.anthropic.claude-3-7-sonnet-20250219-v1:0
- arn:aws:bedrock:<region>:<account_id>:inference-profile/us.anthropic.claude-3-5-sonnet-20241022-v2:0
Amazon Titan:
- amazon.titan-text-express-v1
- amazon.titan-text-lite-v1

3. Google Vertex AI

Google Vertex AI supports three authentication methods. Choose the one that fits your deployment:

Method 1: Service Account File (Recommended)

GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/service-account.json"
GOOGLE_VERTEX_PROJECT="your-gcp-project-id"
GOOGLE_VERTEX_LOCATION="us-central1"

Method 2: Service Account JSON String

GOOGLE_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"your-project",...}'
GOOGLE_VERTEX_PROJECT="your-gcp-project-id"
GOOGLE_VERTEX_LOCATION="us-central1"

Method 3: Individual Environment Variables

GOOGLE_AUTH_CLIENT_EMAIL="service-account@your-project.iam.gserviceaccount.com"
GOOGLE_AUTH_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0B..."
GOOGLE_VERTEX_PROJECT="your-gcp-project-id"
GOOGLE_VERTEX_LOCATION="us-central1"

Optional Variables

VERTEX_MODEL="gemini-2.5-pro"           # Default: gemini-2.5-pro

How to Set Up Google Vertex AI

Create Google Cloud Project
Enable Vertex AI API
Create Service Account:
- Go to IAM & Admin > Service Accounts
- Click Create Service Account
- Grant Vertex AI User role
- Generate and download JSON key file
Set GOOGLE_APPLICATION_CREDENTIALS to the JSON file path

Supported Models

gemini-2.5-pro (default) - Most capable model
gemini-2.5-flash - Faster responses
claude-3-5-sonnet@20241022 - Claude via Vertex AI

4. Anthropic (Direct)

Anthropic supports two authentication methods: API key (traditional) and OAuth token (for Claude subscription users).

Method 1: API Key (Traditional)

Required Variables

ANTHROPIC_API_KEY="sk-ant-api03-your-anthropic-key"

Optional Variables

ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"  # Default model

How to Get Anthropic API Key

Visit Anthropic Console
Sign up or log in
Navigate to API Keys
Click Create Key
Copy the key (starts with sk-ant-api03-)
Add billing information for usage

Method 2: OAuth Token (Claude Subscription)

Use OAuth authentication to access Claude models through a Claude Pro, Max, or Team subscription instead of pay-per-token API billing.

Required Variables

# Either of these (ANTHROPIC_OAUTH_TOKEN takes precedence)
ANTHROPIC_OAUTH_TOKEN="your-oauth-access-token"
CLAUDE_OAUTH_TOKEN="your-oauth-access-token"

The OAuth token value can be a plain access token string or a JSON object with the following fields:

{
  "accessToken": "your-access-token",
  "refreshToken": "your-refresh-token",
  "expiresAt": 1735689600000
}

Where expiresAt is the token expiry time in Unix milliseconds.

Optional Variables

ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"            # Default model
ANTHROPIC_SUBSCRIPTION_TIER="pro"                        # Subscription tier override

ANTHROPIC_SUBSCRIPTION_TIER controls which models and rate limits are available. Valid values:

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)

If ANTHROPIC_SUBSCRIPTION_TIER is not set, the tier is auto-detected: pro when using OAuth, api when using an API key.

Environment Variables Reference

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`

* One of ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, or CLAUDE_OAUTH_TOKEN must be set.

Supported Models

claude-3-5-sonnet-20241022 (default) - Latest Claude
claude-3-haiku-20240307 - Fast, cost-effective
claude-3-opus-20240229 - Most capable (if available)

5. Google AI Studio

Required Variables

GOOGLE_AI_API_KEY="AIza-your-google-ai-api-key"

Optional Variables

GOOGLE_AI_MODEL="gemini-2.5-pro"      # Default model

How to Get Google AI Studio API Key

Visit Google AI Studio
Sign in with your Google account
Navigate to API Keys section
Click Create API Key
Copy the key (starts with AIza)
Note: Google AI Studio provides free tier with generous limits

Supported Models

gemini-2.5-pro (default) - Latest Gemini Pro
gemini-2.0-flash - Fast, efficient responses

6. Azure OpenAI

Required Variables

AZURE_OPENAI_API_KEY="your-azureOpenai-key"
AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
AZURE_OPENAI_DEPLOYMENT_ID="your-deployment-name"

Optional Variables

AZURE_MODEL="gpt-4o"                    # Default: gpt-4o
AZURE_API_VERSION="2024-02-15-preview"  # Default API version

How to Set Up Azure OpenAI

Create Azure Account
Apply for Azure OpenAI Service access
Create Azure OpenAI Resource:
- Go to Azure Portal
- Search "OpenAI"
- Create new OpenAI resource
Deploy Model:
- Go to Azure OpenAI Studio
- Navigate to Deployments
- Create deployment with desired model
Get credentials from Keys and Endpoint section

Supported Models

gpt-4o (default) - Latest GPT-4 Optimized
gpt-4 - Standard GPT-4
gpt-35-turbo - Cost-effective option

7. Hugging Face

Required Variables

HUGGINGFACE_API_KEY="hf_your_huggingface_token"

Optional Variables

HUGGINGFACE_MODEL="Qwen/Qwen2.5-72B-Instruct"  # Default model
HUGGINGFACE_BASE_URL="https://router.huggingface.co/v1"  # Default endpoint

How to Get Hugging Face API Token

Visit Hugging Face
Sign up or log in
Go to Settings → Access Tokens
Create new token with "read" scope
Copy token (starts with hf_)

Supported Models

Requests go to the unified router (router.huggingface.co/v1), which serves a curated set of ~140 models — not the whole Hub. An id absent from the router answers 400 "not supported by any provider you have enabled", which is why the legacy defaults (DialoGPT, GPT-2, GPT-Neo) no longer work.

Qwen/Qwen2.5-72B-Instruct (default) - tool-capable, strong multilingual
meta-llama/Llama-3.1-8B-Instruct - fastest of the served set, tool-capable
meta-llama/Llama-3.3-70B-Instruct - stronger general reasoning
deepseek-ai/DeepSeek-V3 - highest quality of the served set
Qwen/Qwen2.5-Coder-32B-Instruct - code-focused
Any id listed by GET https://router.huggingface.co/v1/models

8. Ollama (Local AI)

Required Variables

None! Ollama runs locally.

Optional Variables

OLLAMA_BASE_URL="http://localhost:11434"    # Default local server
OLLAMA_MODEL="llama2"                        # Default model

How to Set Up Ollama

Install Ollama:
- macOS: brew install ollama or download from ollama.ai
- Linux: curl -fsSL https://ollama.ai/install.sh | sh
- Windows: Download installer from ollama.ai
Start Ollama Service:
```
ollama serve  # Usually auto-starts
```
Tip: To keep Ollama running in the background:
- macOS: brew services start ollama
- Linux (user): systemctl --user enable --now ollama
- Linux (system): sudo systemctl enable --now ollama

Pull Models:

ollama pull llama2
ollama pull codellama
ollama pull mistral

Supported Models

llama2 (default) - Meta's Llama 2
codellama - Code-specialized Llama
mistral - Mistral 7B
vicuna - Fine-tuned Llama
Any model from Ollama Library

9. Mistral AI

Required Variables

MISTRAL_API_KEY="your_mistral_api_key"

Optional Variables

MISTRAL_MODEL="mistral-small"               # Default model
MISTRAL_ENDPOINT="https://api.mistral.ai"   # Default endpoint

How to Get Mistral AI API Key

Visit Mistral AI Platform
Sign up for an account
Navigate to API Keys section
Generate new API key
Add billing information

Supported Models

mistral-tiny - Fastest, most cost-effective
mistral-small (default) - Balanced performance
mistral-medium - Enhanced capabilities
mistral-large - Most capable model

10. LiteLLM 🆕

Required Variables

LITELLM_BASE_URL="http://localhost:4000"         # Local LiteLLM proxy (default)
LITELLM_API_KEY="sk-anything"                    # API key for local proxy (any value works)

Optional Variables

LITELLM_MODEL="gemini-2.5-pro"                   # Default model
LITELLM_TIMEOUT="60000"                          # Request timeout (ms)

How to Use LiteLLM

LiteLLM provides access to 100+ AI models through a unified proxy interface:

Local Setup: Run LiteLLM locally with your API keys (recommended)
Self-Hosted: Deploy your own LiteLLM proxy server
Cloud Deployment: Use cloud-hosted LiteLLM instances

Available Models (Example Configuration)

openai/gpt-4o - OpenAI GPT-4 Optimized
anthropic/claude-3-5-sonnet - Anthropic Claude Sonnet
google/gemini-2.0-flash - Google Gemini Flash
mistral/mistral-large - Mistral Large model
Many more via LiteLLM Providers

Benefits

100+ Models: Access to a broad range of AI providers through one interface
Cost Optimization: Automatic routing to cost-effective models
Unified API: OpenAI-compatible API for all models
Load Balancing: Automatic failover and load distribution
Analytics: Built-in usage tracking and monitoring

11. Amazon SageMaker 🆕

Required Variables

AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="your-aws-secret-key"
AWS_REGION="us-east-1"
SAGEMAKER_DEFAULT_ENDPOINT="your-endpoint-name"

Optional Variables

SAGEMAKER_MODEL="custom-model-name"         # Model identifier (default: sagemaker-model)
SAGEMAKER_TIMEOUT="30000"                   # Request timeout in ms (default: 30000)
SAGEMAKER_MAX_RETRIES="3"                   # Retry attempts (default: 3)
AWS_SESSION_TOKEN="IQoJb3..."               # For temporary credentials
SAGEMAKER_CONTENT_TYPE="application/json"   # Request content type (default: application/json)
SAGEMAKER_ACCEPT="application/json"         # Response accept type (default: application/json)

How to Set Up Amazon SageMaker

Amazon SageMaker allows you to deploy and use your own custom trained models:

Deploy Your Model to SageMaker:
- Train your model using SageMaker Training Jobs
- Deploy model to a SageMaker Real-time Endpoint
- Note the endpoint name for configuration
Set Up AWS Credentials:
- Use IAM user with sagemaker:InvokeEndpoint permission
- Or use IAM role for EC2/Lambda/ECS deployments
- Configure AWS CLI: aws configure

Configure NeuroLink:

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"
export SAGEMAKER_DEFAULT_ENDPOINT="my-model-endpoint"

Test Connection:

npx @juspay/neurolink sagemaker status
npx @juspay/neurolink sagemaker test my-endpoint

How to Get AWS Credentials for SageMaker

Create IAM User:

Go to AWS IAM Console
Create new user with Programmatic access
Attach the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sagemaker:InvokeEndpoint"],
      "Resource": "arn:aws:sagemaker:*:*:endpoint/*"
    }
  ]
}

Download Credentials:
- Save Access Key ID and Secret Access Key
- Set as environment variables

Supported Models

SageMaker supports any custom model you deploy:

Custom Fine-tuned Models - Your domain-specific models
Foundation Model Endpoints - Large language models deployed via SageMaker
Multi-model Endpoints - Multiple models behind single endpoint
Serverless Endpoints - Auto-scaling model deployments

Model Deployment Types

Real-time Inference - Low-latency model serving (recommended)
Batch Transform - Batch processing (not supported by NeuroLink)
Serverless Inference - Pay-per-request model serving
Multi-model Endpoints - Host multiple models efficiently

Benefits

🏗️ Custom Models - Deploy and use your own trained models
💰 Cost Control - Pay only for inference usage, auto-scaling available
🔒 Enterprise Security - Full control over model infrastructure and data
⚡ Performance - Dedicated compute resources with predictable latency
🌍 Global Deployment - Available in all major AWS regions
📊 Monitoring - Built-in CloudWatch metrics and logging

CLI Commands

# Check SageMaker configuration and endpoint status
npx @juspay/neurolink sagemaker status

# Validate connection to specific endpoint
npx @juspay/neurolink sagemaker validate

# Test inference with specific endpoint
npx @juspay/neurolink sagemaker test my-endpoint

# Show current configuration
npx @juspay/neurolink sagemaker config

# Performance benchmark
npx @juspay/neurolink sagemaker benchmark my-endpoint

# List available endpoints (requires AWS CLI)
npx @juspay/neurolink sagemaker list-endpoints

# Interactive setup wizard
npx @juspay/neurolink sagemaker setup

Environment Variables Reference

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

Production Considerations

🔒 Security: Use IAM roles instead of access keys when possible
📊 Monitoring: Enable CloudWatch logging for your endpoints
💰 Cost Optimization: Use auto-scaling and serverless options
🌍 Multi-Region: Deploy endpoints in multiple regions for redundancy
⚡ Performance: Choose appropriate instance types for your workload

12. DeepSeek

Required Variables

DEEPSEEK_API_KEY="sk-your-deepseek-api-key"

Optional Variables

DEEPSEEK_MODEL="deepseek-chat"                    # Default: deepseek-chat (use deepseek-reasoner for R1)
DEEPSEEK_BASE_URL="https://api.deepseek.com"      # Default: DeepSeek API

How to Get DeepSeek API Key

Visit DeepSeek Platform
Sign up or log in to your account
Navigate to API Keys section
Click Create API Key
Copy the key

Supported Models

deepseek-chat (default) - DeepSeek V3, high-quality general chat
deepseek-reasoner - DeepSeek R1, extended chain-of-thought reasoning

13. NVIDIA NIM

Required Variables

NVIDIA_NIM_API_KEY="nvapi-your-nvidia-api-key"

Optional Variables

NVIDIA_NIM_MODEL="openai/gpt-oss-20b"                         # Default model
NVIDIA_NIM_BASE_URL="https://integrate.api.nvidia.com/v1"   # Default: NVIDIA cloud API (override for self-hosted NIM)

NIM-Specific Extras (rarely needed)

# Sampling extras passed as request body extensions
NVIDIA_NIM_TOP_K=                      # Integer, -1 = disabled (default)
NVIDIA_NIM_MIN_P=                      # Float, 0 = disabled (default)
NVIDIA_NIM_REPETITION_PENALTY=         # Float, 1.0 = disabled (default)
NVIDIA_NIM_MIN_TOKENS=                 # Integer, 0 = disabled (default)
NVIDIA_NIM_CHAT_TEMPLATE=              # Override model chat template string (advanced)

How to Get NVIDIA NIM API Key

Visit NVIDIA Build
Sign in with your NVIDIA developer account
Open Settings → API Keys
Generate a new API key (Bearer token)

Supported Models

openai/gpt-oss-20b (default) - OpenAI gpt-oss 20B, 128K context, tool calling
Any model listed at build.nvidia.com/models

14. LM Studio (Local)

LM Studio is a local provider — no API key is required for standard installations.

Optional Variables

LM_STUDIO_BASE_URL="http://localhost:1234/v1"    # Default: local LM Studio server
LM_STUDIO_MODEL=""                               # Blank = auto-discover from /v1/models
# LM_STUDIO_API_KEY=                             # Only set when running behind an auth-proxying reverse-proxy

How to Set Up LM Studio

Install LM Studio from lmstudio.ai
Open LM Studio and download a model (e.g., Llama 3.2 3B Instruct)
Click Local Server → Start Server
The server starts at http://localhost:1234/v1 by default
NeuroLink auto-discovers the loaded model; no LM_STUDIO_MODEL needed

Note: LM_STUDIO_API_KEY is only needed if you run LM Studio behind an authenticating reverse-proxy. Vanilla local installs do not require an API key.

15. llama.cpp (Local)

llama.cpp (llama-server) is a local provider — no API key is required for standard installations.

Optional Variables

LLAMACPP_BASE_URL="http://localhost:8080/v1"     # Default: local llama-server
LLAMACPP_MODEL=""                                # Blank = use whatever model llama-server has loaded
# LLAMACPP_API_KEY=                              # Only set when running behind an auth-proxying reverse-proxy

How to Set Up llama.cpp

Build llama.cpp from source: github.com/ggerganov/llama.cpp
Download a GGUF model file

Start llama-server:

# Basic usage
./llama-server -m model.gguf --port 8080

# With tool/function-call support (required for MCP tools)
./llama-server -m model.gguf --port 8080 --jinja

NeuroLink auto-discovers the loaded model; no LLAMACPP_MODEL needed

Note: LLAMACPP_API_KEY is only needed if you run llama-server behind an authenticating reverse-proxy. Vanilla local installs do not require an API key.

16. OpenAI TTS

OpenAI TTS uses the same OPENAI_API_KEY as the OpenAI LLM provider. No additional credentials are required.

Required Variables

OPENAI_API_KEY="sk-proj-your-openai-api-key"  # Shared with the OpenAI LLM provider

How to Get the API Key

See OpenAI above — the same key is used for both LLM and TTS.

Supported Models

tts-1 (default) - Optimized for speed
tts-1-hd - Optimized for audio quality

17. ElevenLabs TTS + STT

Required Variables

ELEVENLABS_API_KEY="your-elevenlabs-api-key"

One key serves the elevenlabs TTS handler, the elevenlabs-stt (Scribe) STT handler and elevenlabs-music.

Optional Variables

# API base URL including the /v1 prefix — for a proxy or a test stub.
ELEVENLABS_BASE_URL="https://api.elevenlabs.io/v1"
# Base URL for Scribe (speech-to-text) only; wins over ELEVENLABS_BASE_URL
# for STT, so transcription can go through a different host than TTS.
ELEVENLABS_STT_BASE_URL="https://api.elevenlabs.io/v1"

How to Get ElevenLabs API Key

Visit ElevenLabs
Sign up or log in to your account
Navigate to Profile → API Key
Copy the key

Supported Models

eleven_multilingual_v2 (default) - Best quality, 29 languages
eleven_v3 - Most expressive, 70+ languages, accepts language
eleven_turbo_v2_5 - Low-latency streaming, 32 languages, accepts language
eleven_flash_v2_5 - Fastest, suitable for real-time use, accepts language
eleven_flash_v2, eleven_turbo_v2, eleven_monolingual_v1 - English variants
STT: scribe_v2 (default), scribe_v2_medical; scribe_v1 and scribe_v1_experimental are deprecated

See the ElevenLabs provider guide for formats (Opus 48 kHz for ogg/opus), speed clamping, retries and the Scribe STT options.

18. Deepgram STT

Required Variables

DEEPGRAM_API_KEY="your-deepgram-api-key"

Optional Variables

# REST base URL (a proxy, a self-hosted Deepgram or a test stub). The live
# stream uses the same host on the WebSocket scheme (https → wss).
DEEPGRAM_BASE_URL="https://api.deepgram.com/v1"

How to Get Deepgram API Key

Visit Deepgram Console
Sign up or log in to your account
Navigate to API Keys
Click Create a New API Key
Copy the key

Supported Models

nova-2 (default) - High accuracy, broad language support
nova-3 - Latest, highest accuracy
base - Balanced accuracy and speed

19. Azure Speech Services (TTS + STT)

Azure Speech Services provides both text-to-speech and speech-to-text through Microsoft Azure Cognitive Services.

Required Variables

AZURE_SPEECH_KEY="your-azure-speech-key"
AZURE_SPEECH_REGION="eastus"              # Azure region where your Speech resource is deployed

Optional Variables

If you also use Google STT or Gemini Live alongside Azure, set the canonical Google credentials:

GOOGLE_AI_API_KEY="AIza-your-google-ai-studio-key"   # canonical
# GEMINI_API_KEY="AIza-your-key"                     # alias (also accepted)
# GOOGLE_API_KEY="AIza-your-key"                     # legacy alias (also accepted)
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json    # service account (Google STT)

How to Set Up Azure Speech Services

Sign in to Azure Portal
Create a Speech resource under Azure AI services
Go to Keys and Endpoint in your Speech resource
Copy Key 1 and note the Location/Region
Set AZURE_SPEECH_KEY and AZURE_SPEECH_REGION

Supported Capabilities

TTS: Azure Neural TTS with 400+ voices across 140+ languages
STT: Azure Speech-to-Text with real-time and batch transcription

Environment Variables Reference

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

20. Speech-to-Text: `transcribe()` and the built-in Whistle engine

neurolink.transcribe(), neurolink.transcribeStream(), the neurolink transcribe CLI command, the transcription server routes and audio attached to generate() all choose their engine the same way:

NEUROLINK_STT_PROVIDER, when it names a known STT provider, alias or named endpoint (an unknown name is logged and ignored);
otherwise the first configured provider in descriptor order — whisper (OpenAI-compatible), deepgram, elevenlabs-stt, google-stt, azure-stt — configured by the keys in sections 1, 17, 18 and 19 above;
otherwise Whistle, the built-in local engine, which needs no key.

Engine selection

# Default STT provider (name or alias: whisper, deepgram, scribe, google-stt,
# azure-stt, whistle, or a NEUROLINK_STT_ENDPOINTS name).
NEUROLINK_STT_PROVIDER="deepgram"
# Model for the provider NEUROLINK_STT_PROVIDER / the default rule picked.
# Not applied to a provider named explicitly in a call or with --provider.
NEUROLINK_STT_MODEL="nova-3"
# Default language code; omit it, or set "auto", to let the engine detect it.
NEUROLINK_STT_LANGUAGE="en"

OpenAI-compatible STT (`whisper`)

# Key for the /audio/transcriptions endpoint. Only the default base URL
# (api.openai.com) falls back to OPENAI_API_KEY; a custom OPENAI_STT_BASE_URL
# never receives it, and a NEUROLINK_STT_ENDPOINTS entry sends its own
# "apiKey" or no key at all.
OPENAI_STT_API_KEY="sk-..."
# Any OpenAI-compatible /audio/transcriptions server (vLLM, LiteLLM, a
# self-hosted Whisper / Qwen3-ASR wrapper). Default: https://api.openai.com/v1
OPENAI_STT_BASE_URL="http://localhost:8004/v1"
OPENAI_STT_MODEL="whisper-1"          # default model
OPENAI_STT_TIMEOUT_MS="120000"        # request timeout for long recordings

# Several self-hosted engines at once, each a provider of its own (usable as
# each other's fallback or second opinion). Keys are the provider names; a
# name that collides with a shipped provider is ignored.
# Per endpoint: baseURL (required), apiKey, model, timeoutMs, and for a server
# that can take a language prior / answer with a language verdict only (the
# IndicConformer wrapper): priorLanguageForm ("auto-{lang}") and lidModel.
NEUROLINK_STT_ENDPOINTS='{"qwen-asr":{"baseURL":"http://gpu-box:8004/v1","model":"qwen3-asr"},"indic":{"baseURL":"http://gpu-box:8007/v1","model":"indic-conformer","priorLanguageForm":"auto-{lang}","lidModel":"indic-conformer-lid"}}'

Correction layer

# Text provider and model for the correction rewrite, when a request names
# none (a request's correction.rewrite.provider/model still wins).
NEUROLINK_STT_REWRITE_PROVIDER="openai"
NEUROLINK_STT_REWRITE_MODEL="gpt-4o-mini"
# Text provider and model that render transcripts into other languages
# (`output.languages`), when a request names none; unset, the rewrite's.
NEUROLINK_STT_OUTPUT_PROVIDER="openai"
NEUROLINK_STT_OUTPUT_MODEL="gpt-4o"

The dictionary guard uses whichever decide provider is configured (see the decision providers at the top of this page) and fails open without one.

Whistle (built-in local engine)

Whistle runs on this machine in WebAssembly. Its three files (about 17 MB, pinned Hugging Face revisions verified by SHA-256) ship inside the package under models/whistle/, so nothing is downloaded. A download happens only when that copy is missing, into ~/.neurolink/models/whistle.

# Where Whistle's files live. Precedence: credentials.stt.whistle.modelDir,
# then NEUROLINK_WHISTLE_DIR, then $NEUROLINK_MODEL_DIR/whistle, then the
# package's own models/whistle, then ~/.neurolink/models/whistle.
NEUROLINK_WHISTLE_DIR="/opt/models/whistle"
NEUROLINK_MODEL_DIR="/opt/models"       # root for local model files
# 0 / false / off / no forbids the fallback download (air-gapped hosts, CI).
# With no copy anywhere Whistle then reports itself unconfigured.
NEUROLINK_WHISTLE_AUTO_DOWNLOAD="0"
# 1 / true / on / yes sends the request's vocabulary (dictionary terms
# included) to the engine as keywords. Off by default: the engine can loop
# on long keyword lists. The model name "whistle-keywords" does the same per
# request.
NEUROLINK_WHISTLE_KEYWORDS="1"

Variable	Default	Description
`NEUROLINK_STT_PROVIDER`	first configured, else Whistle	Default STT provider, alias or named endpoint
`NEUROLINK_STT_MODEL`	provider default	Model for the env-chosen provider
`NEUROLINK_STT_LANGUAGE`	`auto`	Default language; `auto` lets the engine detect
`NEUROLINK_STT_ENDPOINTS`	-	JSON map of named OpenAI-compatible STT endpoints
`NEUROLINK_STT_REWRITE_PROVIDER`	instance default	Text provider for the correction rewrite
`NEUROLINK_STT_REWRITE_MODEL`	provider default	Model for the correction rewrite
`NEUROLINK_STT_OUTPUT_PROVIDER`	the rewrite's provider	Text provider for output-language renderings
`NEUROLINK_STT_OUTPUT_MODEL`	the rewrite's model	Model for output-language renderings
`NEUROLINK_STT_REALTIME_PROFILES`	-	JSON map of profiles an OpenAI-Realtime client selects by `model` on `/v1/realtime`
`NEUROLINK_STT_EVAL_LANGFUSE_PUBLIC_KEY`	-	With the secret key: export `POST /v1/evals/stt` batches and scores to this Langfuse project
`NEUROLINK_STT_EVAL_LANGFUSE_SECRET_KEY`	-	Secret key of the evaluation Langfuse project
`NEUROLINK_STT_EVAL_LANGFUSE_BASE_URL`	`https://cloud.langfuse.com`	Langfuse host for the evaluation export
`NEUROLINK_STT_EVAL_DIR`	- (memory only)	Directory where `POST /v1/evals/stt` keeps one JSON-lines file per call, replayed on start
`OPENAI_STT_API_KEY`	`OPENAI_API_KEY` (api.openai.com only)	Key for the OpenAI-compatible STT endpoint; a custom base URL never receives `OPENAI_API_KEY`
`OPENAI_STT_PRIOR_LANGUAGE_FORM`	-	`language` template (`auto-{lang}`) that carries a language prior to a custom STT server
`OPENAI_STT_LID_MODEL`	-	Model name the custom STT server runs in language-verdict-only mode (the batch probe)
`OPENAI_STT_VOCABULARY_PROMPT`	on	Send dictionary terms as a "Names and terms used" prompt; `0` for servers that echo it
`OPENAI_STT_BASE_URL`	`https://api.openai.com/v1`	OpenAI-compatible `/audio/transcriptions` base URL
`OPENAI_STT_MODEL`	`whisper-1`	Default model for `whisper`
`OPENAI_STT_TIMEOUT_MS`	handler default	Request timeout for `whisper`
`DEEPGRAM_BASE_URL`	`https://api.deepgram.com/v1`	Deepgram REST base URL (stream uses the same host over `wss://`)
`ELEVENLABS_STT_BASE_URL`	`ELEVENLABS_BASE_URL`	ElevenLabs Scribe base URL
`NEUROLINK_WHISTLE_DIR`	see precedence above	Directory holding Whistle's files (default: the bundled copy)
`NEUROLINK_MODEL_DIR`	`~/.neurolink/models`	Root for local model files (`<root>/whistle`)
`NEUROLINK_WHISTLE_AUTO_DOWNLOAD`	on	`0`/`false`/`off`/`no` forbids the fallback download
`NEUROLINK_WHISTLE_KEYWORDS`	off	`1`/`true`/`on`/`yes` biases Whistle on the request's vocabulary

See The transcribe inference type and Whistle.

🔧 Configuration Examples

Complete .env File Example

# NeuroLink Environment Configuration - Commonly Used Providers

# OpenAI Configuration
OPENAI_API_KEY="sk-proj-your-openai-key"
OPENAI_MODEL="gpt-4o"

# Amazon Bedrock Configuration
AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="your-aws-secret"
AWS_REGION="us-east-1"
BEDROCK_MODEL="arn:aws:bedrock:us-east-1:<account_id>:inference-profile/us.anthropic.claude-3-5-sonnet-20241022-v2:0"

# Amazon SageMaker Configuration
AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="your-aws-secret"
AWS_REGION="us-east-1"
SAGEMAKER_DEFAULT_ENDPOINT="my-model-endpoint"
SAGEMAKER_TIMEOUT="30000"
SAGEMAKER_MAX_RETRIES="3"

# Google Vertex AI Configuration
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
GOOGLE_VERTEX_PROJECT="your-gcp-project"
GOOGLE_VERTEX_LOCATION="us-central1"
VERTEX_MODEL="gemini-2.5-pro"

# Anthropic Configuration (API key or OAuth token)
ANTHROPIC_API_KEY="sk-ant-api03-your-key"
# ANTHROPIC_OAUTH_TOKEN="your-oauth-token"     # Alternative: OAuth token for Claude subscription
# ANTHROPIC_SUBSCRIPTION_TIER="pro"            # Optional: free, pro, max, max_5, max_20, api
# ANTHROPIC_ENABLE_BETA_FEATURES="true"        # Optional: enable beta headers (default: true for OAuth)
# ANTHROPIC_OAUTH_REFRESH_TOKEN=""             # Optional: OAuth refresh token for auto-renewal
# ANTHROPIC_AUTH_METHOD="oauth"                # Optional: force auth method (api_key or oauth)

# Google AI Studio Configuration
GOOGLE_AI_API_KEY="AIza-your-google-ai-key"
GOOGLE_AI_MODEL="gemini-2.5-pro"

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY="your-azure-key"
AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
AZURE_OPENAI_DEPLOYMENT_ID="gpt-4o-deployment"
AZURE_MODEL="gpt-4o"

# Hugging Face Configuration
HUGGINGFACE_API_KEY="hf_your_huggingface_token"
HUGGINGFACE_MODEL="Qwen/Qwen2.5-72B-Instruct"

# Ollama Configuration (Local AI - No API Key Required)
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_MODEL="llama2"

# Mistral AI Configuration
MISTRAL_API_KEY="your_mistral_api_key"
MISTRAL_MODEL="mistral-small"

# LiteLLM Configuration
LITELLM_BASE_URL="http://localhost:4000"
LITELLM_API_KEY="sk-anything"
LITELLM_MODEL="openai/gpt-4o-mini"

# DeepSeek Configuration
DEEPSEEK_API_KEY="sk-your-deepseek-key"
DEEPSEEK_MODEL="deepseek-chat"
# DEEPSEEK_BASE_URL=https://api.deepseek.com

# NVIDIA NIM Configuration
NVIDIA_NIM_API_KEY="nvapi-your-nvidia-key"
NVIDIA_NIM_MODEL="openai/gpt-oss-20b"
# NVIDIA_NIM_BASE_URL=https://integrate.api.nvidia.com/v1

# LM Studio Configuration (local — no API key required)
LM_STUDIO_BASE_URL="http://localhost:1234/v1"
# LM_STUDIO_MODEL=                 # blank = auto-discover
# LM_STUDIO_API_KEY=               # only for reverse-proxy setups

# llama.cpp Configuration (local — no API key required)
LLAMACPP_BASE_URL="http://localhost:8080/v1"
# LLAMACPP_MODEL=                  # blank = auto-discover
# LLAMACPP_API_KEY=                # only for reverse-proxy setups

Docker/Container Configuration

# Use environment variables in containers
docker run -e OPENAI_API_KEY="sk-..." \
           -e AWS_ACCESS_KEY_ID="AKIA..." \
           -e AWS_SECRET_ACCESS_KEY="..." \
           your-app

CI/CD Configuration

# GitHub Actions example
env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

🧪 Testing Configuration

Test All Providers

# Check provider status
npx @juspay/neurolink status --verbose

# Test specific provider
npx @juspay/neurolink generate "Hello" --provider openai

# Get best available provider
npx @juspay/neurolink get-best-provider

Expected Output

✅ openai: Working (1245ms)
✅ bedrock: Working (2103ms)
✅ vertex: Working (1876ms)
✅ anthropic: Working (1654ms)
✅ azure: Working (987ms)
📊 Summary: 5/5 providers working

🔒 Security Best Practices

Attachment loading (`NEUROLINK_ATTACHMENT_*`)

What the SDK may read or fetch when a call names a file path or a URL (input.files, input.images, rag.files, transcribe({ audio })). Each variable mirrors a field of the attachments constructor option, which wins when both are set. See Attachment Security.

# Directories a local path may resolve into (":"- or ";"-separated).
# Unset: any readable file, with a one-time warning.
NEUROLINK_ATTACHMENT_ROOTS=/srv/uploads:/var/lib/app/files
# Accept http:// attachment URLs (default: HTTPS only)
NEUROLINK_ATTACHMENT_ALLOW_INSECURE_URLS=1
# Fetch loopback / private / link-local / cloud-metadata targets (default: refused)
NEUROLINK_ATTACHMENT_ALLOW_PRIVATE_NETWORK=1
# Refuse redirects outright (default: followed, re-checked per hop)
NEUROLINK_ATTACHMENT_FOLLOW_REDIRECTS=0
# Cap on any single attachment read or download, in bytes
NEUROLINK_ATTACHMENT_MAX_BYTES=67108864
# Accept Redis session/user ids containing ':' '*' '?' '[' with a warning while migrating
NEUROLINK_REDIS_ALLOW_LEGACY_IDS=1

API Key Management

✅ Use .env files for local development
✅ Use environment variables in production
✅ Rotate keys regularly (every 90 days)
❌ Never commit keys to version control
❌ Never hardcode keys in source code

.gitignore Configuration

# Add to .gitignore
.env
.env.local
.env.production
*.pem
service-account*.json

Production Deployment

Use secret management systems (AWS Secrets Manager, Azure Key Vault)
Implement key rotation policies
Monitor API usage and rate limits
Use least privilege access policies

Serving over HTTP (`neurolink serve`)

neurolink serve listens on 127.0.0.1 unless --host says otherwise, and refuses to bind a non-loopback host without an API key. These variables govern the listener; see /docs/reference/server-configuration:

NEUROLINK_SERVER_API_KEY=key1,key2          # Required on every route except the health probes
NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1    # Run open on purpose: non-loopback bind without a key, tool/MCP execution open
NEUROLINK_SERVER_ENABLE_BUILTIN_TOOLS=1     # Keep the built-in filesystem tools in the server's registry (off by default)
NEUROLINK_SERVER_WS_ALLOW_QUERY_TOKEN=1     # Accept the key as ?token= on the transcription WebSocket (off by default)
NEUROLINK_SERVER_TIMEOUT_MS=30000           # Per-request timeout (504 past it)
NEUROLINK_STT_EVAL_ENABLED=1                # Mount the STT evaluation collector, /v1/evals/stt (off by default)

🚨 Troubleshooting

Common Issues

1. "Missing API Key" Error

# Check if environment is loaded
npx @juspay/neurolink status

# Verify .env file exists and has correct format
cat .env

2. AWS Bedrock "Not Authorized" Error

✅ Verify account has model access in Bedrock console
✅ Use full inference profile ARN for Anthropic models
✅ Check IAM permissions include Bedrock access

3. Google Vertex AI Import Issues

✅ Ensure Vertex AI API is enabled
✅ Verify service account has correct permissions
✅ Check JSON file path is absolute and accessible

4. CLI Not Loading .env

✅ Ensure .env file is in current directory
✅ Check file has correct format (no spaces around =)
✅ Verify CLI version supports automatic loading

Debug Commands

# Verbose status check
npx @juspay/neurolink status --verbose

# Test specific provider
npx @juspay/neurolink generate "test" --provider openai --verbose

# Check environment loading
node -e "require('dotenv').config(); console.log(process.env.OPENAI_API_KEY)"

Provider Configuration Guide - Detailed provider setup
CLI Guide - Complete CLI command reference
API Reference - Programmatic usage examples
Framework Integration - Next.js, SvelteKit, React

🤝 Need Help?

📖 Check the troubleshooting section above
🐛 Report issues in our GitHub repository
💬 Join our Discord for community support
📧 Contact us for enterprise support

Next Steps: Once configured, test your setup with npx @juspay/neurolink status and start generating AI content!

🚀 Quick Setup​

Automatic .env Loading​

Project MCP configuration (.mcp-config.json)​

Manual Export (Also Supported)​

🏗️ Enterprise Configuration Management​

✨ NEW: Automatic Backup System​

Interface Configuration​

Performance & Optimization​

🆕 AI Enhancement Features​

Basic Enhancement Configuration​

🌐 Universal Evaluation System (Advanced)​

Primary Configuration​

Fallback Configuration​

Performance Tuning​

Cost Optimization​

Complete Universal Evaluation Example​

Testing Universal Evaluation​

🏢 Enterprise Proxy Configuration​

Proxy Environment Variables​

Authenticated Proxy​

🤖 Provider Configuration​

1. OpenAI​

Required Variables​

Optional Variables​

How to Get OpenAI API Key​

Supported Models​

2. Amazon Bedrock​

Required Variables​

Model Configuration (⚠️ Critical)​

Optional Variables​

How to Get AWS Credentials​

Bedrock Model Access Setup​

Supported Models​

3. Google Vertex AI​

Method 1: Service Account File (Recommended)​

Method 2: Service Account JSON String​

Method 3: Individual Environment Variables​

Optional Variables​

How to Set Up Google Vertex AI​

Supported Models​

4. Anthropic (Direct)​

Method 1: API Key (Traditional)​

Required Variables​

Optional Variables​

How to Get Anthropic API Key​

Method 2: OAuth Token (Claude Subscription)​

Required Variables​

Optional Variables​

Environment Variables Reference​

Supported Models​

5. Google AI Studio​

Required Variables​

Optional Variables​

How to Get Google AI Studio API Key​

Supported Models​

6. Azure OpenAI​

Required Variables​

Optional Variables​

How to Set Up Azure OpenAI​

Supported Models​

7. Hugging Face​

Required Variables​

Optional Variables​

How to Get Hugging Face API Token​

Supported Models​

8. Ollama (Local AI)​

Required Variables​

Optional Variables​

How to Set Up Ollama​

Supported Models​

9. Mistral AI​

Required Variables​

Optional Variables​

How to Get Mistral AI API Key​

Supported Models​

10. LiteLLM 🆕​

Required Variables​

Optional Variables​

How to Use LiteLLM​

Available Models (Example Configuration)​

🚀 Quick Setup

Automatic .env Loading

Project MCP configuration (`.mcp-config.json`)

Manual Export (Also Supported)

🏗️ Enterprise Configuration Management

✨ NEW: Automatic Backup System

Interface Configuration

Performance & Optimization

🆕 AI Enhancement Features

Basic Enhancement Configuration

🌐 Universal Evaluation System (Advanced)

Primary Configuration

Fallback Configuration

Performance Tuning

Cost Optimization

Complete Universal Evaluation Example

Testing Universal Evaluation

🏢 Enterprise Proxy Configuration

Proxy Environment Variables

Authenticated Proxy

🤖 Provider Configuration

1. OpenAI

Required Variables

Optional Variables

How to Get OpenAI API Key

Supported Models

2. Amazon Bedrock

Required Variables

Model Configuration (⚠️ Critical)

Optional Variables

How to Get AWS Credentials

Bedrock Model Access Setup

Supported Models

3. Google Vertex AI

Method 1: Service Account File (Recommended)

Method 2: Service Account JSON String

Method 3: Individual Environment Variables

Optional Variables

How to Set Up Google Vertex AI

Supported Models

4. Anthropic (Direct)

Method 1: API Key (Traditional)

Required Variables

Optional Variables

How to Get Anthropic API Key

Method 2: OAuth Token (Claude Subscription)

Required Variables

Optional Variables

Environment Variables Reference

Supported Models

5. Google AI Studio

Required Variables

Optional Variables

How to Get Google AI Studio API Key

Supported Models

6. Azure OpenAI

Required Variables

Optional Variables

How to Set Up Azure OpenAI

Supported Models

7. Hugging Face

Required Variables

Optional Variables

How to Get Hugging Face API Token

Supported Models

8. Ollama (Local AI)

Required Variables

Optional Variables

How to Set Up Ollama

Supported Models

9. Mistral AI

Required Variables

Optional Variables

How to Get Mistral AI API Key

Supported Models

10. LiteLLM 🆕

Required Variables

Optional Variables

How to Use LiteLLM

Available Models (Example Configuration)