Environment Variables
Store API keys and settings for your app, choose which environments get each one, and use them in local development.
Configure variables per app in Settings → Configuration → Environment Variables. Each variable targets one or more environments: Sandbox, Preview and Production. See Environments for how they differ.
Use built-ins first
Several services need no key of your own:
| Need | Use |
|---|---|
| Google Maps embeds (place, search, view, directions) | NEXT_PUBLIC_GOOGLE_MAPS_EMBED_API_KEY, provided by the platform. It covers the Maps Embed API only, not paid APIs such as Places, Geocoding or Routes. |
| Transactional email | |
| OCR and document extraction | Starlens |
| Taking payments | Payments |
| Google Calendar, LINE, Slack | Connected Services |
| Your app's data | Data Stores |
Calling a third-party API
- Add the provider's key as a secret variable, for example
WEATHER_API_KEY. - Call the API from server code (a route handler or server action), never from the browser.
- Return only the data the browser needs.
// apps/web/src/app/api/weather/route.ts
export async function GET(req: Request) {
const city = new URL(req.url).searchParams.get("city");
const res = await fetch(`https://api.example.com/weather?q=${encodeURIComponent(city ?? "")}`, {
headers: { Authorization: `Bearer ${process.env.WEATHER_API_KEY}` },
});
return Response.json(await res.json());
}Secret and non-secret variables
| Secret | Non-secret | |
|---|---|---|
| Available | Runtime only, server code | Build time and runtime |
| Reaches browser | Never | Only if the name starts with NEXT_PUBLIC_ |
| Storage and UI | Encrypted; shown as Secret (hidden for security) | Value shown, with a show/hide toggle |
| Use for | API keys, tokens, passwords, connection strings | Public endpoints, feature toggles |
NEXT_PUBLIC_values are embedded in the built app. Never put a secret in one. Stardeck does not add the prefix for you.- Stardeck also writes a
VITE_copy of each non-secret variable for legacy Vite apps. Next.js apps ignore it.
Add, edit or delete
- Click Add Environment Variable.
- Enter a Key: uppercase letters, digits and underscores, not starting with a digit.
- Enter the Value. Turn on Secret Variable for anything sensitive.
- Select the Deployment Targets and click Add Variable.
To edit, click Edit, change the fields and click Update Variable. Leave a secret's value empty to keep it. To delete, click the trash icon and confirm.
From your coding agent
Over MCP, your agent can list variables and create, edit or delete
non-secret ones (list_app_env_vars, create_app_env_var, update_app_env_var,
delete_app_env_var). Each change shows you a preview first. It can't read or set a secret's value:
for a secret it gives you a link to this tab, and you enter the value yourself.
To run the app on your machine, the agent writes the sandbox's variables, secrets included, to a
git-ignored .env.local. See Run Your App Locally.
When changes take effect
- Sandbox: saving or deleting a variable restarts the dev server.
- Secrets: synced to live deployments without a redeploy. If the sync fails, the change applies on the next deploy.
- Non-secret variables: apply on the next deploy.
Reserved names
You can't create these (the check ignores case):
- Prefixes:
VITE_,OIDC_ - Platform secrets:
DATABASE_URL,DEPLOYMENT_SECRET,PKCE_ENCRYPTION_SECRET,STARDECK_AI_API_KEY,STARDECK_GATEWAY_SECRET - Other:
DATABASE_NAME,APP_DATABASE_NAME,DEPLOYMENT_ID,CLOUDFLARE_INCLUDE_PROCESS_ENV,DISABLE_AUTH,SENTRY_RELEASE,NEXT_PUBLIC_SENTRY_RELEASE,PLATFORM_BASE_URL,NEXT_PUBLIC_PLATFORM_BASE_URL
DATABASE_URL is the legacy per-app database of older apps. New apps keep their data in
Data Stores. To reach an external database, use another name such as
EXTERNAL_DATABASE_URL and mark it secret.
For the full exposure rules, see Constraints.