Hyperterse — Agentic server framework.

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

PORT

integer

default:"8080"

Fallback port when not set via CLI flag or config.Precedence: --port flag → server.port config → PORT env → 8080

HYPERTERSE_API_KEY

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

HYPERTERSE_LOG_TAGS

string

Comma-separated log tag filter. Limits which tags appear in log output.Precedence: --log-tags flag → HYPERTERSE_LOG_TAGS env

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.

.env

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_KEY=sk-secret-key-value
PORT=9090

Shell-set environment variables take precedence over .env values. The file provides defaults, not overrides.

Security guidance

Do not commit .env to version control. Add it to .gitignore.

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.

​Configuration substitution

​Supported locations

​Resolution behavior

​Runtime variables

​Agent model provider variables

​Agent model options and env substitution

​.env file

​Security guidance

Configuration substitution

Supported locations

Resolution behavior

Runtime variables

Agent model provider variables

Agent model options and env substitution

`.env` file

Security guidance