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

# Environment variables

> Environment variables for the Hyperterse server, CLI, and `{{ env.* }}` substitution in config.

## Configuration substitution

You can use `{{ env.VAR_NAME }}` placeholders in any string value across your configuration files. Hyperterse resolves these when the server starts.

### Supported locations

| Config location              | Example                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| Adapter `connection_string`  | `"postgresql://{{ env.DB_USER }}:{{ env.DB_PASS }}@{{ env.DB_HOST }}:5432/{{ env.DB_NAME }}"` |
| Adapter `options` values     | `sslmode: "{{ env.DB_SSL_MODE }}"`                                                            |
| Tool `statement`             | `"SELECT * FROM {{ env.TABLE_PREFIX }}_users WHERE id = {{ inputs.user_id }}"`                |
| Tool `auth.policy` values    | `value: "{{ env.API_KEY }}"`                                                                  |
| Agent `model.options` values | `api_key: "{{ env.OPENAI_API_KEY }}"`                                                         |
| Root config `server.port`    | `port: "{{ env.PORT }}"`                                                                      |

### Resolution behavior

* Placeholders resolve at the point of use: connector initialization, statement execution, auth check, or agent model initialization.
* Missing variables cause a hard failure with an error identifying the unresolved variable.
* Placeholders are not recursive — a variable whose value contains `{{ env.OTHER }}` is not expanded further.
* The `.env` file in the working directory is loaded before command execution.

## Runtime variables

<ParamField body="PORT" type="integer" default="8080">
  Fallback port when not set via CLI flag or config.

  Precedence: `--port` flag → `server.port` config → `PORT` env → `8080`
</ParamField>

<ParamField body="HYPERTERSE_API_KEY" type="string">
  Fallback API key for the `api_key` auth plugin when `auth.policy.value` is not set on a tool.

  Precedence: `auth.policy.value` config → `HYPERTERSE_API_KEY` env
</ParamField>

<ParamField body="HYPERTERSE_LOG_TAGS" type="string">
  Comma-separated log tag filter. Limits which tags appear in log output.

  Precedence: `--log-tags` flag → `HYPERTERSE_LOG_TAGS` env
</ParamField>

## Agent model provider variables

These variables are used when resolving model configuration for declarative agents
(`app/agents/*/config.terse`).

| Variable                | Used by                                                                  | Purpose                                                          | Precedence                                                                            |
| ----------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `OPENAI_API_KEY`        | `openai_compatible`, `openai`                                            | Fallback API key for OpenAI-compatible model calls.              | `model.options.api_key` → `OPENAI_API_KEY`                                            |
| `GOOGLE_API_KEY`        | `gemini`, `google_ai_studio`, `vertex`, `vertex_ai` (optional on Vertex) | Fallback API key for Gemini/Vertex model calls.                  | `model.options.api_key` → `GOOGLE_API_KEY`                                            |
| `GOOGLE_CLOUD_PROJECT`  | `vertex`, `vertex_ai`                                                    | Fallback Vertex project id.                                      | `model.options.project` → `GOOGLE_CLOUD_PROJECT`                                      |
| `GOOGLE_CLOUD_LOCATION` | `vertex`, `vertex_ai`                                                    | Primary Vertex location fallback.                                | `model.options.location` → `GOOGLE_CLOUD_LOCATION` → `GOOGLE_CLOUD_REGION`            |
| `GOOGLE_CLOUD_REGION`   | `vertex`, `vertex_ai`                                                    | Secondary Vertex location fallback when location is still empty. | Used only after `model.options.location` and `GOOGLE_CLOUD_LOCATION` are absent/empty |

### Agent model options and env substitution

* `model.options` string values support `{{ env.VAR_NAME }}` substitution when the agent model starts.
* Missing variables referenced in `model.options` placeholders fail startup with a clear error.
* This is in addition to provider-level fallback variables in the table above.

## `.env` file

The CLI loads `.env` from the current working directory when present. Standard `KEY=VALUE` format. Blank lines and `#`-prefixed lines are ignored.

```bash .env theme={null}
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_KEY=sk-secret-key-value
PORT=9090
```

<Note>
  Shell-set environment variables take precedence over `.env` values. The file
  provides defaults, not overrides.
</Note>

## Security guidance

<Warning>
  Do not commit `.env` to version control. Add it to `.gitignore`.
</Warning>

* Use `{{ env.VAR }}` for all credentials. Connection strings, API keys, and tokens must reference environment variables — never hardcode secrets in `.terse` files.
* Rotation requires restart. Environment variables resolve at startup. For zero-downtime rotation, use a secrets manager that updates the environment and signals a restart.
* Set production log level. Debug logs may include substituted statement text. Use log level `2` (warn) or `3` (info) in production.