[Installation Guide]

Prepare your local machine, install the hoox CLI tool, bootstrap workspaces, and verify system prerequisites.

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 Onboarding Wizard

With your folder structured, run the one-shot bootstrap wizard:

# Recommended: chains config + infrastructure in one command
hoox onboard

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 hoox onboard wizard chains both steps and will guide you through the critical setup phases:

  1. Cloudflare Authentication: Prompts for your Cloudflare API token (with Account.D1, Account.KV, Account.Workers permissions) and Account ID.

  2. 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).

  3. Local Credentials Encryption: Generates safe local .dev.vars matrices and sets up initial KV configuration structures.

  4. Infrastructure Provisioning: Creates D1 databases, KV namespaces, and other resources on your Cloudflare account.

┌────────────────────────────────────────────────────────┐
│               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