Environment Variables

Environment variables provide a flexible way to configure Claude Code without modifying settings files, ideal for CI/CD, containerized deployments, and per-environment configuration.

Core Variables

Authentication

# Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-..."

# API base URL (for proxy or custom endpoints)
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

Usage:

ANTHROPIC_API_KEY=sk-ant-... claude

Model Configuration

# Default model
export CLAUDE_CODE_MODEL="claude-sonnet-4.6"

# Temperature override (0.0-1.0)
export CLAUDE_CODE_TEMPERATURE="0.7"

Available models:

claude-sonnet-4.6 (default)
claude-opus-4.6
claude-sonnet-4.5

Account Information

For SDK users to provide account context:

export CLAUDE_CODE_ACCOUNT_UUID="..."
export CLAUDE_CODE_USER_EMAIL="[email protected]"
export CLAUDE_CODE_ORGANIZATION_UUID="..."

Eliminates race condition in early telemetry events.

Feature Flags

Simple Mode

Minimal Claude Code with reduced features for faster startup:

export CLAUDE_CODE_SIMPLE=true

Disables:

Skills
Session memory
Custom agents
MCP tools
Attachments
Hooks
CLAUDE.md loading

When to use: CI/CD, quick tasks, resource-constrained environments

Context Window

Control context window size:

# Disable 1M context window (use 200K)
export CLAUDE_CODE_DISABLE_1M_CONTEXT=true

When to use: Faster responses, lower costs, simpler tasks

Background Tasks

Disable background task functionality:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true

Disables:

Agent backgrounding
Ctrl+B shortcut
Task parallelization

When to use: Headless mode, CI/CD, debugging

Experimental Features

Enable experimental features:

# Agent Teams (multi-agent collaboration)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

# Disable experimental beta headers
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=true

MCP Servers

Control MCP server availability:

# Disable claude.ai MCP servers
export ENABLE_CLAUDEAI_MCP_SERVERS=false

System Configuration

Temporary Directory

Custom temp directory for internal files:

export CLAUDE_CODE_TMPDIR="/custom/tmp"

When to use: Custom temp locations, containerized environments, limited disk space

Shell Configuration

Control bash tool behavior:

# Skip login shell for better performance
export CLAUDE_BASH_NO_LOGIN=true

Effect: Bash commands use -l flag less frequently (enabled by default when shell snapshot available)

Plugin Configuration

Plugin system settings:

# Git clone timeout for plugins (milliseconds)
export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000  # 2 minutes

Default: 120000ms (changed from 30000ms in v2.1.51)

CI/CD Configuration

Optimal settings for continuous integration:

#!/bin/bash
# ci-setup.sh

# Authentication
export ANTHROPIC_API_KEY="$CI_API_KEY"

# Fast, minimal mode
export CLAUDE_CODE_SIMPLE=true
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true
export CLAUDE_CODE_DISABLE_1M_CONTEXT=true

# Use faster model
export CLAUDE_CODE_MODEL="claude-sonnet-4.6"

# Disable interactive features
export CI=true

# Run Claude in headless mode
claude -p "Run linting and tests" --no-stream

Docker Configuration

Environment variables for containerized deployments:

Dockerfile

FROM node:18-alpine

# Install Claude Code
RUN npm install -g @anthropic-ai/claude-code

# Set environment defaults
ENV CLAUDE_CODE_SIMPLE=true \
    CLAUDE_CODE_TMPDIR=/tmp/claude \
    CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true

# Runtime variables via docker run
# docker run -e ANTHROPIC_API_KEY=$API_KEY ...

CMD ["claude"]

docker-compose.yml

version: '3.8'

services:
  claude-code:
    image: claude-code:latest
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - CLAUDE_CODE_MODEL=claude-sonnet-4.6
      - CLAUDE_CODE_SIMPLE=true
      - CLAUDE_CODE_TMPDIR=/tmp/claude
    volumes:
      - ./project:/workspace
    working_dir: /workspace

Environment-Specific Configs

Development

# .env.development
ANTHROPIC_API_KEY=sk-ant-dev-...
CLAUDE_CODE_MODEL=claude-opus-4.6
CLAUDE_CODE_TEMPERATURE=0.8
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

Staging

