harn web

harn web <subcommand> [options]

Standalone Next.js dashboard for .harnery/ state. See concepts / web UI for the feature tour.

Note

The dashboard is not bundled in the npm package (which is the CLI + coord engine only). On an npm install, harn web up fetches it on first use: it clones the matching harnery version into ~/.cache/harnery/web/ and installs the web app’s deps, then runs it (later runs reuse the cache). Pass --no-fetch to skip that and get manual steps instead. See Install → npm vs git clone.

Subcommands

harn web up [--port 9000] [--coord-root <dir>] [--prod] [--no-fetch] [--max-old-space <mb>]
harn web build [--no-fetch]
harn web start [--port 9000] [--coord-root <dir>] [--no-fetch] [--max-old-space <mb>]

up

Boot the dashboard. Dev mode by default (HMR, no build needed). With --prod, runs next start (requires a prior web build).

harn web up
# → http://localhost:9000

harn web up --port 4000 --coord-root /path/to/some/repo
# → http://localhost:4000, reading .harnery/ from /path/to/some/repo

build

Produce the production bundle:

harn web build

Runs next build against harnery/web/. Output lands in harnery/web/.next/.

start

Start the production server (requires prior build):

harn web build && harn web start

Memory

up and start pin a V8 old-space ceiling of 2048 MB by default.

Without it, Next picks its own ceiling at roughly half of system RAM. On a large machine that is a limit a dashboard will never reach, so V8 never feels enough pressure to run a major GC, and a server left up for days settles at a multi-gigabyte working set that is mostly collectable garbage. On one 32 GB machine a dev server sat at 7.9 GB after three days; the same server under the default ceiling held at 1.7 GB, and the production build held at 0.4 GB.

Raise it, lower it, or opt out entirely:

harn web up --max-old-space 4096      # roomier ceiling
HARNERY_WEB_MAX_OLD_SPACE=1024 harn web up
harn web up --max-old-space 0         # opt out; Next sizes it again

Precedence is flag, then HARNERY_WEB_MAX_OLD_SPACE, then the default. A ceiling you set yourself in NODE_OPTIONS is always left alone.

For a dashboard that stays up, prefer build + start over up: the production server carries no bundler state, no source maps, and no HMR machinery, which is most of the difference.

First-run fetch (npm installs)

The npm package omits the dashboard to keep the CLI lean. When web/ is absent (a plain npm i -g harnery), the first harn web up fetches it:

1. Clones the harnery repo at the matching version tag (v<your version>) into ~/.cache/harnery/web/<ref>/.
2. Installs the web app’s deps there (just web/; no root install, no browser downloads).
3. Boots it. Later runs reuse the cache, so only the first launch pays the cost.

Flag / env	Effect
--no-fetch	Skip the fetch; print manual clone steps instead. Works on build / start too.
HARNERY_WEB_REF=<ref>	Fetch a specific git ref instead of the version tag (e.g. next, a branch).

The fetched dashboard matches your installed harnery version, so it stays in sync with the coord schema the CLI writes.

Networking

Localhost-only by default. For cross-device access (phone, second laptop), pair with harn tunnel:

harn web up &
harn tunnel up --target 127.0.0.1:9000

harn tunnel runs an IP-gated reverse-proxy in front of a Cloudflare quick tunnel; see harn tunnel for the allowlist + setup story.

Coord root resolution

The dashboard resolves .harnery/ from, in order:

1. --coord-root <dir> flag
2. HARNERY_COORD_ROOT env var
3. Walk up from cwd looking for a .harnery/ directory (up to 8 levels)