BYOK Plus Claude Code: Keeping One Env File While Your Own Key Sits Behind the Aggregator

Claude Code is a command-line tool that lets you interact with Claude models directly from your terminal. By default, it connects to Anthropic's official API, but you can point it to an aggregator instead. This lets you use your aggregator API key and access multiple models through one endpoint. In this guide, we'll show you how to set up Claude Code with an aggregator, manage credentials with a single environment file, and swap providers without editing multiple files.

Why Use an Aggregator with Claude Code?

An aggregator provides a unified API endpoint for multiple model providers (like Claude, GPT, DeepSeek, Qwen, GLM, and Kimi). Benefits include:

• One API key for all models, simplifying management.
• Unified billing in USDC, with no KYC.
• Flexible model switching by changing a single parameter.
• Potential cost savings for key contributors (you receive credits at official price ×1.1 or ×1.2).

When you use an aggregator, your provider key (e.g., Anthropic API key) is stored on the aggregator side. Your local setup only needs the aggregator's base URL and your aggregator API key.

Setting Up Claude Code with an Aggregator

Claude Code reads configuration from environment variables. The key variables are:

• ANTHROPICBASEURL: The base URL of the API endpoint.
• ANTHROPICAPIKEY: Your API key for authentication.

To use an aggregator, set these variables to point to the aggregator's endpoint and your aggregator API key.

Step 1: Obtain Your Aggregator API Key

Sign up with the aggregator and generate an API key. This key will be used for all requests.

Step 2: Create an Environment File

Create a file named .env in your project directory or home directory. Add the following lines:

ANTHROPIC_BASE_URL=https://api.aggregator.example.com
ANTHROPIC_API_KEY=your_aggregator_api_key_here

Replace the URL with the aggregator's actual base URL and the key with your generated key.

Step 3: Load the Environment Variables

Claude Code does not automatically load .env files. You need to export these variables before running Claude Code. You can do this by sourcing the file:

export $(grep -v '^#' .env | xargs)

Or use a tool like dotenv:

npx dotenv-cli -e .env -- claude

Alternatively, add the exports directly to your shell profile (e.g., .bashrc or .zshrc).

Step 4: Run Claude Code

Now run Claude Code as usual. It will use the aggregator's endpoint and your aggregator API key.

claude

How Authentication Works

When you set ANTHROPICAPIKEY to your aggregator key, Claude Code sends this key in the Authorization header (or x-api-key header, depending on the API specification). The aggregator validates your key and forwards the request to the appropriate provider using its own stored provider key. This means your provider key never leaves the aggregator's secure environment.

Swapping Providers

One of the main advantages of using an aggregator is the ability to switch between models and providers without changing your authentication. To use a different model, you typically specify it in the request. Claude Code may have a --model flag or a configuration option to set the model name.

For example, to use a different Claude model:

claude --model claude-3-opus-20240229

Check your aggregator's documentation for the exact model names supported.

If you need to switch to a different aggregator or back to the official API, simply update the ANTHROPICBASEURL and ANTHROPICAPIKEY in your .env file. No other changes are needed.

Managing Multiple Configurations

If you work with multiple aggregators or want to keep separate configurations for different projects, you can use multiple .env files and load the appropriate one. For example:

• .env.aggregator1
• .env.aggregator2
• .env.official

Then load the desired file before running Claude Code.

Security Considerations

• Keep your .env file out of version control (add it to .gitignore).
• Do not share your API key.
• Use environment variables or a secrets manager in production.

Troubleshooting

• Authentication errors: Double-check your API key and base URL.
• Connection issues: Ensure the base URL is correct and reachable.
• Model not found: Verify the model name with your aggregator's documentation.

Conclusion

Configuring Claude Code to use an aggregator is straightforward: set the base URL and API key in your environment, and you're ready to go. This setup lets you manage multiple models with a single key and easily swap providers by editing one file. Remember to follow security best practices and consult your aggregator's docs for specific details.