Quickstart

Everything on this page works in the current release, on macOS and Linux, with no sudo, and on Windows (best effort) with no administrator rights. For the details of installing (Node version, lingering on Linux, the scheduled task on Windows), see Installation.

1. Start it

npm i -g hallway
hallway service install      # run the daemon at every login
hallway open

Only trying it out? npx hallway runs the dashboard in the foreground, until you close the terminal. Install it as above to keep it: Hallway won’t install a service from npx’s cache, which npm can delete at any time.

The dashboard opens at http://localhost:4255. The page title is your machine’s name.

2. Meet what is already running

You probably have servers running already. Within a couple of minutes the scanner lists them under Found running — not yet named:

:4666  dashboard · ~/Code/dashboard-wt-b @ feature/new-chart · up 9 days · orphaned
       [Claim]  [Ignore ▾]

For each one Hallway shows what it could work out: the project directory (from the process’s working directory, because command lines like node dist/index.js say nothing), the git branch, how long it has been up, the page <title>, and orphaned if the session that started it has gone. Noise is filtered out: IDE and agent-tool helpers on high ephemeral ports, databases, and system daemons never appear. See Apps.

Claim the ones you care about. Claiming writes a small file, ~/.hallway/apps/<slug>.yaml, on the port the app already uses (Hallway never changes an app’s port), and the row becomes a card in Apps. Ignore the rest, by port, by process name or by directory.

The same from a terminal:

hallway scan                    # what is listening, with identity
hallway claim 4666 --slug dashboard
hallway ignore 631 --by port

3. Add an app by hand

Any server you know about can be declared with one command or one file:

hallway app add slides --port 4321 --name "Slides"

or create ~/.hallway/apps/slides.yaml in your editor:

name: Slides
port: 4321

An open dashboard shows the new card within a second, without a reload. Edit or delete the file and the page follows. If you break the YAML, that one card shows the file, line and error; everything else keeps working, and Hallway never rewrites a file you broke.

4. Say which apps should be up

Each app says what you expect of it. Something that should always be up is running; if it stops answering it turns down, the only alarming state. Something you only run sometimes is adhoc (claimed apps start that way), and when it is off it shows as a calm, closed door instead:

expected: running    # running | adhoc | stopped

See Health states.

5. Hang up some bookmarks

Create ~/.hallway/bookmarks/production.yaml:

title: Production
links:
  - title: Admin console
    url: https://admin.example.com
  - title: Status page
    url: https://status.example.com

They appear as favicon chips under Bookmarks. See Bookmarks.

6. Tell your agents

Add a short paragraph to your AGENTS.md or CLAUDE.md so agents stop leaving orphans behind:

hallway guide --snippet

See Working with agents.

Next

• hallway run: start a dev server that outlives the session, on a stable port.
• Services and reboots: keep apps running across restarts, and see what the last reboot took down.
• Fronted mode: https://slides.localhost instead of a port, after one hallway setup (macOS and Linux only).
• Thumbnails: screenshots of your apps on their doors, or generated cards.
• The MCP server and the dev-server hook, for coding agents.
• The CLI reference and the file formats.