Environment Variables

Environment variables let you pass configuration and secrets to your functions without hardcoding them.

Local Development

Automatic .env Loading

ccp dev automatically loads a .env file from your project root:

# .env
API_KEY=sk-abc123
DATABASE_URL=postgres://localhost:5432/mydb

ccp dev
# Automatically loaded .env file...

Custom Env File

Point to a different file with --env:

ccp dev --env .env.staging

Accessing in Code

Use process.env to read variables:

export function handler(request: Request): Response {
  const apiKey = process.env.API_KEY;

  if (!apiKey) {
    return new Response("API_KEY not set", { status: 500 });
  }

  return Response.json({ configured: true });
}

Production

Production environment variables are stored per function and injected into your deployment at runtime. Set them by PATCH-ing the function via the serverless API:

curl -X PATCH https://api.clusterbase.dev/api/v1/serverless/functions/<FUNCTION_ID> \
  -H "Authorization: Bearer $(ccp auth token)" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_variables": {
      "API_KEY": "sk-abc123",
      "DATABASE_URL": "postgres://..."
    }
  }'

The function ID is in your .cluster/config.json. A UI for managing these in the console is coming soon.

How env updates merge

When you deploy (or PATCH the function), Cluster merges the env you send into the function's existing variables: keys you include are added or updated, and keys you don't include are left untouched. So server-side managed values — like the DATABASE_URL and DATABASE_TOKEN that ccp db create injects — survive a code-only redeploy even when they aren't in your local .env.

Because updates merge, removing a key from your .env (or from the PATCH body) no longer deletes it from the function — the old value stays. Value changes still take effect; only key removal is a no-op. There is no function-env delete API yet, so to drop a variable entirely, destroy and recreate the function.

Updates redeploy the function

Updating env republishes the function's active production deployment so the new values take effect on the running deployment immediately — expect a brief window during which the function is momentarily unavailable while the deployment is rebuilt. If the env write itself fails, the request returns 500 with {"error": "env_update_failed"} instead of a misleading 200 — a failed update is surfaced, never silently dropped.

.env in .gitignore

The ccp init command adds .env to .gitignore by default. Never commit secrets to your repository.