Happier Docs
hstack (local stack)

Setup

Install hstack, choose a workspace, and initialize main/dev checkouts.

Prerequisites

  • Node.js
  • Yarn
  • Docker (recommended if you plan to use happier-server full flavor)
  • Tailscale (optional, but recommended for phone/remote access)

Install and initialize

hstack can be run either:

  • as an installed CLI (recommended once published), or
  • via npx (good for one-off setup), or
  • from a local checkout (maintainers / when the npm package isn’t published yet).

Development profile (recommended for contributors):

hstack setup-from-source --profile=dev

Self-host profile (stable / production-ish):

happier relay host install --mode system

Legacy wrapper (still supported):

hstack self-host install # forwards to `happier relay host install` when supported

Enable auto-updates (opt-in) at install time:

hstack self-host install --auto-update --auto-update-at=03:15

You can also update the schedule after install:

hstack self-host config set --auto-update --auto-update-at=03:15

Legacy alias (still supported):

hstack setup --profile=selfhost # deprecated; use setup-from-source or self-host install
hstack setup-from-source --profile=selfhost

Use a different stable branch

By default, setup-from-source uses main for the stable main/ workspace checkout. To target a different branch (for example preview):

hstack setup-from-source --profile=selfhost --stable-branch=preview

This persists HAPPIER_STACK_STABLE_BRANCH in your user config so future bootstrap/review flows keep using the same branch.

Choose a workspace directory

The workspace is where hstack stores:

  • main/ (stable checkout; treat as read-only)
  • dev/ (dev branch checkout for development)
  • categorized worktrees:
    • pr/…
    • local/<owner>/…
    • tmp/<owner>/…

You can set it explicitly:

hstack setup-from-source --profile=dev --workspace-dir=~/Documents/Development/happier

Or by env var:

export HAPPIER_STACK_WORKSPACE_DIR=~/Documents/Development/happier

Developing hstack itself (local CLI root)

When you’re iterating on the hstack source code inside the monorepo, you can point the installed shim at your local checkout:

export HAPPIER_STACK_CLI_ROOT_DIR=~/Documents/Development/happier/dev/apps/stack
hstack help

To confirm what hstack is actually using on your machine, run:

hstack where

hstack (Happier Stack)

Self-host, run, and develop Happier locally with stacks + worktrees.

Development workflow

The “one-stop” guide to develop Happier locally with hstack (worktrees + stacks + dev-auth).

On this page

PrerequisitesInstall and initializeGuided setup (recommended)Use a different stable branchChoose a workspace directoryDeveloping hstack itself (local CLI root)