[Local Development]

How to run, hot-reload, and test Hoox workers locally using native wrangler runtimes or Docker Compose containers.

This page

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. Prefer hoox dev / hx dev over calling Wrangler by hand.

🚀 Starting the Local Workspace

Run from the monorepo (or any directory after the CLI has remembered that path — see Installation).

To spin up all enabled workers simultaneously:

hoox dev start
# alias:
hx dev start

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

Option A: Native Runtime (Recommended for speed)

  • Runs each worker in a separate background thread using wrangler dev (the official Cloudflare® local server; invoked by the Hoox CLI).
  • Speed: Instant startup and sub-millisecond hot-reloading.
  • Requirements: Local node/bun installation.

Option B: Docker Runtime (Recommended for isolation)

  • 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 (9 services — all background workers, no UI)
docker compose --profile workers up

# Profile 2: Dashboard + transitive worker deps (5 services: hoox,
#           d1-worker, trade-worker, agent-worker, dashboard).
#           trade-worker is pulled in because agent-worker depends on it
#           for executing risk-approved trades.
docker compose --profile dashboard up

# Profile 3: Full Stack (all workers including pyne-worker + dashboard)
docker compose --profile full up

Only hoox (8787) and dashboard (8794) are published to the host. The other workers are reachable only via service bindings on the hoox-net bridge network — the same topology as production Cloudflare® Workers Service Bindings.

📍 Local Port Mapping & Endpoint Access

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

| Worker | Local Port | Endpoint URL | Purpose | || :-------------------- | :--------: | :---------------------- | :-------------------------------- | || hoox | 8787 | http://localhost:8787 | Public Gateway & Webhook Receiver | || trade-worker | 8789 | http://localhost:8789 | Trade Execution Engine | || telegram-worker | 8791 | http://localhost:8791 | Telegram Bot Alerts & Commands | || d1-worker | 8792 | http://localhost:8792 | SQLite Database Operations | || web3-wallet | 8793 | http://localhost:8793 | On-Chain DeFi Execution | || dashboard | 8794 | http://localhost:8794 | Next.js Dashboard Cockpit | || agent-worker | 8795 | http://localhost:8795 | AI Risk Manager & Cron Engine | || email-worker | 8796 | http://localhost:8796 | Email Signal Parsing | || report-worker | 8797 | http://localhost:8797 | PDF Portfolio Report Generator | || analytics-worker | 8798 | http://localhost:8798 | Analytics & Reporting Engine | || pyne-worker | 8799 | http://localhost:8799 | Pine Script™ edge evaluate (PYNE) |

# Probe / evaluate via CLI (when pyne-worker is enabled)
hoox pyne health
hoox pyne run path/to/script.pine

🛠️ 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] (~4,600+ unit tests · ~9k 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