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:
- Windows (via Powershell):
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):
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:
Once installed, verify that the hoox command is registered globally in your system path:
🛠️ 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:
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.
This command automatically structures your directories as a clean monorepo:
🪄 Running the Onboarding Wizard
With your folder structured, run the one-shot bootstrap wizard:
For fine-grained control, run the two steps separately:
The hoox onboard wizard chains both steps and will guide you through the critical setup phases:
- Cloudflare Authentication: Prompts for your Cloudflare API
token (with
Account.D1, Account.KV,
Account.Workers permissions) and Account ID. - 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).
- Local Credentials Encryption: Generates safe local
.dev.vars matrices and sets up initial KV configuration
structures. - Infrastructure Provisioning: Creates D1 databases, KV
namespaces, and other resources on your Cloudflare account.
🔍 Verifying Local Prerequisites
Verify that all dependencies and Cloudflare edge routes are accessible:
If all diagnostic checks pass, you are ready to proceed with configuration!
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
