# Environment Variables

> Configure environment variables for your Tarout applications

# Environment Variables

Environment variables let you configure your application without changing code. Use them for API keys, database connection strings, feature flags, and more.

## How variables are stored

Variables belong to one application. Each variable has:

- **Key** - letters, numbers, and underscores, starting with a letter or underscore (for example `DATABASE_URL`).
- **Value** - up to 64 KB, encrypted at rest.
- **Description** - optional note about what the variable is for.
- **Secret** - on by default. Secret values are masked in lists and exports unless you explicitly reveal them.

There are no per-environment values (such as separate production and staging sets). To reuse the same variables in another app, copy them with `tarout env copy`.

## Setting Variables

### Dashboard

1. Open your application and go to the **Variables** tab.
2. Click **Add variable**, enter the key and value, and save. You can also click **Import .env** to paste the contents of a `.env` file (matching keys are overwritten, the rest are kept), or switch to the **.env file** view to edit every variable as one document.
3. When the dashboard shows that a restart is needed, click **Restart now** to apply the change to the running app.

### CLI

Every `env` command takes the application (ID or name) first:

```bash
# Set one variable (secret by default; add --no-secret for plain config)
tarout env set my-app DATABASE_URL="postgres://user:pass@host:5432/db"

# Read a value from stdin instead of the command line (useful for multi-line secrets)
tarout env set my-app PRIVATE_KEY < key.pem

# List variables (values masked unless you add --reveal)
tarout env list my-app

# Upload a .env file (merges by default; --replace removes keys not in the file)
tarout env push my-app --input .env

# Download variables to a .env file (secrets masked unless you add --reveal)
tarout env pull my-app --output .env

# Remove a variable
tarout env unset my-app OLD_KEY

# Copy variables from one app to another
tarout env copy source-app target-app
```

Other commands: `env get`, `env reveal`, `env audit`, `env bulk-set`, and `env bulk-delete`. Run `tarout env --help` for details.

### When changes take effect

| How you change it | When the running app sees it |
|---|---|
| `tarout env set` (single create or update, also through MCP and the API) | On the next deploy. The value is saved, but the running container is not updated and a restart alone does not pick it up. Run `tarout deploy` to apply it. |
| `tarout env push` | On the next restart or deploy. Add `--restart` to restart the app and apply it right away. |
| `tarout env unset` | Immediately: removing a variable always restarts the app. |
| Dashboard add, edit, or import | After you click **Restart now** (or on the next deploy). |

## Build-time variables

Most variables are **runtime only**: they are injected when the container starts and are not visible while your app builds. This keeps secrets out of build logs and image layers.

Only these variables are passed to the build:

- Keys that start with a public prefix: `NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, `PUBLIC_`, `NUXT_PUBLIC_`, `GATSBY_`, or `EXPO_PUBLIC_`.
- Builder settings that start with `RAILPACK_` (for example `RAILPACK_PHP_EXTENSIONS`), plus `NIXPACKS_NODE_VERSION`.

Public-prefixed values usually end up in the browser bundle, so never put a secret in one. If a build step needs a secret (for example a private package token) and your app builds from a Dockerfile, use the **Build Arguments** section on the **Variables** tab instead.

## Special Variables

| Variable | Description |
|----------|-------------|
| `PORT` | Injected by Tarout with the port your application must listen on. Tarout owns this value: a `PORT` you set yourself is replaced at deploy time. |

## Best Practices

- Never commit secrets to Git - use environment variables instead.
- Keep secret values out of `NEXT_PUBLIC_`, `VITE_`, and other public-prefixed keys.
- Prefix related variables (e.g., `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`).
- Use the `.env.example` file in your repo to document required variables.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md