Skip to main content

​
Environment Variable Management

​
Overview

This project intentionally tracks the .env file in git, which differs from standard best practices. This document explains the rationale and security considerations.

​
Why .env is Tracked

​
Rationale

  1. Vibecode Development Environment: This project is developed within the Vibecode Incorporated development system
  2. Controlled Access: Repository access is limited to authorized team members
  3. Development Keys Only: The tracked .env contains development/staging credentials, not production secrets
  4. Simplified Onboarding: New developers get working environment immediately after clone
  5. Consistency: Ensures all developers use the same environment configuration

​
Security Considerations

What’s Safe:
  • ✅ Supabase publishable key (protected by RLS policies)
  • ✅ Development API keys with usage limits
  • ✅ Non-sensitive configuration values
What’s Protected:
  • ❌ Production database credentials (stored in EAS Secrets)
  • ❌ Production API keys (stored in Supabase Secrets)
  • ❌ Service role keys (never committed)

​
Cursor Cloud Agent Secrets

For AI Agents and Cloud Development: When using Cursor Cloud Agents (background agents), secrets should be managed via Cursor’s built-in secret management rather than local .env files.

​
Why Use Cursor Secrets?

  • ✅ Persistent across sessions - Secrets survive agent restarts
  • ✅ Secure storage - Managed by Cursor, encrypted at rest
  • ✅ Automatic injection - Available as environment variables automatically
  • ✅ Works with MCP servers - Shared with Model Context Protocol integrations
  • ✅ No local file management - No need to manage ~/.sentryclirc manually

​
Setting Up Cloud Agent Secrets

  1. Open Cursor Settings:
    • Cursor → Settings (or Cmd+, on Mac)
    • Navigate to: Cloud Agents → Secrets
  2. Add Required Secrets: MCP Server Secrets (Required for AI Agents):
    • SENTRY_AUTH_TOKEN - Sentry User Auth Token (for CLI and MCP)
    • GITHUB_PERSONAL_ACCESS_TOKEN - GitHub Personal Access Token
    • INTERCOM_ACCESS_TOKEN - Intercom API Access Token
    • SUPABASE_ACCESS_TOKEN - Supabase Account Access Token
    • SUPABASE_PROJECT_REF - Supabase Project Reference ID
    App Runtime Secrets (Optional - can use .env instead):
    • EXPO_PUBLIC_SUPABASE_URL - Supabase project URL
    • EXPO_PUBLIC_SUPABASE_KEY - Supabase publishable key
    See MCP Integrations for detailed setup instructions for each secret.
  3. Restart Cursor:
    • Restart Cursor or start a new Cloud Agent session
    • Secrets are automatically injected as environment variables

​
How Secrets Are Used

Setup Workflow (/setup):
  • Automatically detects secrets from Cursor Cloud Agent Secrets
  • Configures CLI tools automatically (~/.sentryclirc, gh auth, etc.)
  • No manual intervention needed
MCP Servers:
  • .cursor/mcp.json references secrets via ${SECRET_NAME} placeholders
  • Cursor resolves placeholders from Cloud Agent Secrets
  • All 5 MCP servers (Vercel, Sentry, GitHub, Intercom, Supabase) use shared secrets
CLI Tools:
  • sentry-cli reads from ~/.sentryclirc (auto-configured from SENTRY_AUTH_TOKEN)
  • gh CLI uses GitHub token (can use GITHUB_PERSONAL_ACCESS_TOKEN or existing gh auth)
  • supabase CLI uses Supabase token (from SUPABASE_ACCESS_TOKEN)

​
When to Use Cloud Agent Secrets vs .env

Use CaseMethodReason
Cloud AgentsCursor SecretsPersists across sessions, works with MCP
Local Development.env fileTraditional workflow, git-tracked for team
CI/CD PipelineGitHub SecretsStandard CI/CD secret management
Production BuildsEAS SecretsExpo-specific secret management

​
Best Practices

DO:
  • ✅ Use Cursor Secrets for Cloud Agent development
  • ✅ Use .env for local development (human developers)
  • ✅ Keep secrets synchronized (same values in both places)
  • ✅ Document which secrets are needed in setup docs
DON’T:
  • ❌ Store production secrets in Cursor Secrets (use EAS Secrets)
  • ❌ Commit sensitive tokens to .env (use .env.local for personal overrides)
  • ❌ Mix Cloud Agent Secrets with local .env unnecessarily
See .cursor/README.md for more details on Cursor configuration.

​
Production Deployment

CRITICAL: Production deployments do NOT use the committed .env file. Production secrets are managed through:
  1. EAS Secrets - For Expo application secrets
  2. Supabase Secrets - For Edge Function secrets (OpenAI API key, etc.)
  3. GitHub Secrets - For CI/CD pipeline
  4. Cursor Cloud Agent Secrets - For Cloud Agent development (not used in production builds)

​
For New Developers

If you need different local credentials:
  1. Create .env.local (git-ignored) with your overrides
  2. Values in .env.local take precedence over .env
  3. See .env.example for all available variables
# Example .env.local
EXPO_PUBLIC_SUPABASE_URL=https://your-local-instance.supabase.co
EXPO_PUBLIC_SUPABASE_KEY=sb_publishable_your-key  # Use publishable key, NOT legacy anon key

​
Best Practices

DO:
  • ✅ Use .env for shared development configuration
  • ✅ Use .env.local for personal overrides
  • ✅ Use Cursor Cloud Agent Secrets for Cloud Agent development
  • ✅ Use EAS Secrets for production deployments
  • ✅ Rotate keys if they’re exposed publicly
  • ✅ Keep Cloud Agent Secrets and .env synchronized
DON’T:
  • ❌ Commit production credentials to .env
  • ❌ Commit service role keys
  • ❌ Share .env outside the team
  • ❌ Use EXPO_PUBLIC_* for sensitive secrets
  • ❌ Store production secrets in Cursor Cloud Agent Secrets

​
Security Model

This approach works because:
  1. Development keys have limited scope - Can only access development/staging environments
  2. RLS policies protect data - Even with the publishable key, users can only access their own data
  3. Production uses different secrets - Deployed apps never use the committed .env
  4. Repository is private - Only authorized team members have access

​
Questions?

See docs/reference/SUPABASE.md for more on our security architecture.