App environment variables

Reference

Environment variables are how apps see their configuration at runtime. Today each app uses one runtime environment: the same values apply to the deployed app and to local development when org policy allows live data on the laptop.

All env var values live in the customer’s Azure Key Vault. The control-plane database stores metadata only: the name, environment, sensitivity flag, vault reference, actor, and timestamps.

Plain vs sensitive

Kind	Where it lives	Visible in dashboard?
Plain	Key Vault	Yes, when explicitly revealed
Sensitive	Key Vault	Yes, the name only — value never shown

Plain variables are for non-sensitive configuration: feature flags, hostnames, log levels. Sensitive variables are for tokens, signing keys, and other secrets.

A variable is marked sensitive in the dashboard or via greenlight.env.set with sensitive: true. Once marked sensitive, it cannot be un-marked without removing and re-adding the value.

Environment scope

Environment	Vault path	Used by
`shared`	`apps/<app-id>/env/shared/<NAME>`	Deployed pod and local `.env.local` (when policy permits)

There are no separate development and production scopes today. Separate dev, prod, and preview environments with independent values are on the roadmap.

Because local development and deployed runtime share one environment, local writes can affect live app data. Co-owners share that environment; conflicting changes are last-write-wins.

Reserved names

Greenlight injects these automatically. Apps can read them but cannot set them via env.set.

Name	Purpose
`GREENLIGHT_PROXY_URL`	Base URL of the data broker.
`GREENLIGHT_DATA_KEY`	Workload key for proxy calls (`runtime` in the pod; short-lived `local` key from `env.pull`).
`DATABASE_URL`	Present when Postgres is provisioned via `resource.add`.
`STORAGE_SAS_URL`	Present when blob storage is provisioned.
`STORAGE_CONTAINER_NAME`	App-owned blob container name.
`PORT`	Port the platform expects the app to listen on.
`PUBLIC_BASE_URL`	App URL after first deploy.
`DEV_USER_EMAIL`	Local identity simulation fixture.
`DEV_USER_GROUPS`	Local identity simulation fixture.
`GREENLIGHT_AI_BASE_URL`	AI inference gateway (when enabled).
`GREENLIGHT_AI_KEY`	AI gateway key (when enabled).

Setting variables

Dashboard — immediate, audited.
greenlight.env.set — same behavior from the agent; env defaults to shared.

Env var values are never committed to the repository. Infra is not declared in greenlight.yml.

await greenlight.env.set({
  app_id: 'app_k9x2m3p',
  name: 'APPROVAL_SECRET',
  value: '…',
  env: 'shared',
  sensitive: true,
});

Org policy

IT controls local-development risk via orgs.envVarPolicy:

Field	When `false`
`local_live_data_allowed`	`env.pull` returns fixture mode — no live DB, blob, or proxy credentials on the laptop.
`sensitive_local_pull_allowed`	Sensitive names are omitted from `.env.local` (`skipped_sensitive` in the response).
`shared_env_changes_require_approval`	Reserved for future approval workflows.

Local development

greenlight.env.pull returns structured contents for .env.local plus short-lived local credentials. The agent writes the file using its own filesystem tools; the MCP server does not write to the laptop.

Strict orgs set local_live_data_allowed: false and use fixtures locally. Cloud-only development — the app runs in the cluster while the laptop only edits code — is on the roadmap.

Secrets management The platform's secret-handling model.

greenlight.yml Identity and docs metadata in the repo.

MCP tools The greenlight.env.* tool family.