Skip to main content
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:
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.
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:

​
🐳 Docker Compose Profiles

If you choose the Docker runtime, Hoox manages orchestration using three specialized Docker Compose profiles defined in docker-compose.yml:
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 |

​
🛠️ 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:

​
🧪 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:
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.
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

Last modified on June 29, 2026