How to add environment variables during deployment · Ample Computer
How to add environment variables during deployment
Pass encrypted environment variables or an env file to Ample without packaging secret files into the release.
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.
Who this is for
This guide is for apps that need API keys, database URLs, runtime settings, or public build-time configuration.
How to do it
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.
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 }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=productionOr 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.productionRedeploy 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
- 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.