Hoox Docs

💻 Local Development

Hoox provides a comprehensive local development workspace designed to match your production Cloudflare edge environment. You can run all microservices with hot-reload enabled, monitor them visually via the Terminal UI (TUI), and execute the full test suite using native Bun tools or isolated Docker containers.

🚀 Starting the Local Workspace

To spin up all enabled workers simultaneously:

hoox dev start

On execution, the CLI automatically detects your environment and prompts you to select a runtime:

  • Runs each worker in a separate background thread using wrangler dev (the official Cloudflare local server).
  • Speed: Instant startup and sub-millisecond hot-reloading.
  • Requirements: Local node/bun installation.
  • Launches a multi-container stack using Docker Compose.
  • Isolation: All environment variables, SQLite databases, and queue handlers run in isolated Linux containers, ensuring zero conflicts with local packages.
  • Requirements: Docker Desktop installed.

Tip: The CLI saves your runtime preference inside wrangler.jsonc.dev.runtime. Subsequent launches skip the prompt. You can override your preference at any time using flags:

# Force native execution
hoox dev start --runtime native

# Force Docker Compose execution
hoox dev start --runtime docker

🐳 Docker Compose Profiles

If you choose the Docker runtime, Hoox manages orchestration using three specialized Docker Compose profiles defined in docker-compose.yml:

# Profile 1: Workers Only (No frontend dashboard)
docker compose --profile workers up

# Profile 2: Dashboard Only (Next.js server only)
docker compose --profile dashboard up

# Profile 3: Full Stack (All workers + Next.js dashboard)
docker compose --profile full up

📍 Local Port Mapping & Endpoint Access

During local development, all enabled workers are assigned dedicated local ports, simulating service boundaries locally:

WorkerLocal PortEndpoint URLPurpose
hoox8787http://localhost:8787Public Gateway & Webhook Receiver
trade-worker8789http://localhost:8789Trade Execution Engine
telegram-worker8791http://localhost:8791Telegram Bot Alerts & Commands
d1-worker8792http://localhost:8792SQLite Database Operations
web3-wallet8793http://localhost:8793On-Chain DeFi Execution
dashboard8794http://localhost:8794Next.js Dashboard Cockpit
agent-worker8795http://localhost:8795AI Risk Manager & Cron Engine

🛠️ Operating Individual Services

If you only want to work on a single microservice rather than running the full stack, you can spin up individual modules:

# Dev run a single worker (gateway)
hoox dev worker hoox

# Dev run trade-worker with hot-reloading
hoox dev worker trade-worker

# Dev run dashboard separately (Next.js dev server with Turbopack)
hoox dev dashboard

🧪 Running the Verification CI Pipeline

Hoox features a rigorous local test pipeline to ensure that all TypeScript types, formatting, and unit tests pass perfectly before pushing to git:

# Run the complete CI verification pipeline locally
hoox test

The pipeline executes four verification steps in a strict dependency sequence:

  1. Lint Check (bun run lint): Validates ESLint styling rules across the monorepo.
  2. Type Check (bun run typecheck): Compiles code via tsc --noEmit to verify type safety.
  3. Unit Tests (bun test): Fires all unit and integration test assertions using Bun’s native test runner.
  4. Build Check (bun run build): Compiles all workspaces (cli, tui, shared, dashboard) to verify production packaging.
🔍 Running local CI Pipeline...
[STARTED] lint check... [PASSED]
[STARTED] TypeScript typecheck... [PASSED]
[STARTED] bun test runner... [PASSED] (1,574 assertions)
[STARTED] workspace builds... [PASSED]
✔ Local CI Pipeline Succeeded!

Note: Local unit tests utilize Bun’s native test runner for instantaneous execution. You can target specific workspace folders or run files individually: bun test workers/trade-worker/src/index.test.ts.

🔗 Next Steps