Environment variables

OpenCode uses environment variables for configuration, especially for API keys and provider credentials. This page documents all environment variables that OpenCode recognizes.

API provider credentials

These environment variables configure authentication for various AI providers.

Anthropic (Claude)

ANTHROPIC_API_KEY

string

API key for Anthropic’s Claude models.Provider: Anthropic
Models: Claude 4, Claude 3.5, Claude 3.7, and all Claude model variantsGet your API key from the Anthropic Console.

export ANTHROPIC_API_KEY="sk-ant-..."

If this key is present and valid, OpenCode will default to using Claude 4 Sonnet for all agents.

OpenAI

OPENAI_API_KEY

string

API key for OpenAI models.Provider: OpenAI
Models: GPT-4.1, GPT-4.5, GPT-4o, O1, O3, O4, and all OpenAI variantsGet your API key from the OpenAI Platform.

export OPENAI_API_KEY="sk-..."

OpenCode prioritizes providers in this order: Copilot > Anthropic > OpenAI. If multiple keys are present, Anthropic will be used by default.

Google Gemini

GEMINI_API_KEY

string

API key for Google Gemini models via Google AI Studio.Provider: Google Gemini
Models: Gemini 2.5, Gemini 2.5 Flash, Gemini 2.0 Flash, Gemini 2.0 Flash LiteGet your API key from Google AI Studio.

export GEMINI_API_KEY="AI..."

This is different from Google Cloud VertexAI. See VERTEXAI_PROJECT for VertexAI configuration.

GitHub Copilot

GITHUB_TOKEN

string

GitHub token with Copilot permissions for accessing GitHub Copilot models.Provider: GitHub Copilot (Experimental)
Models: GPT-4o, GPT-4.1, Claude 3.5/3.7/4 Sonnet, O1, O3-mini, O4-mini, Gemini 2.0/2.5Requirements:

Copilot chat in the IDE enabled in GitHub settings
One of:
- VSCode GitHub Copilot chat extension
- GitHub gh CLI
- Neovim GitHub Copilot plugin (copilot.vim or copilot.lua)
- GitHub token with copilot permissions

If using one of the above tools, authenticate the tool with your GitHub account. This creates a token at:

~/.config/github-copilot/hosts.json
~/.config/github-copilot/apps.json
$XDG_CONFIG_HOME/github-copilot/hosts.json

Alternatively, set the token explicitly:

export GITHUB_TOKEN="ghp_..."

Copilot support is currently experimental. Some features may not work as expected.

Groq

GROQ_API_KEY

string

API key for Groq cloud inference.Provider: Groq
Models: Llama 4, QWEN QWQ-32b, Deepseek R1 distill Llama 70b, Llama 3.3 70bGet your API key from Groq Console.

export GROQ_API_KEY="gsk_..."

OpenRouter

OPENROUTER_API_KEY

string

API key for OpenRouter, which provides access to multiple AI models through a unified API.Provider: OpenRouter
Models: Various models with openrouter. prefixGet your API key from OpenRouter.

export OPENROUTER_API_KEY="sk-or-..."

xAI (Grok)

XAI_API_KEY

string

API key for xAI’s Grok models.Provider: xAI
Models: Grok-3 Beta, Grok-3 Mini, Grok-3 Fast variantsGet your API key from xAI Console.

export XAI_API_KEY="xai-..."

Cloud provider credentials

These environment variables configure access to cloud-based AI services.

AWS Bedrock

AWS Bedrock provides access to Claude models through Amazon’s infrastructure.

AWS_ACCESS_KEY_ID

string

AWS access key ID for authenticating with AWS services.

export AWS_ACCESS_KEY_ID="AKIA..."

AWS_SECRET_ACCESS_KEY

string

AWS secret access key corresponding to the access key ID.

export AWS_SECRET_ACCESS_KEY="..."

AWS_REGION

string

AWS region for Bedrock API calls.

export AWS_REGION="us-east-1"

If not set, OpenCode will check AWS_DEFAULT_REGION.

AWS_DEFAULT_REGION

string

Fallback AWS region if AWS_REGION is not set.

export AWS_DEFAULT_REGION="us-west-2"

AWS_PROFILE

string

AWS profile name to use from ~/.aws/credentials and ~/.aws/config.

