Managing Environment Variables

Environment variables in an Agentuity project live in three places: local .env files for development, the cloud project (and optionally the org) for deployed apps, and the bundle itself for values the build patches in.

agentuity cloud env list
agentuity cloud env set OPENAI_API_KEY "sk_..." --secret
agentuity cloud env pull
agentuity cloud env push

These examples show agentuity ... for readability. If the CLI is project-local, run the same command through your package-manager exec wrapper, for example npx agentuity ..., bunx agentuity ..., pnpm exec agentuity ..., or yarn exec agentuity .... See Local versus global CLI for install and undo commands.

Local Env Files

The CLI looks up AGENTUITY_SDK_KEY in your .env files using the active profile. Default profile is production. The local profile (local) loads a different file order so dev overrides do not bleed into other profiles.

Switch profiles with --profile <name> or AGENTUITY_PROFILE=.... Your framework's runtime reads its own variables. The CLI parses these files only for the SDK key it needs to wire the gateway during agentuity dev.

AI Gateway in Local Dev

Agentuity's AI Gateway provider catalog can change by project and release. Use AI Gateway or agentuity cloud aigateway models --simple for the current provider IDs. Local agentuity dev has one automatic env-injection path today.

For OpenAI, Anthropic, and Groq SDKs, agentuity dev patches the API key and base URL env vars directly into the dev process:

The patch fires only when the API key var is missing or already equals AGENTUITY_SDK_KEY. If you set OPENAI_API_KEY to a real OpenAI key in .env, the CLI leaves it alone and your call goes straight to the provider.

See AI Gateway local development for env injection and Bring your own provider key for BYOK options.

Project SDK Key

AGENTUITY_SDK_KEY is the only Agentuity value the local CLI reads from .env. It is written by agentuity project import when you register the project, refreshed by agentuity cloud env pull, and required by agentuity deploy.

If deploy cannot find the key, it exits before building with a message pointing at agentuity cloud env pull. The platform injects AGENTUITY_SDK_KEY into the deployed runtime automatically. You should not set or override it for a deployed app.

Cloud Project Variables

agentuity cloud env manages variables stored on the cloud project (the default scope) or the organization (--org). The deployed app sees the merged view: project values override org values for the same key.

agentuity cloud env list                       # merged project + org view
agentuity cloud env list --org                 # org-scoped only
agentuity cloud env get OPENAI_API_KEY         # one key
agentuity cloud env set API_TIMEOUT "30"
agentuity cloud env set DATABASE_URL "..." --secret
agentuity cloud env delete LEGACY_FLAG

The set command auto-detects whether a value should be stored as a secret. Pass --secret to force secret storage. Setting --secret on a public-prefixed key (VITE_*, PUBLIC_*, AGENTUITY_PUBLIC_*) is rejected.

Pull and Push

Move values between local .env and the cloud project. By default both directions avoid silent overwrites: pull keeps existing local values, and push shows the diff before it asks to overwrite existing cloud values.

agentuity cloud env pull
agentuity cloud env pull --force
agentuity cloud env push
agentuity cloud env push --force

pull writes cloud values into .env. Without --force, local values win when a key already exists locally. With --force, cloud values overwrite local after a confirmation.

push reads .env, drops reserved Agentuity keys (see below), classifies the rest, and writes to the cloud project. Without --force, the CLI prompts before overwriting an existing cloud value.

A project pull also writes AGENTUITY_SDK_KEY when the cloud project returns one. Use it to recover the key on a fresh checkout.

Reserved Agentuity Keys

agentuity cloud env push and the env sync inside agentuity deploy filter out variables that the platform owns. Filtered keys never make it to the cloud project.

That keeps platform-managed values from being pinned by a stale local .env.

Public Variables and Secrets

The CLI auto-classifies env values when pushing to the cloud project so secrets stay encrypted and public values stay readable.

Always treated as public env vars (never secrets):

Always treated as secrets:

• Keys ending in _SECRET, _KEY, _TOKEN, _PASSWORD, or _PRIVATE
• The exact key DATABASE_URL

Public-prefix classification beats the suffix rule. VITE_PUBLIC_KEY is public, not a secret, even though it ends in _KEY. Pass --secret on cloud env set only when you want to override auto-detection on a non-public key.

Deployed Apps

Deployed apps see three sources of environment values:

1. Platform-injected. AGENTUITY_SDK_KEY and the regional transport URLs (AGENTUITY_TRANSPORT_URL, AGENTUITY_KEYVALUE_URL, AGENTUITY_VECTOR_URL, AGENTUITY_STREAM_URL, AGENTUITY_OTLP_URL, etc.) are set by the platform. You do not set these in cloud project vars.
2. Cloud project vars and secrets. Everything you set with agentuity cloud env set or sync via agentuity deploy. Project values override org values on the same key.
3. Provider SDK configuration. The deployed runtime has AGENTUITY_SDK_KEY and AGENTUITY_TRANSPORT_URL, but provider SDKs still need to be configured for the gateway path you are using. OpenAI, Anthropic, and Groq can use env-driven SDK defaults. AI SDK factory providers, such as Google or xAI, should receive apiKey and baseURL explicitly. Set the provider's own key when you want to bring your own quota and bypass the gateway. For non-LLM service keys (Stripe, Postmark, Datadog, etc.), set them with agentuity cloud env set:

# Provider key the gateway already covers (usually unnecessary)
agentuity cloud env set OPENAI_API_KEY "sk-..." --secret
 
# Service key only your code reads (required)
agentuity cloud env set STRIPE_SECRET_KEY "sk_live_..." --secret
 
# Public value your framework reads at build or render time
agentuity cloud env set PUBLIC_FEATURE_FLAGS '{"newCheckout":true}'

Org-Scoped Variables

Use --org for values shared across every project in an org. Project values still override org values on the same key, so --org is best for defaults.

agentuity cloud env set DATADOG_API_KEY "..." --secret --org
agentuity cloud env list --org
agentuity cloud env pull --org
agentuity cloud env push --org

Best Practices

• Use .env.local for personal overrides. It is loaded ahead of .env.development and .env on the local profile and stays out of the synced bundle.
• Push before deploy if .env drifts. agentuity deploy runs the sync best-effort. A failure during sync does not block the deploy, so verify with agentuity cloud env list after.
• Keep gateway and provider-owned paths explicit. Use the gateway setup documented in AI Gateway when you want Agentuity-routed model calls. Set provider API keys on the cloud project when you want direct provider traffic or when you're calling a non-LLM service.
• Never check .env into git. Keep a committed .env.example for shape and a private .env for values.

Next Steps

• Local Development: the gateway wiring and profile resolution that uses these values.
• Deploy Framework Apps: how agentuity deploy reads .env and ships it to the cloud project.
• Environment Variables on Deploy: the deploy step's exact env-sync semantics.