Cohere Multi-Environment Setup
Overview
Configure Cohere API v2 across dev/staging/prod with environment-specific API keys, model selection, and budget controls.
Prerequisites
- Separate Cohere API keys per environment (trial for dev, production for staging/prod)
- Secret management solution (Vault, AWS Secrets Manager, GCP Secret Manager)
- Environment detection in application
Environment Strategy
| Environment | API Key Type | Model | maxTokens | Caching |
|---|
| Development | Trial (free) | command-r7b-12-2024 | 200 | Disabled |
| Staging | Production | command-r-08-2024 | 1000 | Enabled |
| Production | Production | command-a-03-2025 | 4096 | Enabled |
Instructions
Step 1: Configuration Structure
type Environment = 'development' | 'staging' | 'production';
interface CohereEnvConfig {
chatModel: string;
embedModel: string;
rerankModel: string;
maxTokens: number;
cacheEnabled: boolean;
cacheTtlMs: number;
retries: number;
timeoutSeconds: number;
}
const configs: Record<Environment, CohereEnvConfig> = {
development: {
chatModel: 'command-r7b-12-2024',
embedModel: 'embed-v4.0',
rerankModel: 'rerank-v3.5',
maxTokens: 200,
cacheEnabled: false,
cacheTtlMs: 0,
retries: 1,
timeoutSeconds: 30,
},
staging: {
chatModel: 'command-r-08-2024',
embedModel: 'embed-v4.0',
rerankModel: 'rerank-v3.5',
maxTokens: 1000,
cacheEnabled: true,
cacheTtlMs: 5 * 60 * 1000,
retries: 3,
timeoutSeconds: 60,
},
production: {
chatModel: 'command-a-03-2025',
embedModel: 'embed-v4.0',
rerankModel: 'rerank-v3.5',
maxTokens: 4096,
cacheEnabled: true,
cacheTtlMs: 15 * 60 * 1000,
retries: 5,
timeoutSeconds: 120,
},
};
function detectEnvironment(): Environment {
const env = process.env.NODE_ENV ?? 'development';
if (['development', 'staging', 'production'].includes(env)) {
return env as Environment;
}
return 'development';
}
export function getCohereConfig(): CohereEnvConfig & { environment: Environment } {
const env = detectEnvironment();
return { ...configs[env], environment: env };
}
Step 2: Environment-Aware Client
import { CohereClientV2 } from 'cohere-ai';
import { getCohereConfig } from '../config/cohere';
let instance: CohereClientV2 | null = null;
export function getCohere(): CohereClientV2 {
if (!instance) {
const config = getCohereConfig();
if (!process.env.CO_API_KEY) {
throw new Error(`CO_API_KEY not set for ${config.environment} environment`);
}
instance = new CohereClientV2({
token: process.env.CO_API_KEY,
timeoutInSeconds: config.timeoutSeconds,
});
console.log(`[cohere] Initialized for ${config.environment} (model: ${config.chatModel})`);
}
return instance;
}
Step 3: Secret Management
CO_API_KEY=trial-key-for-dev
gh secret set CO_API_KEY --body "production-key-for-ci"
aws secretsmanager create-secret \
--name cohere/staging/api-key \
--secret-string "staging-production-key"
aws secretsmanager create-secret \
--name cohere/production/api-key \
--secret-string "prod-production-key"
echo -n "staging-key" | gcloud secrets create cohere-api-key-staging --data-file=-
echo -n "prod-key" | gcloud secrets create cohere-api-key-prod --data-file=-
vault kv put secret/cohere/staging api_key="staging-key"
vault kv put secret/cohere/production api_key="prod-key"
Step 4: Environment Guards
function guardExpensiveOperation(operation: string): void {
const config = getCohereConfig();
if (config.environment === 'development') {
console.warn(`[cohere] ${operation} using trial key — limited to 20 calls/min`);
}
}
function validateKeyForEnv(): void {
const config = getCohereConfig();
const key = process.env.CO_API_KEY ?? '';
if (config.environment === 'production' && key.length < 30) {
throw new Error('Production requires a production API key (not trial)');
}
}
Step 5: Per-Environment API Calls
import { getCohereConfig } from '../config/cohere';
export async function chat(message: string): Promise<string> {
const config = getCohereConfig();
const cohere = getCohere();
const response = await cohere.chat({
model: config.chatModel,
messages: [{ role: 'user', content: message }],
maxTokens: config.maxTokens,
});
return response.message?.content?.[0]?.text ?? '';
}
export async function embed(texts: string[]): Promise<number[][]> {
const config = getCohereConfig();
const cohere = getCohere();
const response = await cohere.embed({
model: config.,
texts,
: ,
: config. === ? [] : [],
});
response.. ?? response..;
}
Step 6: Docker Compose for Local Multi-Env Testing
services:
app-dev:
build: .
environment:
- NODE_ENV=development
- CO_API_KEY=${CO_API_KEY_DEV}
ports:
- "3000:3000"
app-staging:
build: .
environment:
- NODE_ENV=staging
- CO_API_KEY=${CO_API_KEY_STAGING}
ports:
- "3001:3000"
Output
- Per-environment Cohere configuration (model, tokens, timeout)
- Secret management across dev/staging/prod
- Environment guards preventing misuse
- Docker compose for local multi-env testing
Error Handling
| Issue | Cause | Solution |
|---|
| Trial key in production | Wrong secret | Validate key length at startup |
| Rate limited in dev | Trial key limits | Use 20 calls/min budget |
| Model not found | Typo in config | Validate model IDs at startup |
| Config merge fails | Missing environment | Default to development |
Resources
Next Steps
For observability setup, see cohere-observability.
