> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**:
  ```bash theme={null}
  curl -fsSL https://bun.sh | bash
  ```
* **Windows (via Powershell)**:
  ```powershell theme={null}
  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](https://dash.cloudflare.com/) (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):
  ```bash theme={null}
  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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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.
</Warning>

***

## 🚀 Bootstrapping Your Trading Workspace

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

```bash theme={null}
# Bootstrap your trading folder
hoox clone my-trading-empire
cd my-trading-empire
```

This command automatically structures your directories as a clean monorepo:

```text theme={null}
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:

```bash theme={null}
# Recommended: chains config + infrastructure in one command
hoox onboard
```

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

```bash theme={null}
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:

<ol>
  <li>
    <strong>Cloudflare Authentication</strong>: Prompts for your Cloudflare API
    token (with <code>Account.D1</code>, <code>Account.KV</code>,{" "}
    <code>Account.Workers</code> permissions) and Account ID.
  </li>

  <li>
    <strong>Microservice Profile Selection</strong>: 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).
  </li>

  <li>
    <strong>Local Credentials Encryption</strong>: Generates safe local{" "}
    <code>.dev.vars</code> matrices and sets up initial KV configuration
    structures.
  </li>

  <li>
    <strong>Infrastructure Provisioning</strong>: Creates D1 databases, KV
    namespaces, and other resources on your Cloudflare account.
  </li>
</ol>

```text theme={null}
┌────────────────────────────────────────────────────────┐
│               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:

```bash theme={null}
# 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.
</Tip>

### 🔗 Next Steps

* [**Configuration Matrix**](configuration) — Map out your 31-key environment variables and 16-key KV registries.
* [**5-Minute Quick Start Guide**](quick-start) — Execute your first simulated edge trade in under 5 minutes.