How to add environment variables during deployment | Ample
The short version
Pass deployment values with repeated --env arguments or import a dotenv-style file with --env-file. Ample encrypts deployment environment variables and excludes common env files from the source package. Declare secret keys in ample.toml without literal values, then supply the values when you deploy.
Before you start
This guide is for apps that need API keys, database URLs, runtime settings, or public build-time configuration.
How to do it
- 1
Separate secrets from public values
Server-side tokens, passwords, and private keys are secrets. Framework prefixes such as VITE_, NEXT_PUBLIC_, PUBLIC_, and NUXT_PUBLIC_ are browser-visible and must contain only public values.
- 2
Declare the shape in ample.toml
A secret declaration records that the service needs the value without committing the value itself.
SMTP_KEY = { secret = true }
- 3
Pass a value directly
Repeat --env for multiple values. A bare key can prompt for its value where interactive input is available.
ample deploy --env SMTP_KEY --env NODE_ENV=production
- 4
Or import an env file
Use an existing dotenv-style file as deployment input. The file is read for values and is not packaged as application source.
ample deploy --env-file .env.production
- 5
Redeploy build-time changes
Public framework variables may be inlined during the build. Create a new deployment after changing them so the client bundle is rebuilt.
What this supports
Good fit
- Repeated encrypted --env values
- Dotenv-style --env-file imports
- Secret declarations in ample.toml
- Framework-specific public build variables
Know the limits
- Literal secret values are rejected in ample.toml
- Public-prefixed variables are visible to browser users
- A missing secret cannot be inferred safely from source code
Common failure modes
The app reports a missing variable
Confirm the key name, service, and deploy command, then inspect runtime logs.
A frontend value did not change
Use the framework's public prefix and redeploy so the production bundle is rebuilt.
A secret file is blocked from packaging
Keep the file out of the artifact and import its values with --env-file instead.