Platform Configuration

Hoox uses a dual-layer configuration topology: a declarative build-time environment layer (managed via local files and Cloudflare® Secrets) and an instantaneous runtime configuration layer (managed via Cloudflare® KV key-value databases). This ensures maximum agility: deploy secure code once, and adjust trading parameters or flip kill switches in real-time without redeploying code. Prefer hoox config / hoox secrets over manual Wrangler edits for day-to-day ops.

1. Declarative Environment Variables (.env.local)

For local operations, build-time variables, and workspace linking, Hoox loads a .env.local file at your project root.

Copy the secure template during initialization:

cp .env.example .env.local

The Hoox environment is split into 5 core logical sections. Below is the comprehensive dictionary of key configuration parameters:

A. ⚡ Cloudflare® Core Infrastructure

B. 💱 Exchange API Keys (Securely Redacted)

These credentials must be injected as encrypted Cloudflare® Worker secrets. The CLI automates this (hoox secrets set <worker> <name> — worker name is required; the command prompts for the value).

One unified pair covers Binance / Bybit / MEXC. The venue comes from the signal exchange field (and exchange:<venue>:enabled KV flags), not from the secret name:

hoox secrets set trade-worker EXCHANGE_KEY_BINDING
hoox secrets set trade-worker EXCHANGE_SECRET_BINDING
# Optional testnet pair (Binance / Bybit when the payload has "test": true)
hoox secrets set trade-worker EXCHANGE_TESTNET_KEY_BINDING
hoox secrets set trade-worker EXCHANGE_TESTNET_SECRET_BINDING

Per-venue names (BINANCE_KEY_BINDING, BYBIT_KEY_BINDING, MEXC_KEY_BINDING, and matching *_SECRET_BINDING / *_TESTNET_*) are deprecated aliases. They still resolve if the unified pair is unset.

DEX spots (uniswap-ethereum, uniswap-arbitrum, jupiter-solana) do not use CEX API keys. hoox setup writes WALLET_EXECUTE_KEY_BINDING and a Solana seed if missing. You still set JUPITER_API_KEY for Solana and supply WALLET_PK_SECRET / WALLET_MNEMONIC_SECRET for EVM. See DEX spot swaps.

Webhook passkey is not a KV key. hoox setup writes WEBHOOK_API_KEY_BINDING on the hoox gateway; the JSON field apiKey is compared against that secret.

Mesh keys generated by setup (do not hand-edit): INTERNAL_KEY_BINDING, WALLET_EXECUTE_KEY_BINDING, and related inter-worker keys. After rotation: hoox secrets sync --system.

C. 💬 Telegram Bot Alerts

D. 🧠 Multi-Provider AI Credentials

Used to power autonomous risk assessments, Telegram conversation loops, and time-series summaries in agent-worker.

• OPENAI_API_KEY — Access key for OpenAI GPT models (agent-worker).
• ANTHROPIC_API_KEY — Access key for Anthropic Claude models (agent-worker).
• GOOGLE_API_KEY — Access key for Google Gemini models (agent-worker).
• AZURE_API_KEY / AZURE_ENDPOINT — Optional Azure OpenAI provider.

2. Managing Environment & Secrets via CLI

To prevent plain-text exposure and ensure proper edge variable binding, never manually paste sensitive keys into wrangler.jsonc files. Instead, utilize the high-integrity hoox config env command groups:

# 1. Start the guided terminal config wizard
hoox config env init

# 2. View active workspace configuration (sensitive credentials automatically redacted)
hoox config env show

# 3. Validate env file structure against required platform variables
hoox config env validate

# 4. Generate local decrypted .dev.vars files for every enabled worker
hoox config env generate-dev-vars

3. Worker Configurations (wrangler.jsonc)

Each worker in the monorepo has a standard wrangler.jsonc file at its directory root. These configurations declare:

1. Service Bindings: Connects gateway routes (hoox) to internal compute units (trade-worker, d1-worker) directly via microsecond V8 isolates—no TCP/TLS overhead, no public routes.
2. Resource Bindings: Declares which D1 databases, R2 storage buckets, and KV configurations are linked.
3. Execution Mode: Toggles latency-saving features like Smart Placement ("placement": { "mode": "smart" }).

You can inspect, check, or change worker toggle status directly:

# Print complete microservice enabled/disabled status tree
hoox config show

# Declaratively enable/disable specific workers in the manifest
hoox config set workers.web3-wallet-worker.enabled false

4. Runtime KV Configuration (Sub-millisecond Settings)

One of Hoox's core architectural features is instant runtime parameter updates. By using Cloudflare® KV, certain settings can be modified globally in sub-milliseconds and take effect on the very next signal execution—without rebuilding or redeploying any worker.

Runtime keys live in the CONFIG_KV namespace (hoox config kv apply-manifest seeds defaults from each worker’s dashboard.jsonc). Below are the most critical parameters:

Managing KV Settings via CLI

# Get the current value of the Global Kill Switch
hoox config kv get trade:kill_switch

# Manually trigger a global trading halt
hoox config kv set trade:kill_switch true

# Restore trading by flipping the switch back
hoox config kv set trade:kill_switch false

# Declaratively apply default manifest variables to Cloudflare® KV
hoox config kv apply-manifest

🔗 Next Steps

• 5-Minute Quick Start Guide — Launch local worker runners and execute a simulated webhook trade signal.
• Deploying to Production — Deploy and bind all workers in the correct dependency sequence.