Installation

Install

v0 Two commands:

npm i -g hallway             # Node 22.13 or later
hallway service install      # run the daemon at every login

Then open http://localhost:4255, or run hallway open.

Just trying it?

npx hallway                  # the dashboard, in the foreground

That runs Hallway from npx’s cache until you close the terminal. It’s the quick way to try it, not to keep it: npm can delete that cache at any time, so hallway service install refuses to run from it (and hallway doctor flags a service that already does). To keep it, install it with the two commands above.

hallway service install registers the daemon with your OS’s own service manager and starts it, so the dashboard is always there without you starting anything:

• macOS: a LaunchAgent, ~/Library/LaunchAgents/hallway.daemon.plist, loaded now and at every login.
• Linux: a systemd user unit, ~/.config/systemd/user/hallway-daemon.service, enabled and started. A user unit runs while you are logged in; to keep it running without a login session (and from boot), enable lingering once with loginctl enable-linger $USER. Hallway never does that for you, and hallway doctor warns while it is off.
• Windows (best effort): a scheduled task, \hallway.daemon, that starts when you log on and runs hallway supervise, which keeps the daemon running and writes its logs. Its files are in %LOCALAPPDATA%\hallway\tasks\. It runs while you’re logged on. No administrator rights are needed, and none are asked for. This has run for real on GitHub’s Windows runners, but a real logon starting it hasn’t been tried on a Windows desktop yet.

It is idempotent: run it again any time. Undo it with hallway service uninstall; hallway service status says whether it is running.

Finally, tell your coding agents about it. This prints a short paragraph to paste into an agent instruction file such as CLAUDE.md or AGENTS.md:

hallway guide --snippet

Optional extras, each on its own page: memorable HTTPS names such as https://my-app.localhost with hallway setup, the MCP server and the dev-server hook for coding agents, and screenshot thumbnails.

To try Hallway without installing it as a service, run the daemon in the foreground instead:

hallway              # same as `hallway serve`; Ctrl-C to stop
hallway open         # open the dashboard in your browser

Requirements

OS	macOS (launchd) or Linux (systemd user units). Windows is best effort (per-user scheduled tasks): everything but fronted mode works; see the roadmap for what hasn’t been checked on a real Windows desktop.
Node	22.13 or later (for the built-in node:sqlite that holds uptime history).
Privileges	None. The daemon never runs as root, and nothing asks for sudo except hallway setup and hallway teardown.
For fronted mode v1	Optional, and macOS and Linux only. Caddy 2.7 or later (on macOS hallway setup installs it with Homebrew; on Linux, put a release binary from caddyserver.com on your PATH), and one guided sudo step. On Linux also systemd, nft and a system CA store. See Setup.
For custom domains v1	Optional. dnsmasq (Homebrew’s on macOS, which setup installs; on Linux the dnsmasq-base package or similar) and, on Linux, systemd-resolved.
For screenshots v2	Optional. About 300 MB of disk: hallway thumbs enable downloads a headless browser into the data home. See Thumbnails.

Why port 4255?

The default dashboard port is 4255, which spells HALL on a phone keypad, the same trick as Local Review’s 5622 (LOCA). It stays clear of common dev-server defaults (Angular 4200, Astro 4321, Jekyll and Phoenix 4000), of macOS’s AirPlay Receiver on 5000 and 7000, and of the range Hallway assigns to new apps (5100–5999). Override it with port: in config.yaml, or for one run with --port <n> or $PORT.

Where things go

Everything Hallway knows lives in one directory, the data home: ~/.hallway, or wherever $HALLWAY_HOME points. See The data home. Nothing is written outside it except the service definitions (launchd plists, systemd user units, or on Windows scheduled tasks and their files in %LOCALAPPDATA%\hallway\tasks\) for the daemon and any services you ask for, and, only during hallway setup, the files listed in Setup, teardown and doctor.