Hoox — Edge-Native Algorithmic Trading on the Cloudflare Edge

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

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.

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

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.

​🏗️ Onboarding Wizard (hoox onboard)

​Phase 1: Cloudflare Authentication

​Phase 2: Microservice Profile Selection

​Phase 3: Integration Secrets

​Phase 4: Configuration Write

​Phase 5: Infrastructure Provisioning

​Phase 6: Verification

​🔎 Configuration Files Spec

​A. wrangler.jsonc (Central Settings)

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

​🔒 Secret Bindings Architecture

​Local Mocking (.dev.vars)

​Production Secret Bindings

​🔗 Next Steps

🏗️ Onboarding Wizard (`hoox onboard`)

Phase 1: Cloudflare Authentication

Phase 2: Microservice Profile Selection

Phase 3: Integration Secrets

Phase 4: Configuration Write

Phase 5: Infrastructure Provisioning

Phase 6: Verification

🔎 Configuration Files Spec

A. wrangler.jsonc (Central Settings)

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

🔒 Secret Bindings Architecture

Local Mocking (`.dev.vars`)

Production Secret Bindings

🔗 Next Steps