Configuration
Everything lives in hlid.toml (or hlid.yaml) in hlid's working directory. Environment variables override file values. The full field list is in the config reference.
Minimal config
All models go to one local backend:
bind_addr = "0.0.0.0:8080"
request_timeout_secs = 120
observe_buffer_size = 1000
[[backends]]
model_pattern = "*"
url = "http://localhost:8081"
dialect = "openai-chat"Multiple backends
Route model families to different places. Patterns are checked in order — first match wins — so put the catch-all last:
bind_addr = "0.0.0.0:8080"
# Local llama.cpp for llama models
[[backends]]
model_pattern = "llama-*"
url = "http://localhost:8081"
dialect = "openai-chat"
# Anthropic cloud for claude models
[[backends]]
model_pattern = "claude-*"
url = "https://api.anthropic.com"
dialect = "anthropic-messages"
credential_ref = "ANTHROPIC_API_KEY"
# OpenAI cloud for GPT models
[[backends]]
model_pattern = "gpt-*"
url = "https://api.openai.com"
dialect = "openai-chat"
credential_ref = "OPENAI_API_KEY"
# Catch-all fallback
[[backends]]
model_pattern = "*"
url = "http://localhost:8081"
dialect = "openai-chat"| Pattern | Example match | Where it goes |
|---|---|---|
llama-* | llama-3-70b | Local llama.cpp |
claude-* | claude-sonnet-4-20250514 | Anthropic API |
gpt-* | gpt-4o | OpenAI API |
* | anything else | Local fallback |
Credentials
credential_ref names an environment variable that holds the backend's API key — the key itself never appears in the config file:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...hlid injects the key with the header the backend expects (Authorization: Bearer for OpenAI-family, x-api-key for Anthropic). Your agents never see backend keys.
Auth
Lock down hlid itself with an API key. When auth_key is set, every request must include it:
bind_addr = "0.0.0.0:8080"
auth_key = "sk-hlid-my-secret-key"Callers pass it either way:
curl -H "Authorization: Bearer sk-hlid-my-secret-key" ...
# or
curl -H "x-api-key: sk-hlid-my-secret-key" ...Localhost bypass
Auth is skipped automatically when hlid is bound to a loopback address with no key configured — no friction for local dev. Bind to anything else and you should set auth_key. See Deployment.
Environment overrides
export HLID_BIND_ADDR="127.0.0.1:9090"
export HLID_AUTH_KEY="sk-override-key"These take precedence over whatever is in hlid.toml.