INIT / Install

[GET HOOX RUNNING]

Source, package managers, Docker, or Cloudflare — pick a path. Operate with CLI, TUI, or dashboard.

Back to homeClone on GitHubDocs · Install
Fastest path
git clone --recursive …→bun install→hoox onboard→hoox deploy all --auto
[ source ]01Full StackRecommended

From Source

Clone the monorepo with all worker submodules, install workspace dependencies, and run the one-shot onboard wizard. This is the canonical path for contributors and operators who need the full worker mesh.

  • ▸Workers are Git submodules — without --recursive they will be empty directories.
  • ▸If you already cloned, run: git submodule update --init --recursive
  • ▸After the first run from the monorepo, hx / hoox remember the path (HOOX_REPO / ~/.hoox/config/monorepo.json) so commands work from any directory.
GitHub Repository ↗5-Minute Quick Start
[ package ]02CLI OnlyRecommended

Via Bun (Global CLI)

Install @hoox-sh/hoox-cli@0.13.1 globally with Bun (bins: hoox + hx). Requires Bun ≥ 1.2 — the CLI is a Bun bundle and will not run under Node.js even if installed via npm. Aligns with @hoox-sh/hoox-shared@1.4.0 and optional @hoox-sh/hoox-tui@0.3.2.

Optional TUIbun add -g @hoox-sh/hoox-tui@0.3.2
Aliashx --version
  • ▸Global install gives you hoox and the short alias hx; you still need a cloned workspace for deploy and dev.
  • ▸First run from the monorepo remembers the path — later hx check health works from any cwd.
  • ▸Run hoox update to pull the monorepo / wrangler; reinstall the npm package to upgrade the CLI binary.
  • ▸Published packages: @hoox-sh/hoox-shared@1.4.0, @hoox-sh/hoox-cli@0.13.1, @hoox-sh/hoox-tui@0.3.2.
npm package ↗
[ package ]03Unsupported

Via npm — will abort

npm install -g @hoox-sh/hoox-cli aborts. The published package currently ships optionalDependencies["@hoox-sh/hoox-tui"] = "workspace:*", which npm cannot resolve. Do not use npm as an install path. Supported path is Bun only: bun add -g @hoox-sh/hoox-cli@0.13.1.

Do not run (aborts)npm install -g @hoox-sh/hoox-cli@0.13.1
  • ▸npm global WILL FAIL at optionalDependencies resolution (workspace:*).
  • ▸The CLI is a Bun bundle and will not run under Node.js even if npm could fetch the tarball.
  • ▸Use bun add -g @hoox-sh/hoox-cli@0.13.1 — there is no working npm alternative.
[ docker ]04Compose Profiles

Docker — Local Dev

Run the full worker mesh and dashboard locally via Docker Compose. Mirrors production service-binding topology — only hoox (gateway) and dashboard expose host ports.

Gateway# http://localhost:8787
Dashboard# http://localhost:8794
  • ▸Profiles: workers, dashboard, full (workers + dashboard).
  • ▸Requires .env.local for exchange keys and Telegram token (optional on fresh clone).
  • ▸Equivalent native path: hoox dev start --runtime native
[ docker ]05Air-Gapped

Docker — Production / Self-Hosted

Build the production image (Dockerfile.prod) for demos, local testing, or air-gapped deployments. Not a full substitute for Cloudflare® edge — Durable Objects, Vectorize, and Workers AI are unavailable.

  • ▸Self-hosted gateway requires HOOX_SERVER_API_KEY for authenticated requests.
  • ▸Cloudflare®-specific features (DO idempotency, Vectorize RAG, Browser Rendering) are not supported self-hosted.
  • ▸Production recommendation: hoox deploy all --auto on Cloudflare® Workers.
[ cloudflare ]06ProductionRecommended

Deploy to Cloudflare®

Deploy all 10 workers and the OpenNext dashboard to Cloudflare®'s edge. The onboard wizard provisions D1, KV, secrets, and deploys in the correct dependency order.

  • ▸Dashboard deploys to Cloudflare® Workers via OpenNext — not Cloudflare® Pages.
  • ▸Pass credentials non-interactively: hoox onboard --token cfut_xxx --account xxx --preset full
  • ▸Prefer an API token over wrangler login on remote/headless boxes (OAuth timeouts / stale-tab mismatch).
  • ▸The “Edit Cloudflare Workers” token template is not enough. Required Account permissions:
  • ▸Account → Workers Scripts: Edit
  • ▸Account → Workers KV Storage: Edit
  • ▸Account → Workers R2 Storage: Edit
  • ▸Account → D1: Edit (required — D1 list is 401 without it)
  • ▸Account → Queues: Edit
  • ▸Account → Vectorize: Edit (gateway/telegram RAG)
  • ▸Account → Workers Observability: Read (optional)
  • ▸Account → Workers AI: Edit (optional, agent-worker)
  • ▸Account → Account Settings: Read (whoami)
  • ▸User → Membership: Read if whoami needs it.
Installation GuideDeploy Workers GuideCloudflare® Dashboard ↗
[ source ]07Fine Control

Init & Setup (Step-by-Step)

Split onboarding into init (writes wrangler.jsonc, collects secrets) and setup (generates keys, applies D1 schema, pushes secrets, deploys dashboard). Use when you need granular control over provisioning.

  • ▸hoox init --self-hosted prints the VPS / Docker path and exits — it does not write a Cloudflare-free wrangler.jsonc.
  • ▸Self-hosted / air-gapped path: bun run docker:prod or bun run server.js. See Docker — Production above.
  • ▸Resume interrupted wizard: hoox onboard --resume
Interfaces

[CLI · TUI · DASHBOARD]

CLI for automation, TUI for ops, dashboard for monitoring.

CLI

Full ref

~30 command groups · 100+ subcommands

The primary operator interface. Manages workers, infrastructure, secrets, deployments, health checks, monitoring, repair, and performance measurement. Running hoox with no arguments launches the TUI.

Recommended entry point

Remembered monorepo + runtime

Workers + dashboard + wiring

Interactive native vs Docker

Post-deploy verification

pyne-worker evaluate host

Live trade stream

Latency probes

Workers Observability

Diagnose & fix

TUI

OpenTUI terminal dashboard

Full-screen terminal operations center. Monitor workers, trades, logs, and deployments without leaving the shell. Launch via hoox tui or bun run from packages/tui.

@hoox-sh/hoox-tui@0.3.2

From any workspace

Hot reload

Standalone

Repo root script

Keyboard shortcuts
Ctrl+1Dashboard view
Ctrl+2Workers overview
Ctrl+4Trade monitor
Ctrl+5Logs viewer
Ctrl+6Service manager (deploy/restart)
Ctrl+8Setup wizard
Ctrl+PCommand palette
Ctrl+QQuit

Dashboard

Next.js 16 · OpenNext on Workers

Web command center for portfolio monitoring, risk management, and emergency actions. Reads from D1, writes to CONFIG_KV, dispatches through the hoox gateway. Protected by Cloudflare® Access in production.

localhost:3000

Same as above

Build + deploy to Workers

Same as above

localhost:8794

  • ▸Production URL: https://<your-subdomain>.workers.dev (set during onboard)
  • ▸Requires hoox, d1-worker, and agent-worker running for full functionality
Install paths7
Workers10
CLI version0.13.1
hoox onboard → hoox deploy all --auto → live on edge