[Cloudflare® Workers Setup Flow]

Detailed system onboarding, toolchain validation steps, wrangler.jsonc schemas, and Secret Store binding architectures.

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

Note

The Hoox CLI enforces strict type validation for all configuration files via the Config and WorkerConfig TypeScript interfaces defined in packages/cli/src/core/types.ts. Avoid using as any or type bypasses when extending wrangler parameters to prevent build-time CLI crashes.

Onboarding Wizard (hoox onboard)

v0.8.0 update: The recommended entry point is now hoox onboard, which chains init (configuration) and setup (infrastructure) into a single command. Running hoox with no arguments on an uninitialized workspace will auto-launch onboard.

To start the system bootstrap, run the one-shot wizard from the monorepo root:

hoox onboard

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

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

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: Microservice Profile Selection

Lets you selectively enable or disable specific workers from the workers/ directory based on your trading intent (e.g., cross-margin futures execution vs. Web3 DeFi wallet swaps). Disabling unnecessary workers saves deployment bandwidth and keeps resource bindings clean.

Phase 3: Integration Secrets

Collects any integration secrets required by the selected workers (exchange API keys, Telegram bot tokens, AI provider keys) and writes them to local .dev.vars files.

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.

Phase 6: Verification

Runs hoox check setup to verify that all components are operational.

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": "debc6545e63bea36be059cbc82d80ec8",
    "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": ["BYBIT_API_KEY", "BYBIT_API_SECRET", "TELEGRAM_BOT_TOKEN"],
    },
  },
}

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

During the interactive setup, the CLI caches your current step and intermediate inputs inside .install-wizard-state.json at your project root.

  • 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.
  • Auto-Cleanup: Upon final completion of Phase 7, the state file is automatically purged to keep your root directory clean.

Secret Bindings Architecture

Hoox utilizes Cloudflare's 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
BYBIT_API_KEY=mock_bybit_development_key
BYBIT_API_SECRET=mock_bybit_development_secret

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": "BYBIT_API_KEY_BINDING",
        "store_id": "48433bc559a943f09d9d6c622e188fd5",
        "secret_name": "BYBIT_API_KEY"
      }
    ]
  }
}

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.

Tip

Made a configuration mistake or changed your subdomain? You can re-run hoox check-setup at any time to execute high-integrity type validation and ensure all bindings and configurations match production examples perfectly!

Next Steps