export AWS_PROFILE="my-profile"

AWS_DEFAULT_PROFILE

string

Fallback AWS profile if AWS_PROFILE is not set.

export AWS_DEFAULT_PROFILE="default"

AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

string

Used when running on ECS with task IAM roles. Set automatically by AWS.

This is typically set automatically when running in AWS ECS. You don’t need to set it manually.

AWS_CONTAINER_CREDENTIALS_FULL_URI

string

Alternative credentials endpoint for ECS tasks. Set automatically by AWS.

This is typically set automatically when running in AWS ECS. You don’t need to set it manually.

Azure OpenAI

Azure OpenAI Service provides OpenAI models through Microsoft Azure.

AZURE_OPENAI_ENDPOINT

string

Azure OpenAI service endpoint URL.Format: https://<resource-name>.openai.azure.com

export AZURE_OPENAI_ENDPOINT="https://my-resource.openai.azure.com"

This variable must be set for Azure OpenAI to be enabled, even when using Entra ID authentication.

AZURE_OPENAI_API_KEY

string

API key for Azure OpenAI service. Optional when using Entra ID authentication.

export AZURE_OPENAI_API_KEY="..."

This can be omitted when using Azure Entra ID (formerly Azure AD) credentials for authentication.

AZURE_OPENAI_API_VERSION

string

Azure OpenAI API version to use.Format: YYYY-MM-DD-preview or YYYY-MM-DD

export AZURE_OPENAI_API_VERSION="2025-04-01-preview"

Google Cloud VertexAI

VertexAI provides access to Gemini models through Google Cloud Platform.

VERTEXAI_PROJECT

string

Google Cloud project ID for VertexAI.

export VERTEXAI_PROJECT="my-project-id"

Both VERTEXAI_PROJECT and VERTEXAI_LOCATION must be set for VertexAI to be enabled.

VERTEXAI_LOCATION

string

Google Cloud location/region for VertexAI API calls.Common values: us-central1, us-east1, europe-west1, asia-northeast1

export VERTEXAI_LOCATION="us-central1"

GOOGLE_CLOUD_PROJECT

string

Alternative to VERTEXAI_PROJECT. Google Cloud project ID.

export GOOGLE_CLOUD_PROJECT="my-project-id"

GOOGLE_CLOUD_REGION

string

Alternative to VERTEXAI_LOCATION. Google Cloud region.

export GOOGLE_CLOUD_REGION="us-central1"

GOOGLE_CLOUD_LOCATION

string

Alternative to VERTEXAI_LOCATION and GOOGLE_CLOUD_REGION.

export GOOGLE_CLOUD_LOCATION="us-central1"

Self-hosted models

LOCAL_ENDPOINT

string

Endpoint URL for self-hosted OpenAI-compatible model servers.Use this to connect to locally running models or custom inference servers that implement the OpenAI API specification.Compatible servers:

llama.cpp server
Ollama (with OpenAI compatibility)
vLLM
Text Generation Inference (TGI)
LocalAI
Any OpenAI-compatible API

export LOCAL_ENDPOINT="http://localhost:1235/v1"

Example with Ollama:

# Start Ollama with OpenAI compatibility
export LOCAL_ENDPOINT="http://localhost:11434/v1"

Example configuration:

{
  "agents": {
    "coder": {
      "model": "local.granite-3.3-2b-instruct@q8_0",
      "reasoningEffort": "high"
    }
  }
}

System configuration

SHELL

string

Default shell to use for the bash tool. If not specified, OpenCode defaults to /bin/bash.This variable is typically set automatically by your system but can be overridden.

export SHELL="/bin/zsh"

You can also configure the shell in .opencode.json:

{
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  }
}

OPENCODE_DEV_DEBUG

string

Enable development debug mode. When set to "true", OpenCode writes debug logs to a file instead of using the TUI logger.Values: "true" or unset

export OPENCODE_DEV_DEBUG="true"

When enabled:

Logs written to <data-directory>/debug.log
Messages saved to <data-directory>/messages/
Useful for debugging OpenCode itself

This is primarily for OpenCode development and debugging. Regular users should use the --debug flag instead.

Configuration precedence

OpenCode loads configuration from multiple sources in this order (highest to lowest priority):

