[Installation Guide]

This guide walks you through installing the @hoox-sh/hoox-cli tool, cloning the microservices monorepo, running hoox onboard, and validating local prerequisites.

---

📋 System Prerequisites

1. 🧅 Bun JavaScript Runtime (Version ≥ 1.2)

Hoox uses Bun as its package manager, script runner, and test engine. The CLI is a Bun bundle and will not run under Node.

• macOS / Linux:

  curl -fsSL https://bun.sh/install | bash
  

• Windows (via PowerShell):

  powershell -c "irm https://bun.sh/install.ps1 | iex"
  

2. ⚡ Cloudflare® Account

All Hoox workers run on Cloudflare® Workers (V8 isolates). A free account is enough for typical retail volume:

• Account: Register free (Workers, D1, KV, Queues, R2, Vectorize — free-tier limits apply).
• API token: Created during hoox onboard (or pass --token / --account non-interactively). Permissions: Workers Scripts Edit, D1 Edit, KV Edit, R2 Edit, Queues Edit, AI Read.

The CLI ships with Wrangler as a dependency — you do not need a separate global wrangler install for normal operator workflows. Prefer hoox / hx commands over raw Wrangler for provision, secrets, and deploy.

3. 🐳 Docker & Docker Compose (Optional)

For isolated local mesh / self-host profiles:

• Check status: docker compose version

---

📦 Install the CLI (Recommended)

# Install globally using Bun
bun add -g @hoox-sh/hoox-cli

Verify the binary (alias hx is identical):

hoox --version
# e.g. 0.13.x
hx --version

---

🛠️ Clone the Workspace

Workers are git submodules. Clone recursively:

git clone --recursive https://github.com/hoox-sh/hoox.git
cd hoox

If you already cloned without submodules:

git submodule update --init --recursive
# or: hoox clone --all

From source (contributors) — install workspace deps and build the local CLI if needed:

bun install
bun run build:cli   # optional; monorepo scripts can invoke packages/cli
./packages/cli/bin/hoox.js --help

---

🪄 Bootstrap with hoox onboard

hoox onboard is the recommended entry point. It writes wrangler.jsonc, collects secrets, generates keys, applies the D1 schema, pushes secrets, and deploys the dashboard (init + setup in one shot).

# From the monorepo (first run discovers & remembers the path)
hoox onboard

# Non-interactive
hoox onboard --token cfut_xxx --account xxx --preset full

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

hoox init    # Step 1: write wrangler.jsonc, collect integration secrets
hoox setup   # Step 2: generate keys, apply D1 schema, push secrets, deploy dashboard

The wizard walks through:

1. Cloudflare® authentication — API token and Account ID.

2. Microservice profile — enable/disable edge workers (gateway, trade, agent, pyne, web3, …).

3. Local credentials — generates .dev.vars (mode 0600) and initial KV structures.

4. Infrastructure provisioning — D1, KV, and related resources.

5. Setup gates — aborts if worker trees are still empty after submodule clone, or if init did not produce a valid wrangler.jsonc.

┌────────────────────────────────────────────────────────┐
│               hoox Setup & Initialization              │
├────────────────────────────────────────────────────────┤
│  ✔ bun found                                           │
│  ✔ git found                                           │
│  ✔ Cloudflare® credentials verified                    │
│                                                        │
│  Enable central Gateway Worker? [Y/n]: y               │
│  Enable Multi-Exchange trade-worker? [Y/n]: y          │
│  Enable agent-worker AI Risk Manager? [Y/n]: y         │
└────────────────────────────────────────────────────────┘

---

📍 Run from any directory (monorepo remember)

After you have used the CLI once inside the monorepo, the path is saved to ~/.hoox/config/monorepo.json. Later you can call hoox / hx from any folder (e.g. ~/Videos) and the CLI will chdir into the monorepo automatically.

# First time: inside the clone (remembers the path)
cd ~/Git/hoox
hoox doctor

# Later: any working directory
cd ~/Videos
hx check setup
hx doctor          # Source: remembered · Runtime root: /…/hoox

Resolution order: HOOX_REPO env → walk up from cwd → remembered monorepo file → ~/.hoox/repo (managed global clone via hoox doctor --fix-runtime).

---

🔍 Verifying Local Prerequisites

# Pre-flight tools on the machine
hoox check prerequisites

# Full bootstrap validation (config, infra, secrets presence, db)
hoox check setup

# Live worker /health probes
hoox check health

hoox check setup only fails secrets when declared names are missing on Cloudflare® (with hoox secrets sync hints). Healthy local .dev.vars and complete remote name lists stay quiet.

---

🔗 Next Steps

• Configuration Matrix — Environment variables and KV registries.
• 5-Minute Quick Start Guide — Deploy and fire a simulated trade webhook.