# .env.staging
ANTHROPIC_API_KEY=sk-ant-staging-...
CLAUDE_CODE_MODEL=claude-sonnet-4.6
CLAUDE_CODE_SIMPLE=false
CLAUDE_CODE_DISABLE_1M_CONTEXT=true

Production

# .env.production
ANTHROPIC_API_KEY=sk-ant-prod-...
CLAUDE_CODE_MODEL=claude-sonnet-4.6
CLAUDE_CODE_SIMPLE=true
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true
CLAUDE_CODE_DISABLE_1M_CONTEXT=true

Load with dotenv

# Install dotenv
npm install -g dotenv-cli

# Load environment-specific config
dotenv -e .env.development -- claude
dotenv -e .env.production -- claude -p "Deploy to production"

Proxy Configuration

Configure HTTP/HTTPS proxies:

# HTTP proxy
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8443"

# No proxy for certain domains
export NO_PROXY="localhost,127.0.0.1,.example.com"

# Proxy authentication
export HTTP_PROXY="http://user:[email protected]:8080"

Or via settings.json:

{
  "proxy": {
    "http": "http://proxy.example.com:8080",
    "https": "https://proxy.example.com:8443",
    "noProxy": ["localhost", ".example.com"]
  }
}

AWS Configuration

For Bedrock users:

# AWS credentials
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# AWS session token (if using temporary credentials)
export AWS_SESSION_TOKEN="..."

# AWS profile
export AWS_PROFILE="bedrock-profile"

GCP Configuration

For Vertex AI users:

# GCP project
export GCP_PROJECT_ID="my-project"

# Service account key
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

# Vertex AI location
export GCP_LOCATION="us-central1"

Verification

Check which environment variables are active:

# View all Claude-related variables
env | grep CLAUDE

# Check specific variable
echo $ANTHROPIC_API_KEY

# Test configuration
claude doctor

Precedence

Configuration precedence (highest to lowest):

Command-line flags: claude --model opus-4.6
Environment variables: CLAUDE_CODE_MODEL=opus-4.6
Local settings: .claude/settings.local.json
Project settings: .claude/settings.json
User settings: ~/.claude/settings.json
Managed settings: ~/.claude/managed-settings.json
Defaults

Example:

# Settings file
# .claude/settings.json: {"model": "sonnet-4.6"}

# Environment overrides settings file
export CLAUDE_CODE_MODEL="opus-4.6"

# Command flag overrides everything
claude --model sonnet-4.5
# Result: Uses sonnet-4.5

Security Best Practices

Never commit API keys or secrets to version control. Use environment variables or secret management services.

Secret Management

Don’t:

# .env (committed to git)
ANTHROPIC_API_KEY=sk-ant-real-key-123  # BAD!

Do:

# .env.example (committed to git)
ANTHROPIC_API_KEY=sk-ant-your-key-here

# .env (gitignored)
ANTHROPIC_API_KEY=sk-ant-real-key-123  # GOOD

Use Secret Managers

AWS Secrets Manager:

#!/bin/bash
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id claude-api-key \
  --query SecretString \
  --output text)

claude

HashiCorp Vault:

#!/bin/bash
export ANTHROPIC_API_KEY=$(vault kv get -field=api_key secret/claude)
claude

1Password CLI:

#!/bin/bash
export ANTHROPIC_API_KEY=$(op read "op://vault/claude/api_key")
claude

Shell Integration

Bash

Add to ~/.bashrc or ~/.bash_profile:

# Claude Code configuration
export ANTHROPIC_API_KEY="your-key"
export CLAUDE_CODE_MODEL="claude-sonnet-4.6"
export CLAUDE_CODE_SIMPLE=false

# Helper function
function claude-dev() {
  CLAUDE_CODE_MODEL="opus-4.6" claude "$@"
}

function claude-quick() {
  CLAUDE_CODE_SIMPLE=true claude -p "$@"
}

Zsh

Add to ~/.zshrc:

# Claude Code
export ANTHROPIC_API_KEY="your-key"

# Aliases
alias cc="claude"
alias ccq="CLAUDE_CODE_SIMPLE=true claude -p"
alias ccd="CLAUDE_CODE_MODEL=opus-4.6 claude"

Fish

