Running (dev vs start)

start vs dev

• hstack start / hstack stack start <name>: production-like (prefer built UI; fewer watchers)
• hstack dev / hstack stack dev <name>: development (watch mode, faster iteration)

If you’re unsure, use hstack tui stack dev <stack> (or hstack stack dev <stack> in non-interactive environments).

For named stacks only, start can also run from an activated runtime snapshot stored under the stack folder instead of the live repo checkout:

hstack stack build exp1 --activate-runtime
hstack stack start exp1 --runtime

Use this when you want:

• stack-local production artifacts for web + server + daemon
• service installs that are insulated from source rebuild churn in the same checkout
• a production-like stack against the same worktree you are editing in another stack

Keep using dev when you want watchers, Metro, or rapid source iteration.

TUI mode (recommended for interactive development)

For local interactive work, prefer wrapping your run command in the hstack TUI:

hstack tui stack dev dev
# mobile dev-client + QR:
hstack tui stack dev dev --mobile

In non-interactive terminals / CI (or if the TUI is unavailable), run the underlying command directly:

hstack stack dev dev

Browser origin isolation (important)

When you run multiple stacks, browser state (cookies/localStorage) can collide if you always use http://localhost:....

hstack prefers stack-specific origins for non-main stacks when it matters (so stacks don’t fight over browser auth/session state).

Tip: if you see “auth looks wrong” between stacks, check:

• which stack you’re using (hstack stack info <name>)
• which UI URL you opened (use the one printed by hstack)

Browser auto-open (--no-browser)

In interactive runs, hstack dev / hstack start may auto-open the UI in your browser.

• Disable: --no-browser
• Global disable: HAPPIER_STACK_NO_BROWSER=1

Watch mode (hot-reload-ish)

In interactive TTY runs, hstack dev enables watch mode by default:

• happier-cli changes → rebuild + restart the daemon
• some long-lived processes can be restarted safely when hstack knows they are stack-owned

Control flags:

• Force enable: hstack dev --watch
• Disable: hstack dev --no-watch

If hstack prints that a restart is disabled because the PID is unknown, re-run with --restart so hstack can spawn and track the process.

Runtime-backed named stacks

Build targets:

hstack stack build exp1 --web
hstack stack build exp1 --server
hstack stack build exp1 --daemon
hstack stack build exp1 --all

Full runtime activation:

hstack stack build exp1 --activate-runtime

Partial runtime activation:

hstack stack runtime exp1 activate --web
hstack stack runtime exp1 activate --server
hstack stack runtime exp1 activate --daemon
hstack stack runtime exp1 activate --all

Typical production-like named-stack update flow:

hstack stack build exp1 --activate-runtime
hstack stack service exp1 restart

Component-only update flows:

# UI-only: build the artifact, activate only web, then reload the browser
hstack stack build exp1 --web
hstack stack runtime exp1 activate --web

# Server-only: build + activate only server, then restart
hstack stack build exp1 --server
hstack stack runtime exp1 activate --server
hstack stack service exp1 restart

# CLI/daemon-only: build + activate only daemon, then restart
hstack stack build exp1 --daemon
hstack stack runtime exp1 activate --daemon
hstack stack service exp1 restart

Launch selection:

hstack stack start exp1 --runtime
hstack stack start exp1 --source

Persistent mode:

hstack stack env exp1 set HAPPIER_STACK_RUNTIME_MODE=prefer

Mode meanings:

• source: always use the live checkout
• prefer: use the active runtime snapshot when present, otherwise source
• require: fail unless an active runtime snapshot is valid

Important:

• hstack stack build <name> with no flags still builds the web bundle only for backward compatibility.
• hstack stack build <name> --web|--server|--daemon only updates artifacts. It does not switch the running stack to those artifacts until you activate a new runtime snapshot.
• --tauri still belongs to the legacy local hstack build flow and is not part of named-stack artifact/runtime builds in v1.
• Runtime snapshots are currently a named stack feature. Repo-local yarn tui, hstack dev, and repo-local hstack start are still source-backed flows.
• hstack stack dev <name> remains source-only; runtime snapshots are for start and stack services.
• Web-only activation updates the stable runtime/current/ui path, so a browser reload is enough.
• Server-only or daemon-only activation requires a restart so the process re-resolves the active runtime.
• A running named-stack service does not switch server/daemon processes in place. Rebuild or activate first, then restart the service or stack process so it re-resolves the active snapshot.

Safe restarts

Both hstack start and hstack dev support --restart:

hstack dev --restart
hstack start --restart

For a named stack:

hstack stack dev exp1 -- --restart
hstack stack start exp1 -- --restart

Stopping stacks safely

Stop a single stack:

hstack stack stop exp1

Stop multiple stacks:

hstack stop --except-stacks=main --yes

Useful flags:

• --aggressive: stop additional daemon-tracked sessions (still stack-owned)
• --sweep-owned: final sweep for processes that still carry the stack env in their process env
• --no-docker: skip Docker-managed infra shutdown

CLI build behavior (happier-cli)

When running stacks, hstack may ensure the CLI is built when needed (so the daemon can start).

Controls:

• HAPPIER_STACK_CLI_BUILD_MODE=auto|always|never
• HAPPIER_STACK_CLI_BUILD=0 (hard-disable)