hstack (Happier Stack)

hstack runs Happier from your own checkout. Its job is isolation: several complete instances (stacks) side by side on one machine, each pinned to its own checkout, ports and data directory, so a branch you are testing cannot disturb the one you are developing.

For interactive work, prefer the TUI wrapper — it shows what each command is doing rather than leaving you to read log files:

hstack tui stack dev dev

Get set up

• Setup — installing hstack, choosing a workspace, initializing the main and dev checkouts.
• Paths, folders and env precedence — where everything lands, and which env file wins.

Day to day

• Development workflow — the one-stop guide: worktrees, stacks and dev-auth together.
• Quickstarts — the copy/paste companion for feature work, PR testing and server changes.
• Running (dev vs start) — how the server, daemon and UI come up, watch mode, and safe restarts.
• Remote development targets — mirroring one checkout to Linux, macOS or Windows machines.
• Validation — typecheck, lint and test, scoped to a checkout or a stack.
• CLI reference — the commands you will actually use, with the flags that matter.

How isolation works

These four pages are the model. Read them before wondering why two stacks share something they should not.

• Stacks — isolated instances: ports, directories and repo pinning.
• Worktrees and forks — clean upstream PR worktrees with fork-only patches kept out of them.
• Auth (dev-auth seeding) — seed credentials once, reuse them for new stacks without logging in again.
• Server flavors — light (SQLite, optionally PGlite) against full (Docker-managed infrastructure).

Reaching a stack from elsewhere

• Remote access (Tailscale) — an HTTPS secure context on a phone or another laptop.
• Remote daemon setup (SSH) — installing Happier and pairing credentials on a remote host.
• Remote server setup (SSH) — installing the self-host server on one.

Other surfaces

• Mobile (iOS) — the dev-client workflow for a local stack.
• Desktop app (Tauri) — the native wrapper around the web UI.
• Menu bar (SwiftBar) — monitoring stacks and switching worktrees from the macOS menu bar.
• Isolated Linux VM — repeatable validation in a clean VM on Apple Silicon.

Workflow tooling

• Edison — tasks, QA and evidence capture, run through hstack so isolation still holds.
• Monorepo port — bringing commits from the legacy split repos into the monorepo.

When something is wrong

• Debugging — effective paths, the pinned repo, ports, logs and the env knobs that change them.
• Troubleshooting — the common failures: auth, ports, wrong checkout, unhealthy stacks.