# Environment variables

> Add and edit encrypted variables, and wire a database into your service.

Source: https://gheima.ma/docs/environment-variables

Environment variables configure your service without code changes. Every value is encrypted at rest and masked in the UI. Admins can reveal values, and every reveal is logged. A variable marked secret can never be revealed again.

### Add or edit a variable

1. **Open the Environment tab** — On the service page, go to the Environment tab.
2. **Enter a key and value** — Type the variable name (uppercased automatically, for example NODE_ENV) and its value, then click "Add". Reusing a key overwrites it.
3. **Redeploy to apply** — Changes take effect on the next deploy. Click "Deploy" when you’re ready.

> Note: The list shows a masked preview, not the plaintext. To read values, an admin clicks "Reveal values", and each reveal is recorded in the audit log. A variable marked "Secret" is write-only: nobody can reveal it, through the dashboard, the API, or the CLI.

### Connect a database

Open a database’s Connect tab to reveal a ready-to-paste block of connection variables, for example DATABASE_URL for Postgres and MySQL, MONGODB_URI for MongoDB, or REDIS_URL for Redis. Copy them into your service’s environment.

### Limits & rules

- Keys are uppercased automatically: node_env becomes NODE_ENV.
- Values can be up to 32,768 characters.
- Changes take effect on the next deploy.
- Through the API and CLI, listing variables returns the keys with masked values. An admin can read values with gheima env reveal, which never returns a secret variable.

### Env groups (shared config)

Create a reusable env group under Env groups, add variables (or import a .env file), and attach it to several services. On deploy, the group’s variables are injected into every attached service. A service’s own variables override the group’s. Use a group for config and secrets that several services share.

### Build-time variables

Variables are normally injected when the container starts, so nothing secret ends up inside your image. Some builds need values earlier: a Next.js app that pre-renders pages from its database, or NEXT_PUBLIC_ and VITE_ values inlined into the browser bundle. Mark those keys with the hammer toggle in the Environment tab, or add them under "Build-time variables".

- Only the keys you mark reach the build. Everything else stays runtime-only.
- Values are mounted as build secrets for the step that reads them, never written into an image layer.
- Keys resolve like they do at runtime, so a linked database’s DATABASE_URL works by listing that one key.
- Whatever your build writes out of a value does persist. An inlined NEXT_PUBLIC_ value lives in the bundle because your framework put it there.

> Result: Your service reads configuration and database credentials from the environment, kept encrypted and out of your codebase.

---

All docs: https://gheima.ma/docs.md