Cloudflare® Workers Setup Flow

This document details the step-by-step installation, bootstrapping, and validation workflows executed by the Hoox CLI during project initialization.

🏗️ Onboarding Wizard (hoox onboard)

The recommended entry point is hoox onboard (alias: hx onboard). It chains init (configuration) and setup (infrastructure) into a single command. Running hoox / hx with no arguments on an uninitialized workspace auto-launches onboard (or onboard --resume when .wizard-state.json exists).

Setup gates (@hoox-sh/hoox-cli 0.16.0): onboard will not run setup if init was cancelled or never wrote wrangler.jsonc. Setup also aborts when worker trees are still missing after the submodule clone attempt, and requires Cloudflare® auth (wrangler login or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID).

Install the CLI with Bun only (npm install -g aborts on workspace:*). Run the one-shot wizard from the monorepo root — the CLI remembers that path so later hx calls work from any directory:

bun add -g @hoox-sh/hoox-cli
cd /path/to/hoox   # first discovery writes ~/.hoox/config/monorepo.json
hoox onboard
# later, from any directory:
hx doctor          # shows Remembered + Runtime root
hx check health

For fine-grained control, run the two steps separately:

hoox init    # 1. Write wrangler.jsonc, collect integration secrets
hoox setup   # 2. Generate keys (including WALLET_EXECUTE_KEY_BINDING), apply D1 schema, push secrets, deploy dashboard

Self-hosted (no Cloudflare®) is a separate path: hoox init --self-hosted prints Docker / server.js instructions and exits. It does not write a Cloudflare®-free wrangler.jsonc.

The setup wizard guides you through these critical onboarding phases:

Phase 1: Cloudflare® Authentication

Prompts for your Cloudflare® API token (with Account.D1, Account.KV, Account.Workers permissions) and Account ID.

Phase 2: Worker Preset Selection

Chooses a preset rather than free-form per-worker toggles in the wizard:

Pass --preset minimal|standard|full for non-interactive runs (hoox onboard / hoox init). You can still edit wrangler.jsonc afterward to refine enabled workers.

Phase 3: Integration Secrets

Collects any integration secrets required by the selected preset (canonical EXCHANGE_KEY_BINDING / EXCHANGE_SECRET_BINDING, Telegram bot tokens, AI provider keys, optional wallet / Jupiter keys) and writes them to local .dev.vars files. hoox setup then generates the mesh key WALLET_EXECUTE_KEY_BINDING for spot DEX.

Phase 4: Configuration Write

Consolidates all chosen parameters and writes your central wrangler.jsonc file, mapping out variables and bindings for every worker.

Phase 5: Infrastructure Provisioning

Generates internal auth keys, creates D1 databases, applies the schema, and pushes secrets to Cloudflare®. Builds and deploys the Next.js dashboard (via hoox setup / onboard chain).

Phase 6: Verification (suggested next step)

Does not auto-run validation. When setup finishes successfully, the CLI suggests hoox check setup as the next step so you can verify config, infra, secrets, and database health.

🔎 Configuration Files Spec

The Hoox platform uses a dual configuration file architecture to track workspace states:

A. wrangler.jsonc (Central Settings)

This file represents the declarative single source of truth for your monorepo's active workers:

{
  "global": {
    "cloudflare_account_id": "<YOUR_CLOUDFLARE_ACCOUNT_ID>",
    "subdomain_prefix": "hoox",
  },
  "workers": {
    "d1-worker": {
      "enabled": true,
      "path": "workers/d1-worker",
      "vars": { "database_name": "trade-data-db" },
    },
    "trade-worker": {
      "enabled": true,
      "path": "workers/trade-worker",
      "secrets": [
        "EXCHANGE_KEY_BINDING",
        "EXCHANGE_SECRET_BINDING",
        "INTERNAL_KEY_BINDING",
        "WALLET_EXECUTE_KEY_BINDING",
      ],
    },
  },
  "dev": {
    "runtime": "native", // "native" | "docker" — saved by `hoox dev start`
  },
}

B. .wizard-state.json (Onboarding State)

During the interactive setup, the CLI caches your current step and intermediate inputs inside .wizard-state.json at your project root (constant WIZARD_STATE_PATH in @hoox-sh/hoox-shared).

• State Recovery: If your terminal session is disconnected or wrangler login prompts timeout, you can run hoox onboard (or hoox init --resume) again. The CLI will detect the state file and seamlessly resume your onboarding from the last incomplete step. Running hoox with no args and no wrangler.jsonc also resumes via onboard --resume when this file exists.
• Auto-Cleanup: When the wizard completes successfully (or when the workspace is already initialized), the state file is cleaned up so the project root stays tidy.

🔒 Secret Bindings Architecture

Hoox utilizes Cloudflare® hardware-secured Secret Store to bind environment credentials to V8 isolates without exposing them in git history.

Local Mocking (.dev.vars)

During local development, wrangler dev looks for a local, gitignored file called .dev.vars inside each worker's directory to simulate secrets:

# workers/trade-worker/.dev.vars
EXCHANGE_KEY_BINDING=mock_exchange_development_key
EXCHANGE_SECRET_BINDING=mock_exchange_development_secret
WALLET_EXECUTE_KEY_BINDING=mock_wallet_execute_key

Production Secret Bindings

When deploying to production, wrangler binds these variables using direct encrypted environments in your worker's wrangler configuration:

{
  "secrets_store": {
    "bindings": [
      {
        "binding": "EXCHANGE_KEY_BINDING",
        "store_id": "<YOUR_SECRET_STORE_ID>",
        "secret_name": "EXCHANGE_KEY_BINDING"
      }
    ]
  }
}

This guarantees that secrets are never logged, never cached in plain text on disk, and are only accessible inside your worker's sandboxed execution isolate memory.

🔗 Next Steps

• DevOps Setup & Operations Manual — Dive into complete operations, variable matrices, and troubleshooting.
• Terminal UI Cockpit — Run, hot-reload, and monitor your local workers via TUI.
• CLI features — Monorepo remember path, secrets modes, Linear Rail banner.
• MCP server — Drive the same CLI from an MCP client.