How CodeWhale Securely Stores API Keys: Environment Variables and Encrypted Secrets

CodeWhale never hard-codes API secrets in source control; instead, it injects provider keys at runtime via environment variables for local development and encrypted Cloudflare Worker secrets for production.

In the open-source CodeWhale repository, protecting sensitive credentials follows a strict "no secrets in source" policy. All API keys—whether for DeepSeek or other providers—are kept entirely outside the codebase and accessed only through secure runtime injection mechanisms. This approach ensures that even if the repository is public, actual API keys remain encrypted and inaccessible to unauthorized users.

Local Development Security

Environment Variables in .env Files

For local development, CodeWhale relies on .env files that are explicitly excluded from version control. The repository provides web/.env.example as a template showing the expected variable names, such as DEEPSEEK_API_KEY=sk-your-deepseek-key, but developers must create their own .env file locally.

The real .env file lives only on the developer's machine and is never committed to Git. This separation ensures that while the codebase documents which environment variables are required, the actual secret values remain confined to individual development environments.

Production Deployment Security

Cloudflare Worker Secrets with Wrangler

In production environments running on Cloudflare Workers, CodeWhale leverages wrangler secret to store API keys. As documented in the repository's README, administrators run:

# Store a secret encrypted on Cloudflare's edge platform

npx wrangler secret put DEEPSEEK_API_KEY

This command encrypts the value and stores it directly on Cloudflare's infrastructure. The secret never appears in the repository, build artifacts, or deployment logs. According to the CodeWhale source code workflow, this method ensures that API keys are encrypted at rest and only decrypted within the isolated Worker execution environment.

Runtime Access Patterns

Process Environment Access

The application reads injected secrets through standard environment variable interfaces. In [web/lib/kv.ts](https://github.com/Hmbown/CodeWhale/blob/main/web/lib/kv.ts), the code centralizes access to these values:

// web/lib/kv.ts – read the secret safely at runtime
export const kv = {
  DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY,   // ← injected at runtime
};

In Cloudflare Worker contexts, the code accesses these via the env object passed to the handler. This pattern ensures that only the executing process can view the secret values; they are not accessible through static analysis of the codebase.

Configuration File References

CodeWhale also supports a user-specific configuration file at ~/.codewhale/config.toml. Rather than storing the actual API key, this file contains only the name of the environment variable:

# ~/.codewhale/config.toml – reference the env var, no value stored here

[providers.deepseek]
api_key = "DEEPSEEK_API_KEY"

This indirection allows the configuration to remain in source control or dotfiles repositories without exposing sensitive credentials, as the actual value must still be provided via environment variable at runtime.

Validation and Error Handling

The codebase includes defensive programming to detect missing or placeholder secrets before executing API calls. When a required key is absent or still contains the placeholder value from .env.example, the application aborts the operation and returns a clear warning:

// Example guard – abort if the key is missing or still the placeholder
if (!env.DEEPSEEK_API_KEY || env.DEEPSEEK_API_KEY.startsWith('sk-...')) {
  return { ok: false, reason: 'missing or placeholder DEEPSEEK_API_KEY' };
}

Additionally, the helper script [scripts/tencent-lighthouse/doctor.sh](https://github.com/Hmbown/CodeWhale/blob/main/scripts/tencent-lighthouse/doctor.sh) validates the presence of required secrets before the application starts, preventing runtime failures due to missing credentials.

Summary

• CodeWhale stores API keys exclusively in environment variables for local development (via .env files) and encrypted Cloudflare Worker secrets for production.
• No secrets reside in source control: web/.env.example contains only placeholders, while real values are injected at runtime.
• Centralized access occurs through [web/lib/kv.ts](https://github.com/Hmbown/CodeWhale/blob/main/web/lib/kv.ts), which reads process.env variables.
• Configuration files like ~/.codewhale/config.toml reference environment variable names rather than storing actual key values.
• Runtime validation ensures the application fails fast with clear error messages if required secrets are missing or contain placeholder values.

Frequently Asked Questions

Does CodeWhale store API keys in the Git repository?

No. CodeWhale explicitly excludes real API keys from the repository. The .env files containing actual secrets are listed in .gitignore, and the repository only contains web/.env.example with placeholder values. Production deployments use wrangler secret, which stores keys encrypted on Cloudflare's servers, completely outside the codebase.

How does CodeWhale handle missing API keys at runtime?

The application implements validation guards that check for the presence and validity of environment variables before use. If DEEPSEEK_API_KEY is missing or matches the placeholder pattern (e.g., starts with sk-...), the code returns an error response with a descriptive message like "missing or placeholder DEEPSEEK_API_KEY" rather than attempting the API call.

What is the difference between local and production API key storage in CodeWhale?

Local development uses .env files loaded into process.env, with the actual .env file existing only on the developer's machine. Production deployments on Cloudflare Workers use wrangler secret put DEEPSEEK_API_KEY, which encrypts the key on Cloudflare's edge platform. While both methods use runtime injection, production adds the additional security layer of Cloudflare-managed encryption and access controls.

Where is the documentation for supported API providers and their environment variables?

The [docs/PROVIDERS.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/PROVIDERS.md) file in the repository lists every supported provider and the corresponding environment variable that must hold its API key. This documentation serves as the single source of truth for which secrets must be configured for each LLM provider integration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}