VibeKit allows you to securely pass environment variables to your sandbox environment through the secrets configuration. This guide explains how to configure and manage these secrets.

​
Configuration Overview

Secrets in VibeKit are environment variables that get passed to the sandbox where your code executes. They are configured through the optional secrets object when initializing the VibeKit class. 
export type SecretsConfig = {
  /** Environment variables to be passed to the sandbox */
  [key: string]: string;
};

​
Basic Usage

​
Using withSecrets

import { VibeKit } from "@vibe-kit/sdk";

const vibeKit = new VibeKit()
  .withAgent({
    type: "claude",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-sonnet-4-20250514",
  })
  .withSandbox(e2bProvider)
  .withSecrets({
    DATABASE_URL: process.env.DATABASE_URL!,
    REDIS_URL: process.env.REDIS_URL!,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
    API_BASE_URL: process.env.API_BASE_URL!,
  });

​
Adding Secrets to Your Configuration

import { VibeKit, VibeKitConfig } from "@vibe-kit/sdk";

const config: VibeKitConfig = {
  agent: {
    type: "codex",
    model: {
      apiKey: process.env.OPENAI_API_KEY!,
    },
  },
  environment: {
    e2b: {
      apiKey: process.env.E2B_API_KEY!,
    },
  },
  secrets: {
    // These environment variables will be available in your sandbox
    DATABASE_URL: process.env.DATABASE_URL!,
    REDIS_URL: process.env.REDIS_URL!,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
    API_BASE_URL: process.env.API_BASE_URL!,
  },
};

const vibeKit = new VibeKit(config);

​
Accessing Secrets in Generated Code

Once configured, these secrets are available as environment variables in your sandbox: 
// In your generated code running in the sandbox
const databaseUrl = process.env.DATABASE_URL;
const stripeKey = process.env.STRIPE_SECRET_KEY;

// Use them in your application
const db = new Database(databaseUrl);
const stripe = new Stripe(stripeKey);

​
Common Use Cases

​
Database Connections

const config: VibeKitConfig = {
  // ... other configuration
  secrets: {
    DATABASE_URL: process.env.DATABASE_URL!,
    DB_USER: process.env.DB_USER!,
    DB_PASSWORD: process.env.DB_PASSWORD!,
    DB_HOST: process.env.DB_HOST!,
    DB_PORT: process.env.DB_PORT!,
  },
};

​
API Keys and External Services

const config: VibeKitConfig = {
  // ... other configuration
  secrets: {
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
    SENDGRID_API_KEY: process.env.SENDGRID_API_KEY!,
    AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID!,
    AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY!,
    TWILIO_ACCOUNT_SID: process.env.TWILIO_ACCOUNT_SID!,
    TWILIO_AUTH_TOKEN: process.env.TWILIO_AUTH_TOKEN!,
  },
};

​
Application Configuration

const config: VibeKitConfig = {
  // ... other configuration
  secrets: {
    NODE_ENV: process.env.NODE_ENV || "development",
    PORT: process.env.PORT || "3000",
    JWT_SECRET: process.env.JWT_SECRET!,
    CORS_ORIGIN: process.env.CORS_ORIGIN!,
    APP_URL: process.env.APP_URL!,
  },
};

​
Environment Variables Setup

Create a .env file in your project root to store your secrets: 
# .env
# VibeKit Configuration
OPENAI_API_KEY=sk-proj-your-openai-key
E2B_API_KEY=e2b_your-e2b-key

# Application Secrets (passed to sandbox)
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
STRIPE_SECRET_KEY=sk_test_your-stripe-key
SENDGRID_API_KEY=SG.your-sendgrid-key
JWT_SECRET=your-jwt-secret-key
APP_URL=http://localhost:3000

​
Security Best Practices

Never commit secrets or API keys to version control. Always use environment variables and ensure your .env file is in your .gitignore.

​
1. Use Environment Variables

Always use process.env to access secrets: 
// ✅ Good
secrets: {
  API_KEY: process.env.API_KEY!,
}

// ❌ Bad - Never hardcode secrets
secrets: {
  API_KEY: "secret-123-abc",
}

​
2. Add .env to .gitignore

Ensure your .env file is not committed to version control: 
# .gitignore
.env
.env.local
.env.*.local

​
3. Validate Required Secrets

Validate that all required secrets are present before initializing VibeKit: 
const requiredSecrets = [
  'DATABASE_URL',
  'STRIPE_SECRET_KEY',
  'JWT_SECRET'
];

requiredSecrets.forEach((secret) => {
  if (!process.env[secret]) {
    throw new Error(`Missing required environment variable: ${secret}`);
  }
});

const config: VibeKitConfig = {
  // ... other configuration
  secrets: {
    DATABASE_URL: process.env.DATABASE_URL!,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
    JWT_SECRET: process.env.JWT_SECRET!,
  },
};

​
4. Use Different Environments

Use different environment files for different stages: 
DATABASE_URL=postgresql://localhost:5432/myapp_dev
STRIPE_SECRET_KEY=sk_test_dev_key
APP_URL=http://localhost:3000

​
Complete Example

Here’s a complete example showing how to set up secrets for a full-stack application: 
import { VibeKit, VibeKitConfig } from "@vibe-kit/sdk";

// Validate required environment variables
const requiredEnvVars = [
  'OPENAI_API_KEY',
  'E2B_API_KEY',
  'DATABASE_URL',
  'JWT_SECRET'
];

requiredEnvVars.forEach((envVar) => {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
});

const config: VibeKitConfig = {
  agent: {
    type: "codex",
    model: {
      apiKey: process.env.OPENAI_API_KEY!,
    },
  },
  environment: {
    e2b: {
      apiKey: process.env.E2B_API_KEY!,
    },
  },
  github: {
    token: process.env.GITHUB_TOKEN!,
    repository: "your-org/your-repo",
  },
  secrets: {
    // Database
    DATABASE_URL: process.env.DATABASE_URL!,
    
    // Authentication
    JWT_SECRET: process.env.JWT_SECRET!,
    
    // External APIs
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY!,
    SENDGRID_API_KEY: process.env.SENDGRID_API_KEY!,
    
    // Application Config
    NODE_ENV: process.env.NODE_ENV || "development",
    PORT: process.env.PORT || "3000",
    CORS_ORIGIN: process.env.CORS_ORIGIN || "http://localhost:3000",
    
    // Custom secrets
    CUSTOM_API_ENDPOINT: process.env.CUSTOM_API_ENDPOINT!,
    WEBHOOK_SECRET: process.env.WEBHOOK_SECRET!,
  },
};

const vibeKit = new VibeKit(config);

​
Troubleshooting

​
Common Issues

  1. Missing Environment Variable: Make sure all required secrets are set in your environment
  2. Secrets Not Available in Sandbox: Ensure secrets are properly configured in the secrets object
  3. Type Errors: Use the non-null assertion operator ! or provide default values for optional secrets

​
Testing Your Configuration

You can test your configuration by initializing VibeKit: 
try {
  const vibeKit = new VibeKit(config);
  console.log("✅ VibeKit initialized successfully");
  console.log("🔐 Secrets configured:", Object.keys(config.secrets || {}));
} catch (error) {
  console.error("❌ Configuration error:", error.message);
}