Local Development Setup

Hoox provides a comprehensive local development workspace designed to emulate your production Cloudflare® edge environment. Developers can choose between running microservices natively on local Wrangler V8 isolates or inside completely isolated, containerized Docker stacks, with real-time log tailing and TUI diagnostics.

⚡ 1. Dev Runtime Selection: Native vs. Docker

The hoox dev start command orchestrates the boot sequence for all enabled workers and supports two execution runtimes:

The Guided Startup Flow

When you run hoox dev start:

1. Wrangler Version Verification: Probes your global/local Wrangler package. If Wrangler is outdated, it prompts an advisory upgrade warning. The warning shows the current vs minimum version and offers a one-line update command.

2. Docker Environment Probing: Checks if the Docker daemon is active and docker-compose.yml is present in the workspace.

3. Runtime Preference Lock: If both runtimes are available, the CLI prompts you to select your preference. This choice is written to your wrangler.jsonc file under the dev runtime block, bypassing future prompts.

# Override the saved runtime preference on the fly
hoox dev start --runtime native
hoox dev start --runtime docker
# Preference is written to wrangler.jsonc → dev.runtime

🐳 2. Docker Compose Orchestration & Profiles

For full stack containerized development, Hoox divides operations into three Docker Compose profiles in your root docker-compose.yml:

# Profile 1: workers — 10 services, no dashboard UI
#   hoox, trade-worker, telegram-worker, d1-worker, web3-wallet-worker,
#   agent-worker, email-worker, report-worker, analytics-worker, pyne-worker
docker compose --profile workers up

# Profile 2: Dashboard + its transitive worker dependencies (5 services:
#           hoox, d1-worker, trade-worker, agent-worker, dashboard).
#           trade-worker is pulled in because agent-worker depends on it.
docker compose --profile dashboard up

# Profile 3: full — 11 services (the 10 workers + dashboard)
docker compose --profile full up

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

📍 3. Local Port Mapping Registry

hoox dev start assigns the ports below. agent-worker, email-worker, report-worker, and analytics-worker are not pinned and take the next free port from 8800 upward, in enable order. Docker Compose publishes only gateway 8787 and dashboard 8794. Inside the compose network, report-worker, analytics-worker, and pyne-worker also pass --port 8797, 8798, and 8799; those ports are not published to the host.

🛡️ 4. Local Environmental Mocking (.dev.vars)

Because production secrets are locked inside Cloudflare®'s secured key vaults, Wrangler dev uses local .dev.vars files located inside each worker's directory to mock API keys and credentials:

# 1. Copy the secure template
cp workers/hoox-worker/.dev.vars.example workers/hoox-worker/.dev.vars

# 2. Inject local mock keys for testing
echo 'INTERNAL_KEY_BINDING="local_test_key"' >> workers/hoox-worker/.dev.vars

🏃 5. Shell Helpers: Running Commands Across All Workers

The scripts/helpers.sh file provides a wx() function that runs any CLI command in every worker directory — useful for bulk operations like regenerating types, running typecheck, or installing dependencies.

Installation

# One-time install (adds to ~/.zshrc or ~/.bashrc)
bash scripts/install.sh

# Or source it manually in your current session
source scripts/helpers.sh

Usage

# Regenerate Wrangler types in every worker
wx "wrangler types"

# Run typecheck across all workers
wx "bun run typecheck"

# Inspect package names
wx "cat package.json | jq .name"

# List source files per worker
wx "ls -la src/"

Filtering

Use WX_FILTER to target specific workers by glob pattern:

# Only wrangler-based workers (excludes dashboard, hoox)
WX_FILTER='*-worker' wx "wrangler types"

# Single worker
WX_FILTER='trade-worker' wx "bun run typecheck"

Custom Path

Set WX_WORKERS_DIR if your workers live elsewhere:

WX_WORKERS_DIR=~/other-project/workers wx "some command"

🕸️ 6. Codebase Dependency Graph

Hoox includes a function-level dependency graph extractor that maps all exported symbols, imports, calls, type references, and service bindings across the entire monorepo.

# Regenerate graph.json and graph.dot
bun run graph

This runs scripts/extract-graph.ts (ts-morph) across the workspaces. During extraction, a live progress bar shows each phase with elapsed time:

🔍 Extracting exported declarations...
  [██░░░░░░░░░░░░░░░░░░] 13%  exports: 1667 nodes             10.6s
🔍 Extracting import relationships...
  [█████░░░░░░░░░░░░░░░] 25%  imports: 2524 edges              0.1s
🔍 Extracting type references...
  [██████████░░░░░░░░░░] 50%  type refs: 2536 edges            1.7s
🔍 Extracting cross-file call expressions...
  [████████████░░░░░░░░] 63%  calls: 445 edges                 9.7s
  [████████████████████] 100% Done                             22.0s

⏱  Total time: 22.0s

The 8 extraction phases (exports → imports → extends/implements → type refs → calls → service bindings → workspace deps → filtering) typically finish in tens of seconds.

Outputs

Quick Render

# Install Graphviz if missing
# macOS: brew install graphviz
# Ubuntu: sudo apt install graphviz

# Render to SVG
dot -Tsvg graph.dot -o graph.svg && open graph.svg

🔗 Next Steps

Off Cloudflare®, hoox init --self-hosted prints bun run server.js / bun run docker:prod instructions and exits. Durable Objects, Vectorize, and Workers AI are unavailable in that mode.

• Testing Standards — Run unit and integration tests using Bun's native test runner.
• Debugging Runbook — Debug local and remote isolates, tail logs, and trace queries.