Hoox Docs

🏁 Installation Guide

This guide walks you through preparing your environment, installing the @jango-blockchained/hoox-cli tool, cloning the microservices monorepo recursively, and validating your local system prerequisites.

📋 System Prerequisites

Before installing the Hoox command-line workspace, ensure your system meets the following standard software requirements:

1. 🧅 Bun JavaScript Runtime (Version ≥ 1.2)

Hoox uses Bun as its primary package manager, script runner, and native testing engine. Bun’s blazing-fast startup time and zero-config TypeScript compilation are critical to our local developer feedback loops.

  • macOS / Linux: 
    curl -fsSL https://bun.sh | bash
  • Windows (via Powershell): 
    powershell -c "irm https://bun.sh/install.ps1 | iex"

2. ⚡ Cloudflare Account & Wrangler CLI

All Hoox workers are compiled to run on Cloudflare’s Edge V8 isolates. You will need a free Cloudflare account:

  • Account: Register a free account (the free tier provides 100,000 requests/day, D1 database, KV storage, Queues, R2, and vector search—costing $0/month).
  • Cloudflare CLI: Ensure you have wrangler installed globally (though Hoox manages local wrangler operations automatically, having it indexed globally is recommended): 
    bun add -g wrangler

3. 🐳 Docker & Docker Compose (Optional)

If you prefer running the entire Hoox local trading workspace in fully isolated container environments with one command, ensure you have Docker Desktop installed and running:

  • Check status: docker compose version

📦 Option A: Install via Package Manager (Recommended)

To install the global management CLI tool directly from npm/bun registry to manage new workspaces:

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

Once installed, verify that the hoox command is registered globally in your system path:

hoox --version

🛠️ Option B: Build & Run from Source

If you plan to contribute to the Hoox CLI packages or prefer working directly inside a monolithic source clone:

# 1. Clone the parent repository with git submodules recursively
git clone --recursive https://github.com/jango-blockchained/hoox-setup.git hoox-trading
cd hoox-trading

# 2. Install all monorepo workspace dependencies via Bun
bun install

# 3. Verify the locally linked CLI runs from root
bun run build:cli
./packages/cli/bin/hoox.js --help

Warning: You MUST use git clone --recursive or run git submodule update --init --recursive after cloning. If you omit submodules, the worker directories under workers/ will be empty and deployments will fail.

🚀 Bootstrapping Your Trading Workspace

Now, initialize your new algorithmic trading workspace. This compiles directories, configures workspace settings, and sets up Git tracking.

# Bootstrap your trading folder
hoox clone my-trading-empire
cd my-trading-empire

This command automatically structures your directories as a clean monorepo:

my-trading-empire/
├── packages/
│   ├── cli/       # Workspace CLI management binaries
│   ├── tui/       # 9-view Terminal UI monitoring cockpit
│   └── shared/    # Reusable routers, rate-limiters, & errors
├── workers/
│   ├── hoox/      # Gateway, rate-limiter, DO idempotency lock
│   ├── trade-worker/    # Multi-exchange execution engine
│   └── ...        # Other analytical and web3 wallet workers
└── package.json

🪄 Running the Interactive Setup Wizard

With your folder structured, execute the interactive bootstrap wizard:

hoox init

The CLI wizard will guide you through 4 critical setup phases:

  1. Toolchain Validation: Probes your machine for bun, git, wrangler, and docker configurations.
  2. Cloudflare Authentication: Prompts for your Cloudflare API token (with Account.D1, Account.KV, Account.Workers permissions) and Account ID.
  3. Microservice Profile Selection: Lets you declaratively toggle which edge workers to enable (e.g., enable Gateway and Trade Worker, disable Web3 Wallet if you only trade centralized exchanges).
  4. Local Credentials Encryption: Generates safe local .dev.vars matrices and sets up initial KV configuration structures.
┌────────────────────────────────────────────────────────┐
│               hoox Setup & Initialization              │
├────────────────────────────────────────────────────────┤
│  ✔ bun (v1.2.1) found                                  │
│  ✔ wrangler (v3.50.0) 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         │
└────────────────────────────────────────────────────────┘

🔍 Verifying Local Prerequisites

Verify that all dependencies and Cloudflare edge routes are accessible:

# Perform detailed pre-flight diagnostic checklist
hoox check prerequisites

If all diagnostic checks pass, you are ready to proceed with configuration!

Tip: Got installation issues? Run hoox repair check to automatically analyze common path resolution issues, missing environment variables, or node-gyp build failures, and recover your local workspace seamlessly.

🔗 Next Steps