Command-line flags (e.g., --debug)
Environment variables (documented on this page)
Local config file (.opencode.json in working directory)
Global config file:
- $HOME/.opencode.json
- $XDG_CONFIG_HOME/opencode/.opencode.json
- $HOME/.config/opencode/.opencode.json
Default values

Provider priority

When multiple API keys are present, OpenCode selects the default provider in this order:

GitHub Copilot (GITHUB_TOKEN)
Anthropic (ANTHROPIC_API_KEY)
OpenAI (OPENAI_API_KEY)
Google Gemini (GEMINI_API_KEY)
Groq (GROQ_API_KEY)
OpenRouter (OPENROUTER_API_KEY)
xAI (XAI_API_KEY)
AWS Bedrock (AWS credentials)
Azure OpenAI (AZURE_OPENAI_ENDPOINT)
Google Cloud VertexAI (VERTEXAI_PROJECT + VERTEXAI_LOCATION)

You can override this default by explicitly configuring models in .opencode.json.

Security best practices

Never commit API keys to version control. Always use environment variables or secure secret management systems.

Recommended practices

Use environment variables:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

Use a secrets manager:

# Example with 1Password CLI
export OPENAI_API_KEY=$(op read "op://Private/OpenAI/api_key")

Use project-specific env files (not committed):

# .env (add to .gitignore)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Then source before running:

source .env && opencode

Use shell-specific secure storage:

# macOS Keychain
security find-generic-password -s "openai-key" -w

Restrict file permissions:
```
chmod 600 ~/.opencode.json
```

Verification

To verify which provider OpenCode will use:

# Run with debug flag to see provider selection
opencode -d

The debug output will show:

Which API keys were found
Which provider was selected as default
Any configuration issues

Troubleshooting

No valid provider available

If you see “no valid provider available”, ensure:

At least one API key environment variable is set
The API key is valid and has not expired
For cloud providers (AWS, Azure, VertexAI), all required variables are set

Provider not working as expected

Check:

API key format is correct
No typos in environment variable names
Environment variables are exported (use export)
Variables are set in the same shell session

# Verify environment variables are set
env | grep -E '(ANTHROPIC|OPENAI|GEMINI|GITHUB_TOKEN|GROQ|AWS|AZURE|VERTEXAI|LOCAL_ENDPOINT)'

Cloud provider credentials

For AWS Bedrock:

# Test AWS credentials
aws sts get-caller-identity

For Azure OpenAI:

# Verify all required variables
echo $AZURE_OPENAI_ENDPOINT
echo $AZURE_OPENAI_API_KEY
echo $AZURE_OPENAI_API_VERSION

For Google Cloud VertexAI:

# Check authentication
gcloud auth list
gcloud config get-value project

CLI Reference

Configuration

Environment variables

API provider credentials

Anthropic (Claude)

OpenAI

Google Gemini

GitHub Copilot

Groq

OpenRouter

xAI (Grok)

Cloud provider credentials

AWS Bedrock

Azure OpenAI

Google Cloud VertexAI

Self-hosted models

System configuration

Configuration precedence

Provider priority

Security best practices

Recommended practices

Verification

Troubleshooting

No valid provider available

Provider not working as expected

Cloud provider credentials

Build docs developers (and LLMs) love

CLI Reference

Configuration

​API provider credentials

​Anthropic (Claude)

​OpenAI

​Google Gemini

​GitHub Copilot

​Groq

​OpenRouter

​xAI (Grok)

​Cloud provider credentials

​AWS Bedrock

​Azure OpenAI

​Google Cloud VertexAI

​Self-hosted models

​System configuration

​Configuration precedence

​Provider priority

​Security best practices

​Recommended practices

​Verification

​Troubleshooting

​No valid provider available

​Provider not working as expected

​Cloud provider credentials

Build docs developers (and LLMs) love

API provider credentials

Anthropic (Claude)

OpenAI

Google Gemini

GitHub Copilot

Groq

OpenRouter

xAI (Grok)

Cloud provider credentials

AWS Bedrock

Azure OpenAI

Google Cloud VertexAI

Self-hosted models

System configuration

Configuration precedence

Provider priority

Security best practices

Recommended practices

Verification

Troubleshooting

No valid provider available

Provider not working as expected

Cloud provider credentials