Configuration Dictionary
Environment variables, Worker secrets, and CONFIG_KV keys for the HOOX mesh.
This page
This document is the operator dictionary for environment variables, encrypted Worker secrets, and CONFIG_KV runtime keys. Prefer hoox onboard (or hoox init then hoox setup) over hand-editing files. Day-to-day changes: hoox config / hoox secrets.
Worker name is required on hoox secrets set <worker> <name>. The CLI prompts for the value.
1. Environment variables and secrets
Local build/deploy vars live in .env.local (copy from .env.example). Runtime credentials are Cloudflare® Worker secrets.
A. Core platform
| Variable | Required | Type | Default | Description |
|---|---|---|---|---|
CLOUDFLARE_API_TOKEN | Yes | string | — | Cloudflare® API Token with Workers, D1, KV, R2, and Queues Edit. |
CLOUDFLARE_ACCOUNT_ID | Yes | string | — | Your 32-character Cloudflare® account id (your_cloudflare_account_id). |
SUBDOMAIN_PREFIX | Yes | string | — | Subdomain prefix under which public worker gateways deploy. |
HOOX_API_URL | No | string | — | Local API target URL (TUI / operator plane). |
HOOX_API_TOKEN | No | string | — | Bearer for remote TUI (hoox tui --remote --token). |
HOOX_REPO | No | string | — | Force monorepo root. |
HOOX_HOME | No | string | ~/.hoox | Config / data / global clone home. |
B. Mesh keys (generated by hoox setup)
| Variable | Required | Scope | Description |
|---|---|---|---|
INTERNAL_KEY_BINDING | Yes | mesh | Inter-worker X-Internal-Auth-Key. |
WALLET_EXECUTE_KEY_BINDING | DEX path | trade-worker / web3-wallet-worker | Same value as INTERNAL_KEY_BINDING after setup. |
WEBHOOK_API_KEY_BINDING | Yes | hoox gateway | Public webhook passkey. JSON field apiKey is compared against this secret — not a KV key. |
OPERATOR_API_KEY | Operator plane | hoox gateway | Bearer for /v1/* and /wallet/*. |
After rotation: hoox secrets sync --system (alias --required).
C. Exchange API credentials (trade-worker)
Canonical unified pair — venue is chosen by the signal / exchange:<name>:enabled, not by secret name:
| Variable | Required | Description |
|---|---|---|
EXCHANGE_KEY_BINDING | No | Live API key (Binance / Bybit / MEXC). |
EXCHANGE_SECRET_BINDING | No | Live HMAC secret. |
EXCHANGE_TESTNET_KEY_BINDING | No | Preferred when "test": true (Binance / Bybit). |
EXCHANGE_TESTNET_SECRET_BINDING | No | Preferred testnet secret. |
Deprecated aliases still resolve if the unified pair is unset: BINANCE_KEY_BINDING / BINANCE_SECRET_BINDING / BINANCE_TESTNET_*, BYBIT_*, MEXC_*. Prefer EXCHANGE_*.
D. Telegram (telegram-worker)
| Variable | Required | Description |
|---|---|---|
TG_BOT_TOKEN_BINDING | No | BotFather HTTP API token. |
TG_CHAT_ID_BINDING | No | Default numeric chat when alerts omit chatId. |
AUTHORIZED_CHAT_IDS | No | Comma-separated allowlist. Inbound commands fail-closed when unset. |
TELEGRAM_SECRET_TOKEN | No | X-Telegram-Bot-Api-Secret-Token on POST /webhook. |
hoox secrets set telegram-worker TG_BOT_TOKEN_BINDING
hoox secrets set telegram-worker TG_CHAT_ID_BINDING
hoox secrets set telegram-worker AUTHORIZED_CHAT_IDS
E. Multi-provider AI (agent-worker)
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY | No | OpenAI access key. |
ANTHROPIC_API_KEY | No | Anthropic Claude access key. |
GOOGLE_API_KEY | No | Google Gemini access key. |
AZURE_API_KEY / AZURE_ENDPOINT | No | Azure OpenAI (optional fifth provider). |
F. Web3 wallet (web3-wallet-worker)
| Variable | Required | Description |
|---|---|---|
WALLET_MNEMONIC_SECRET | EVM | 12/24-word seed. |
WALLET_PK_SECRET | EVM | Private key (alternative to mnemonic). |
SOLANA_PRIVATE_KEY | Solana | base58 seed; hoox setup generates one if missing. |
JUPITER_API_KEY | Solana DEX | Jupiter portal. Not auto-generated. |
RPC_URL_ARBITRUM / RPC_URL_SOLANA | No | Public RPCs filled by setup if empty. |
DEX spots (uniswap-ethereum, uniswap-arbitrum, jupiter-solana) do not use CEX keys. See DEX spot swaps.
G. Email ingress (email-worker)
email-worker does not poll IMAP. POST /webhook verifies Mailgun HMAC with MAILGUN_API_KEY. POST /email-signal uses the mesh internal key only. Cloudflare® Email Routing uses the worker email handler.
| Variable | Required | Description |
|---|---|---|
MAILGUN_API_KEY | Mailgun path | Signing key for POST /webhook. |
INTERNAL_KEY_BINDING | JSON path | Mesh key for POST /email-signal. |
EMAIL_HOST_BINDING / EMAIL_USER_BINDING / EMAIL_PASS_BINDING | No | Reserved. The worker does not read them. |
hoox secrets set email-worker MAILGUN_API_KEY
2. Dynamic KV manifest settings
These runtime variables exist inside the CONFIG_KV namespace. Seed defaults with hoox config kv apply-manifest (reads each worker’s dashboard.jsonc).
| KV Key | Type | Default | Operational impact |
|---|---|---|---|
trade:kill_switch | boolean | false | Global emergency halt. Gateway rejects /webhook when true. |
global:kill_switch | boolean | false | Gateway-side twin; OR’d with trade:kill_switch. |
trade:max_daily_drawdown_percent | number | 5.0 | Daily loss before agent-worker trips the kill switch. |
trade:default_leverage | number | 10 | Futures leverage when the signal omits leverage. |
trade:max_position_size | number | 1000 | Max notional (USD) per trade. |
webhook:queue_mode | string | queue_failover | queue_failover, queue_everywhere, or queue_disabled. |
webhook:tradingview:ip_check_enabled | boolean | true | Drop payloads whose CF-Connecting-IP is not on the TradingView® list. |
webhook:tradingview:allowed_ips | string | (JSON array) | Extra allowed IPs merged with built-in TradingView® ranges. |
telegram:allowed_chat_ids | string | [] | Gateway notify chatId allowlist (JSON array). |
email:coin_pattern | string | — | Regex to extract assets from a plain-text email body. |
email:action_pattern | string | — | Regex to resolve actions in a plain-text email body. |
email:quantity_multiplier | number | 1 | Multiplies quantity parsed from a plain-text email body. |
exchange:binance:enabled | string | unset = on | "false" skips the venue. Same pattern for bybit, mexc, uniswap-ethereum, uniswap-arbitrum, jupiter-solana. |
The webhook passkey is WEBHOOK_API_KEY_BINDING, not a KV key.
Opt-in tenant isolation is off by default. D1 rows carry tenant_id ('' when unscoped). Do not enable it unless you intend to attribute traffic by tenant.
Tip
Sync, inspect, or reset this manifest: hoox config kv apply-manifest,
hoox config kv get <key>, hoox config kv set <key> <value>.
🔗 Next Steps
- 5-Minute Quick Start Guide — Deploy workers and fire a webhook.
- API Endpoint Reference — REST schemas, parameters, and error models.