Secrets & env variables
Overview
Secrets and environment variables let your published app access API keys, database credentials, and other sensitive configuration without hardcoding them in your codebase.
Emergent provides a built-in secrets manager for every project. Store your secrets there, not in files committed to your repository.
Secrets work in preview and published environments
The secrets manager is designed for preview and published applications. During the build phase in chat, agents use the Universal LLM Key and test credentials. Your secrets become available in both preview and published environments.
Where to store secrets
Open the secrets manager
In your workspace, navigate to the Secrets panel (Click Preview, then Manage, you can see the Secrets panel there).
Add or edit keys
To add a new key, ask the agent to add it to your
.envSave
Click Save to store the secret. It is now encrypted and associated with your project.
Note
The
.envAccessing secrets in your app
Your application reads secrets as environment variables at runtime:
The platform injects these variables into your app's container when it starts.
Re-publishing after adding or changing secrets
Saving alone does not update your live app
A newly saved or updated secret will not take effect in a running published app until you re-publish.
Why? Your published container was built with the secrets available at published app time. Changing a secret in the manager updates the stored value but does not restart or reconfigure running instances.
How to apply updated secrets
- Save your new or modified secret in the secrets manager.
- Trigger a re-publish (re-publish) from the workspace or via chat (e.g. "re-publish the app").
- The new container starts with the updated environment variables.
Tip
If your app isn't picking up a secret, confirm you've republished since the last save. Check the published app timestamp in your workspace.
Common pitfalls
Solution: Re-publish the app. The running container uses the secrets from the last published app, not the latest saved values.
Yes. The secrets manager masks values by default, but a per-line reveal toggle and click-to-copy are available. Note that values are visible to anyone with published app access. To correct a key's value, edit it directly in the Secrets UI. Note that keys cannot be deleted from the UI, if you need to stop using a key, update its value and re-publish.
No. Secrets live only in the Emergent platform. If you use Save to GitHub, your repository will not contain the secret values. You must configure secrets separately in any external CI/CD or hosting environment.
Best practices
- Use descriptive names:
is clearer thanSTRIPE_SECRET_KEY
.KEY_1 - Rotate credentials regularly: Update secrets in the manager, then re-publish.
- One secret per variable: Avoid concatenating multiple keys into a single environment variable.
- Test after publish: Confirm your app can read the secret by checking logs or a health endpoint.
