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). The Cloudflare “Edit Cloudflare Workers” template is not enough — D1 list returns 401 until D1:Edit is added.

Prefer an API token over wrangler login on a remote or headless box — OAuth times out and stale-tab state mismatches are common. Keep the token in CLOUDFLARE_API_TOKEN; never write it into wrangler.jsonc.

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 (the only supported path)
curl -fsSL https://bun.sh/install | bash
# Put ~/.bun/bin on PATH (the installer prints the line for your shell)
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

hoox init copies each worker's wrangler.jsonc.example → wrangler.jsonc (the real files are gitignored). Dashboard OpenNext needs workers/dashboard/wrangler.jsonc. There is no hoox init --self-hosted Cloudflare-free config path — for VPS/air-gap use bun run docker:prod / bun run server.js (or hoox init --self-hosted to print those instructions).

Exchange / Telegram / wallet secrets stay empty until you supply them — that is expected. Mesh keys (INTERNAL_KEY_BINDING, …) are generated by hoox setup.

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.