Env Manager Guide

Every SABLE runtime's environment-variable requirements are tracked as data — env-manifests/*.json files — not as an .env.example with placeholder values, and never with real values. This page is how to read, validate, and extend that system.

The manifest files

Manifest	Covers
sable-web.json	Vercel web app (sable-agents-demo/web)
sable-supabase-edge.json	Supabase Edge Functions
sable-supabase-tools.json	Supabase CLI/tooling environment
sable-trigger.json	Trigger.dev tasks
sable-managed-agents.json	The Claude Managed Agents runtime (RUNBOOK.md)
sable-github-actions.json	CI/CD workflow secrets
sable-docs-site.json	This Docusaurus site (optional DocSearch values only)
datasync-*.json, lead-to-cash-*.json	The neighboring DataSync and Lead-to-Cash apps' own manifests, tracked in the same format for portfolio-wide drift checking

Each manifest carries a client, repo, and app identity block, a platforms map (each target — e.g. vercel-production, supabase-local — with its type and environment), and a vars array. Each var entry names the variable, whether it's required, whether it's sensitive, which platforms it applies to, its sourceOfTruth and provider, a dataTier (public/internal/secret), a syncMode, and a why explaining what breaks without it. Some entries also carry aliases (an equivalent name recognized on another platform) or a sharedCredentialId (linking multiple manifests to the same underlying credential).

Values are never present — only names and metadata. This is what makes the manifests safe to commit and read in an AI-assisted session.

Validating manifests

cd sable-agents-demo
npm run env:validate

This loads every env-manifests/*.json file and validates its structure and required fields. Warnings print but don't fail the run; structural errors fail it with a non-zero exit and a count of manifests plus total variable requirements checked.

Checking for drift

npm run env:drift          # report only
npm run env:drift:strict   # fail the run on any drift
npm run env:drift:portfolio # drift check scoped to the portfolio/lead-to-cash apps

Drift checking compares what a manifest says a platform needs against a set of known, deliberately-ignored ambient variables (IGNORED_ENV_VARS — CI-provided values like GITHUB_ACTIONS, NODE_ENV, PATH, pinned tool-version constants like GITLEAKS_VERSION that are workflow constants rather than deployment configuration, and legacy demo-only ids like MEMORY_STORE_ID/DEPLOYMENT_ID). Anything outside that ignore list that shows up without a matching manifest entry, or a manifest entry with nothing backing it, is drift.

env:check: what CI actually runs

npm run env:check   # env:validate && env:drift:strict

This is exactly the env-manifests job in .github/workflows/sable-ci.yml — running it locally before opening a PR catches a manifest problem before CI does.

Bundling manifests

npm run env:bundle

Bundles the manifest set for distribution/reference — useful when handing a consolidated environment-variable inventory to someone who needs it without walking every file individually.

Adding a new variable

1. Add the entry to the correct manifest's vars array with name, required, sensitive, platforms, sourceOfTruth, provider, dataTier, syncMode, and a why that would make sense to someone who has never seen the code.
2. If the variable is shared across manifests (for example, the Supabase URL appears in both sable-web.json and sable-supabase-edge.json), give it the same sharedCredentialId in both places rather than letting the two entries drift independently.
3. Run npm run env:check before committing.
4. Set the actual value on the real platform (Vercel dashboard, Supabase secrets, Trigger.dev environment) yourself — the manifest tracks the requirement, it never provisions the value.

Where the code lives

• sable-agents-demo/env-manifests/*.json — the manifests themselves.
• sable-agents-demo/scripts/env-manager/schema.mjs — the manifest schema, loader, and drift index builder.
• sable-agents-demo/scripts/env-manager/validate-env-manifests.mjs, check-env-manifest-drift.mjs, bundle-manifests.mjs.
• sable-agents-demo/docs-site/docs/reference/environment-variables.md — the per-runtime variable list this guide's tooling keeps honest.