> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.
</Note>

***

## 🏗️ 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:

```bash theme={null}
hoox onboard
```

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

```bash theme={null}
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:

```jsonc theme={null}
{
  "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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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!
</Tip>

### 🔗 Next Steps

* **[DevOps Setup & Operations Manual](setup_and_operations)** — Dive into complete operations, variable matrices, and troubleshooting.
* **[Terminal UI Cockpit](tui)** — Run, hot-reload, and monitor your local workers via TUI.