---
title: "How to add environment variables during deployment"
description: "Pass encrypted environment variables or an env file to Ample without packaging secret files into the release."
canonical_url: "https://ample.computer/guides/environment-variables-deployment"
last_updated: "2026-07-30"
author: "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

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.

   ```sh
   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.

   ```sh
   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.

   ```sh
   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

- 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.

## Related guides

- [How to deploy a Vite application](https://ample.computer/guides/deploy-vite-app)
- [How to deploy a Next.js application](https://ample.computer/guides/deploy-nextjs-app)
- [What to do when an app works locally but not in production](https://ample.computer/guides/works-locally-not-production)

## Machine-readable resources

- [llms.txt](https://ample.computer/llms.txt) | [AGENTS.md](https://ample.computer/AGENTS.md) | [sitemap.md](https://ample.computer/sitemap.md) | [OpenAPI](https://ample.computer/openapi.json)