Skip to content
Hallway
Hallway is out (npm i -g hallway): v0, v1 and v2 have shipped, apart from checking it all on a real Mac. See the roadmap.

The dashboard

The dashboard is meant to be good enough to set as your browser’s home page. That is a requirement, not polish. This page describes the design the dashboard follows (v0, with later additions marked); the sketches are drawn in text from that design, not screenshots.

Principles

Section titled “Principles”
  1. A jumping-off point, not a control panel. The main action is go to the thing.
  2. Instant. Everything is local, so the whole page paints from one request in well under 200 ms. Live updates arrive over Server-Sent Events; there are no spinners on the main view.
  3. Calm. Most of the time everything is fine or intentionally off, so the page is quiet. Only down is alarming.
  4. Dense but legible. Many apps visible at once on a laptop screen.
  5. Keyboard-first. It must be faster than remembering a URL.
  6. Never needs hand-maintenance to stay accurate.

Layout

Section titled “Layout”
┌──────────────────────────────────────────────────────────────────────────────┐
│ HALLWAY · my-laptop                        [ / filter…    ]  ● 9 up · 1 down │
├──────────────────────────────────────────────────────────────────────────────┤
│ ⚠ Lost at last reboot (Mon 28 Sep 20:05): 6 apps   [Review] [Dismiss]        │
├──────────────────────────────────────────────────────────────────────────────┤
│ APPS                                                                         │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐          │
│ │ [tile]       │ │ [tile]       │ │ [tile]       │ │ [tile]       │          │
│ │ Slides       │ │ Log viewer   │ │ Docs site    │ │ dash @ wip   │          │
│ │ :4321        │ │ :7333        │ │ :4455        │ │ :4670        │          │
│ │ ▮▮▮▮▮▮▮▮▮▮   │ │ ▮▮▮▮▮▮▮▯▮▮   │ │ ░░░░░░░░░░   │ │ ▮▮▮▮▮        │          │
│ │ ● 99.9% 12ms │ │ ● 98.1% 40ms │ │ ○ stopped    │ │ ● adhoc      │          │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘          │
├──────────────────────────────────────────────────────────────────────────────┤
│ FOUND RUNNING — NOT YET NAMED                                                │
│ :4666  dashboard · ~/Code/dashboard-wt-b @ feature/new-chart · up 9 days     │
│        orphaned   [Claim]  [Ignore ▾]                                        │
├──────────────────────────────────────────────────────────────────────────────┤
│ BOOKMARKS                                                                    │
│ Production   (◉ Admin console) (◉ BI dashboards) (◉ Status page)             │
│ Docs         (◉ API reference) (◉ Runbooks)                                  │
└──────────────────────────────────────────────────────────────────────────────┘

Which sections appear, and in what order, is dashboard.sections in config.yaml. The observed tray hides itself when empty, and so do bookmarks.

App cards

Section titled “App cards”

Top to bottom:

  • A thumbnail: the app’s favicon on a tile of its own dominant colour, or a monogram when it has none. v2 Opt in to real screenshots (hallway thumbs enable) and each healthy app’s door gets a pane of glass showing the app itself, re-shot when the app restarts and every six hours. Or set thumbnails.mode: card and every door is drawn as a generated card with its name, address, framework and repo @ branch. See Thumbnails.
  • The name, and for worktree siblings repo @ branch in smaller type.
  • The address, the main click target: localhost:4321 in direct mode, slides.localhost in fronted mode (with the port beside it as a direct link that skips the proxy), with a copy button on hover.
  • The uptime bar for the last 24 hours, with the uptime percentage and median latency.
  • The state, as colour, shape and word: ● healthy, ▲ unhealthy, ■ down, ○ stopped, ◌ unknown.
  • Badges, only when relevant: orphaned (the session that started it has gone and no service manager runs it), exposed (bound to every interface, so reachable from your network; more), managed (a launchd, systemd or scheduled-task service), its source, or a config error. Hover over or focus orphaned or exposed for what it means.

Click or Enter opens the app; ⌘/Ctrl-click opens a new tab. A secondary button opens the detail drawer: full identity (directory, git branch and last commit, framework, PID, start time, the command that started it), uptime and latency history over 24 hours, 7 days or 90 days, a larger screenshot when there is one, the YAML file with an “open in editor” link, deep links and any config error. Start, stop and restart buttons and a live log tail for managed services are not built yet: use hallway stop, start, restart and logs.

After a reboot, a Lost at last reboot banner sits above the apps, listing what was running before and didn’t come back, with Restart once, Make it a service and Dismiss. See Services and reboots.

Keyboard

Section titled “Keyboard”
KeyAction
/Focus the filter (fuzzy over name, slug, host, port, directory, branch and bookmark titles)
↑ ↓ ← →Move between cards and chips
EnterOpen; ⌘/Ctrl-Enter opens a new tab
cCopy the focused item’s URL
iOpen the detail drawer
EscClear the filter, or close the drawer
?Show the shortcuts

Type a filter that matches exactly one thing and press Enter to open it: faster than remembering a URL.

Errors and empty states

Section titled “Errors and empty states”
  • A broken YAML file shows its error in place, on the affected card (or as a banner for config.yaml and bookmark files), with the file, line and message. Never a blank page.
  • With no apps declared yet, the page leads with the observed tray: “We found 4 web servers running. Name the ones you care about.”
  • With nothing running and nothing declared, it shows the two commands that matter and a link to the agent guide.

The hallway

Section titled “The hallway”

The visual design is a calm, well-lit hallway. Each app is a numbered door; its port is the brass door number; its state shows in the door (ajar with lamplight for healthy, closed for stopped, dark for down). Unclaimed listeners are noises behind doors you didn’t know were there; bookmarks hang by the front door. The theme is dark-first, a warm corridor at night with lamplight amber, with a daylit light theme.

The imagery always sits on top of plain labels: “Claim”, “Ignore” and “Down” stay as they are, and nobody has to decode a pun to read a state. Why the name tells where it comes from.