> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# The .env file

> How pgw reads PGW_ variables from the .env file in the folder where you run it, and which source wins when a setting comes from several.

Keep the master key, the bootstrap token, and the tenant API key in a `.env` file, out of the configuration file and your shell history. Every `pgw` command reads the `.env` file in the folder where you run it, except `pgw init`, `pgw version`, and `pgw` with an unknown command. The file is optional.

`pgw init` writes a `.env` file with mode `600` that holds a new `PGW_MASTER_KEY` and `PGW_BOOTSTRAP_TOKEN`. `pgw bootstrap` adds the new tenant's `PGW_API_KEY` to the file when the file exists. Keep the file out of version control.

## Format

pgw reads only lines whose name starts with `PGW_` and skips every other line unparsed, so you can share the file with another tool.

```bash theme={null}
# Secrets for pgw
PGW_MASTER_KEY=<base64 master key>
export PGW_BOOTSTRAP_TOKEN='<token>'
```

| Rule | Behavior |
| - | - |
| Line form | `NAME=value`, optionally after `export `. Blank lines and lines that start with `#` are skipped. |
| Quotes | A value is bare or inside one pair of single or double quotes. pgw keeps quoted characters as they are and processes no escapes. Text after a closing quote is an error. |
| Bare values | pgw trims surrounding spaces. A `#` is part of the value, so `PGW_API_KEY=abc # note` holds `abc # note`. |
| Repeated names | The last line wins. |
| Parse errors | A `PGW_` line that doesn't parse stops the command with `pgw: .env: line N: want NAME=value`. The message never shows the line. |
| Size | At most 1 MiB. |

## Which source wins

pgw takes each setting from the first source that has it:

1. A non-empty variable in the shell's environment. An empty variable counts as unset.
2. The `.env` file.
3. The configuration file, for settings that have a YAML key.
4. The default.

When a shell variable replaces a different value in `.env`, pgw writes `pgw: warning: your shell overrides <NAME> from .env` to stderr, once per name, without the value.

`PGW_MASTER_KEY` and `PGW_MASTER_KEY_FILE` are one setting. When the shell sets either, pgw ignores both in `.env`.

## Protect the file

Except on Windows, `pgw serve` refuses to start when the `.env` file holds the `PGW_MASTER_KEY` that pgw uses, and the file's group or other users can access the file. The check also applies when the shell sets the same key. It doesn't apply when the shell sets `PGW_MASTER_KEY_FILE` or a different key. Restrict the mode:

```bash theme={null}
chmod 600 .env
```

When `pgw bootstrap` saves the API key to a `.env` file that others can read, it first makes the file readable by you only, and prints a warning.

## Next steps

> [card] [Settings reference](https://docs.pgw.sipmicro.services/reference/settings.md)
>
> Look up the environment variable, default, and range of each setting.

> [card] [Security](https://docs.pgw.sipmicro.services/security.md)
>
> Protect the master key, and limit who can reach the admin API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.