Skip to main content

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.

​
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 locationExample
Adapter connection_string"postgresql://{{ env.DB_USER }}:{{ env.DB_PASS }}@{{ env.DB_HOST }}:5432/{{ env.DB_NAME }}"
Adapter options valuessslmode: "{{ env.DB_SSL_MODE }}"
Tool statement"SELECT * FROM {{ env.TABLE_PREFIX }}_users WHERE id = {{ inputs.user_id }}"
Tool auth.policy valuesvalue: "{{ env.API_KEY }}"
Agent model.options valuesapi_key: "{{ env.OPENAI_API_KEY }}"
Root config server.portport: "{{ 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).
VariableUsed byPurposePrecedence
OPENAI_API_KEYopenai_compatible, openaiFallback API key for OpenAI-compatible model calls.model.options.api_key → OPENAI_API_KEY
GOOGLE_API_KEYgemini, 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_PROJECTvertex, vertex_aiFallback Vertex project id.model.options.project → GOOGLE_CLOUD_PROJECT
GOOGLE_CLOUD_LOCATIONvertex, vertex_aiPrimary Vertex location fallback.model.options.location → GOOGLE_CLOUD_LOCATION → GOOGLE_CLOUD_REGION
GOOGLE_CLOUD_REGIONvertex, vertex_aiSecondary 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.