Copy .env.sample to .env. None of these are required to boot — set the
ones whose feature you use. A missing key surfaces when that feature runs: the
built-in tools raise their own clear error at call time, and the model provider
raises a key-named error when the agent is built.
| Env var | Purpose |
|---|
OPENAI_API_KEY | Default openai:gpt-5.4 model. Skip it if you pass your own model. |
LINKUP_API_KEY | The web_search example tool (examples/tools/websearch.py). |
TAVILY_API_KEY | The fetch example tool (examples/tools/fetch.py). |
LANGFUSE_SECRET_KEY / LANGFUSE_PUBLIC_KEY | Tracing (optional). |
LANGFUSE_HOST | Optional Langfuse host override. |
SDK defaults
| Env var | Purpose |
|---|
HEXGATE_DEFAULT_MODEL | Model used when you don’t pass model= explicitly (default openai:gpt-5.4). |
HEXGATE_DEFAULT_SEARCH_ENGINE | Engine for the web_search example tool (default linkup). |
| Env var | Purpose |
|---|
HEXGATE_API_KEY | fty_live_… / fty_test_… token. Wakes up the platform path; without it, adapters and load_agent fall back to local / registered resolution. |
HEXGATE_API_URL | Platform endpoint. Defaults to Hexgate Cloud (https://app.hexgate.ai). Set to http://localhost:8000 only when self-hosting locally — the key must be minted by whichever platform this points at. |
HEXGATE_LOCAL_MODE | Truthy value forces local audit and shorts the platform auto-bind path, even when HEXGATE_API_KEY is set. hexgate chat sets this automatically. |
HEXGATE_BIND_AGENTS | Truthy value opts a code-built agent into the platform path at construction time (requires HEXGATE_API_KEY — the platform path is otherwise opt-in). |
fty_live_… key only verifies against the
platform instance that minted it.
HEXGATE_API_KEY was renamed from HEXGATE_KEY, which is no longer read. If
you’re upgrading, rename it in your .env — an old HEXGATE_KEY is silently
ignored and the platform path never wakes up.
Policy-bundle enforcement
All optional — see WASM bundles and
local override.
| Env var | Purpose |
|---|
HEXGATE_LOCAL_POLICY | Path to a bundle directory or a policy.yaml; routes enforcement through the WASM engine and hot-reloads on save. |
HEXGATE_BUNDLE_PUBKEY_PATH | base64url Ed25519 public key used to verify a bundle’s signature. |
HEXGATE_BUNDLE_SIGN_KEY_PATH | base64url Ed25519 private key used to sign locally-compiled yaml sources (so bundle.is_signed is True). |
HEXGATE_BUNDLE_REQUIRE_SIGNATURE | true to refuse unsigned or unverifiable bundles (default: warn only). |
HEXGATE_OPA_BIN | Override the opa binary location (default: search PATH). |
platform/api/.env. See
control plane and email.
| Env var | Purpose |
|---|
DATABASE_URL | Postgres DSN. Unset → local SQLite. Bare postgres:// URLs are normalized to the asyncpg driver. |
RESEND_API_KEY | Resend API key — enables ResendEmailSender when paired with HEXGATE_EMAIL_FROM. |
HEXGATE_EMAIL_FROM | From-address on a verified Resend domain, e.g. "Hexgate <noreply@yourdomain.com>". |
HEXGATE_DASHBOARD_URL | Link host embedded inside verification / reset emails. |
