Groq Multi-Environment Setup
Overview
Configure Groq API access across development, staging, and production with the right model, rate limit strategy, and secret management per environment. Key insight: use llama-3.1-8b-instant in development (cheapest, fastest), match production model in staging, and harden production with retries and fallbacks.
Prerequisites
- A Groq account with API keys from console.groq.com/keys — ideally a separate key (or organization) per environment.
- Node project with the
groq-sdk package installed (npm install groq-sdk).
NODE_ENV set per environment (development / staging / production).- A secret store for staging/production keys: GitHub Actions secrets, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.
Environment Strategy
| Environment | API Key Source | Default Model | Retry | Logging |
|---|
| Development | .env.local | llama-3.1-8b-instant | 1 | Verbose |
| Staging | CI/CD secrets | llama-3.3-70b-versatile | 3 | Standard |
| Production | Secret manager | llama-3.3-70b-versatile | 5 | Structured |
Instructions
The full, copy-paste implementation lives in the reference files — this section
is the map. Read the implementation walkthrough
for the code module, service wrapper, and verify script, and
secrets & deployment for per-platform
key management, Docker Compose profiles, and rate-limit inspection.
-
Build the config module (config/groq.ts). One configs record keyed by
environment resolves model, token budget, retries, timeout, and logging, then
validates that a key is present with an environment-specific error message.
The essential skeleton:
const configs: Record<string, GroqEnvConfig> = {
development: { model: "llama-3.1-8b-instant", maxRetries: 1, logRequests: true, },
staging: { model: "llama-3.3-70b-versatile", maxRetries: 3, logRequests: false, },
production: { model: "llama-3.3-70b-versatile", maxRetries: 5, logRequests: false, },
};
export function getGroqConfig(): GroqEnvConfig {
return configs[process.env.NODE_ENV || "development"] || configs.development;
}
See implementation.md § Step 1 for the full module including key validation and the memoized getGroqClient().
-
Wire an environment-aware service (services/groq-service.ts) that reads
the resolved config, logs only when logRequests is on, and surfaces the
retry-after header on 429. Full code in
implementation.md § Step 2.
-
Source secrets per platform. Dev reads a git-ignored .env.local; staging
uses CI/CD secrets; production pulls from a secret manager. Commands for
GitHub Actions, AWS, GCP, and Vault are in
secrets-and-deployment.md § Step 3.
-
Deploy with Docker Compose profiles so each environment injects its own
key (env var for dev/staging, external Docker secret for prod). See
secrets-and-deployment.md § Step 4.
-
Verify each environment with scripts/verify-groq-env.ts, which prints the
resolved model/retries and does a live round-trip. Full script in
implementation.md § Step 5.
-
Inspect rate limits per key via the x-ratelimit-* response headers — see
secrets-and-deployment.md § Step 6.
Output
After setup, each environment resolves its own Groq configuration and the verify
script confirms a live connection. Expected output from verify-groq-env.ts in
production:
Environment: production
Model: llama-3.3-70b-versatile
Max retries: 5
API key prefix: gsk_AbCd...
Connection: OK (312ms)
Model response: OK
You end with: a config/groq.ts that selects model/retries/logging by NODE_ENV, a service wrapper that logs verbosely only in dev, per-environment keys sourced from the right secret store, and Docker Compose profiles that never leak a production key into the process environment.
Error Handling
| Issue | Cause | Solution |
|---|
GROQ_API_KEY not set | Missing env var | Check .env.local (dev) or secret manager (prod) |
| Wrong model in env | Config mismatch | Verify with verify-groq-env.ts script |
| Rate limited in dev | Free tier limits | Use llama-3.1-8b-instant with low max_tokens |
| Staging/prod key in dev | Key leak risk | Use separate Groq organizations per environment |
Examples
Resolve the config for the current environment:
import { getGroqConfig } from "./config/groq";
const config = getGroqConfig();
console.log(config.model);
Complete a chat with the environment default model:
import { complete } from "./services/groq-service";
const answer = await complete([{ role: "user", content: "Summarize in one line." }]);
Verify production before a deploy:
NODE_ENV=production GROQ_API_KEY_PROD=gsk_... npx tsx scripts/verify-groq-env.ts
Full, runnable versions of every snippet are in
implementation.md and
secrets-and-deployment.md.
Resources
Next Steps
For deployment configuration, see the groq-deploy-integration skill, which builds on this environment strategy to wire CI/CD deploy pipelines and health checks.
