[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

---

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: All background workers (9 services — no dashboard UI)
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 Stack — all 10 services
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

In the local environment, each V8 dev instance mounts to a dedicated host port. Ensure no other applications are occupying these ports before launching:

---

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/.dev.vars.example workers/hoox/.dev.vars

# 2. Inject local mock keys for testing
echo 'INTERNAL_KEY_BINDING="local_test_key"' >> workers/hoox/.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 "pnpm 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 "pnpm 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) and scans 917 source files across all 14 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) complete in ~20–25s on average.

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

• 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.