Add to ~/.config/fish/config.fish:

# Claude Code
set -x ANTHROPIC_API_KEY "your-key"
set -x CLAUDE_CODE_MODEL "claude-sonnet-4.6"

# Functions
function claude-quick
    env CLAUDE_CODE_SIMPLE=true claude -p $argv
end

Troubleshooting

Variables Not Working

Issue: Environment variables seem ignored Solutions:

Verify variable is exported: export VAR=value not VAR=value
Check spelling and case (case-sensitive)
Verify in current shell: echo $CLAUDE_CODE_MODEL
Restart shell after modifying config files

API Key Not Found

Issue: Authentication fails despite setting ANTHROPIC_API_KEY Solutions:

Verify key format: starts with sk-ant-
Check for spaces: "sk-ant-..." not " sk-ant-..."
Verify export: export not just assignment
Check key is valid: test with API request

Wrong Configuration Used

Issue: Claude uses different config than expected Solutions:

Check precedence order
Verify settings files aren’t overriding
Use claude doctor to see active config
Check for managed settings

Reference

Complete Variable List

Variable	Type	Default	Description
`ANTHROPIC_API_KEY`	string	-	API authentication key
`ANTHROPIC_BASE_URL`	string	`https://api.anthropic.com`	API endpoint
`CLAUDE_CODE_MODEL`	string	`claude-sonnet-4.6`	Default model
`CLAUDE_CODE_TEMPERATURE`	number	-	Temperature override
`CLAUDE_CODE_SIMPLE`	boolean	`false`	Enable simple mode
`CLAUDE_CODE_DISABLE_1M_CONTEXT`	boolean	`false`	Disable 1M context
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	boolean	`false`	Disable background tasks
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	boolean	`false`	Enable agent teams
`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`	boolean	`false`	Disable beta features
`ENABLE_CLAUDEAI_MCP_SERVERS`	boolean	`true`	Enable claude.ai MCP
`CLAUDE_CODE_TMPDIR`	string	system temp	Custom temp directory
`CLAUDE_BASH_NO_LOGIN`	boolean	auto	Skip login shell
`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`	number	`120000`	Plugin git timeout
`CLAUDE_CODE_ACCOUNT_UUID`	string	-	Account identifier
`CLAUDE_CODE_USER_EMAIL`	string	-	User email
`CLAUDE_CODE_ORGANIZATION_UUID`	string	-	Organization ID

Next Steps

Settings

Configure via settings files

Project Config

Set up project-specific configuration

Installation

Installation and setup

Task Automation

Automate with commands and hooks

Get Started

Core Concepts

Guides

Configuration

​Core Variables

​Authentication

​Model Configuration

​Account Information

​Feature Flags

​Simple Mode

​Context Window

​Background Tasks

​Experimental Features

​MCP Servers

​System Configuration

​Temporary Directory

​Shell Configuration

​Plugin Configuration

​CI/CD Configuration

​Docker Configuration

​Dockerfile

​docker-compose.yml

​Environment-Specific Configs

​Development

​Staging

​Production

​Load with dotenv

​Proxy Configuration

​AWS Configuration

​GCP Configuration

​Verification

​Precedence

​Security Best Practices

​Secret Management

​Use Secret Managers

​Shell Integration

​Bash

​Zsh

​Fish

​Troubleshooting

​Variables Not Working

​API Key Not Found

​Wrong Configuration Used

​Reference

​Complete Variable List

​Next Steps

Settings

Project Config

Installation

Task Automation

Build docs developers (and LLMs) love

Core Variables

Authentication

Model Configuration

Account Information

Feature Flags

Simple Mode

Context Window

Background Tasks

Experimental Features

MCP Servers

System Configuration

Temporary Directory

Shell Configuration

Plugin Configuration

CI/CD Configuration

Docker Configuration

Dockerfile

docker-compose.yml

Environment-Specific Configs

Development

Staging

Production

Load with dotenv

Proxy Configuration

AWS Configuration

GCP Configuration

Verification

Precedence

Security Best Practices

Secret Management

Use Secret Managers

Shell Integration

Bash

Zsh

Fish

Troubleshooting

Variables Not Working

API Key Not Found

Wrong Configuration Used

Reference

Complete Variable List

Next Steps