Clay Multi-Environment Setup

Overview

Configure Clay across development, staging, and production environments with isolated API keys, environment-specific settings, and proper secret management.

Prerequisites

• Separate Clay API keys per environment

• Secret management solution (environment variables, Vault, or cloud secrets)

• CI/CD pipeline with environment-aware deployment

• Application with environment detection logic

Environment Strategy

Environment Purpose API Key Source Settings

Development Local development .env.local

Debug enabled, relaxed limits

Staging Pre-production testing CI/CD secrets Production-like settings

Production Live traffic Secret manager Optimized, hardened

Instructions

Step 1: Create Configuration Structure

Create config/clay/ with base.ts (shared defaults), per-environment override files, and an index.ts resolver.

Step 2: Define Base and Environment Configs

Base config sets timeout (30s), retries (3), and cache (5 min TTL). Dev disables cache and enables debug. Prod extends timeout to 60s, retries to 5, and cache TTL to 10 min.

Step 3: Implement Environment Detection

Detect environment from NODE_ENV and VERCEL_ENV . Throw if API key is missing for the detected environment.

Step 4: Configure Secret Management

Store keys in .env.local (dev), GitHub Environment Secrets (staging/prod), or cloud secret managers (AWS/GCP). Reference in CI workflows per environment.

Step 5: Add Startup Validation

Use Zod to validate config at startup, ensuring API key is set, environment is valid, and timeout is positive.

For detailed TypeScript implementations and CI workflow configs, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Error Handling

Issue Cause Solution

Wrong environment Missing NODE_ENV Set environment variable in deployment

Secret not found Wrong secret path Verify secret manager configuration

Cross-env data leak Shared API key Use separate keys per environment

Config validation fail Missing field Add startup validation with Zod schema

Resources

• Clay API Documentation

• Clay Environments

Next Steps

For deployment, see clay-deploy-integration .

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

See deployment implementation details for output format specifications.

Examples

Basic usage: Apply clay multi env setup to a standard project setup with default configuration options.

Advanced scenario: Customize clay multi env setup for production environments with multiple constraints and team-specific requirements.