> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets Management

> Learn how to configure secrets and environment variables in VibeKit

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.

```typescript theme={"dark"}
export type SecretsConfig = {
  /** Environment variables to be passed to the sandbox */
  [key: string]: string;
};
```

## Basic Usage

### Using withSecrets

```typescript theme={"dark"}
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

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
// 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

```typescript theme={"dark"}
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

```typescript theme={"dark"}
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

```typescript theme={"dark"}
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:

```bash theme={"dark"}
# .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

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

### 1. Use Environment Variables

Always use `process.env` to access secrets:

```typescript theme={"dark"}
// ✅ 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:

```bash theme={"dark"}
# .gitignore
.env
.env.local
.env.*.local
```

### 3. Validate Required Secrets

Validate that all required secrets are present before initializing VibeKit:

```typescript theme={"dark"}
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:

<CodeGroup>
  ```.env.development Development theme={"dark"}
  DATABASE_URL=postgresql://localhost:5432/myapp_dev
  STRIPE_SECRET_KEY=sk_test_dev_key
  APP_URL=http://localhost:3000
  ```

  ```.env.staging Staging theme={"dark"}
  DATABASE_URL=postgresql://staging-db:5432/myapp_staging
  STRIPE_SECRET_KEY=sk_test_staging_key
  APP_URL=https://staging.myapp.com
  ```

  ```.env.production Production theme={"dark"}
  DATABASE_URL=postgresql://prod-db:5432/myapp_prod
  STRIPE_SECRET_KEY=sk_live_prod_key
  APP_URL=https://myapp.com
  ```
</CodeGroup>

## Complete Example

Here's a complete example showing how to set up secrets for a full-stack application:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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);
}
```