# Hallway > The front door for everything you vibe-coded on a random port. A small, always-on, local-only service for a developer's own machine (macOS and Linux, and Windows best effort): a live dashboard of every local web server (declared, discovered from other tools, or simply found listening), with health, uptime and bookmarks; native user services (launchd, systemd, or a scheduled task on Windows) for the apps that should survive a reboot; and, on macOS and Linux, memorable HTTPS hostnames via Caddy. **Status: v0 is released** (`npm i -g hallway`, Node 22.13+). Each feature is marked v0 (available now), v1 or v2 (upcoming); see https://hallway.edspencer.net/roadmap/. Every page below is also available as Markdown at the same URL with `.md` instead of the trailing slash. ## Getting Started - [Introduction](https://hallway.edspencer.net/introduction.md): What Hallway is, the problem it solves, and what shipped when. - [Installation](https://hallway.edspencer.net/getting-started/installation.md): Installing Hallway from npm on macOS, Linux or Windows, and what it needs. - [Quickstart](https://hallway.edspencer.net/getting-started/quickstart.md): The first five minutes with Hallway. ## Concepts - [Apps: declared, discovered, observed](https://hallway.edspencer.net/concepts/apps.md): Where every app on the dashboard comes from, how the scanner identifies unknown servers, and claiming. - [Health states](https://hallway.edspencer.net/concepts/health.md): The five states an app can be in, how probes decide, and why "stopped on purpose" is never red. - [Direct and fronted mode](https://hallway.edspencer.net/concepts/modes.md): Linking to localhost ports (direct mode, the default) versus memorable HTTPS hostnames through Caddy (fronted mode). - [Services and reboots](https://hallway.edspencer.net/concepts/services.md): Keeping apps alive with native launchd jobs, systemd user units or Windows scheduled tasks, the PATH trap, log rotation, and "lost at last reboot". - [Bookmarks](https://hallway.edspencer.net/concepts/bookmarks.md): Groups of links to the remote things you always forget the URL of, hung by the front door. - [The dashboard](https://hallway.edspencer.net/concepts/dashboard.md): The home screen, app cards, the observed tray, keyboard shortcuts and the hallway design. - [Thumbnails](https://hallway.edspencer.net/concepts/thumbnails.md): The picture on each door: a favicon by default, opt-in screenshots (hallway thumbs enable), or generated cards. ## Networking - [Fronted mode and HTTPS](https://hallway.edspencer.net/networking/fronted-mode.md): How Hallway uses Caddy, running as you, to serve every app at https://.localhost, and why it rewrites the Host header. - [Custom domains](https://hallway.edspencer.net/networking/custom-domains.md): Serving apps under your own namespace such as myname.internal, and which domains to avoid. - [Setup, teardown and doctor](https://hallway.edspencer.net/networking/setup-and-doctor.md): The one command that needs sudo, what it changes and why that is safe, how to undo it, and the diagnostics that check everything. ## Working with agents - [Files first](https://hallway.edspencer.net/agents/overview.md): How coding agents work with Hallway - plain YAML, live updates, one command to start servers, and MCP. - [hallway run](https://hallway.edspencer.net/agents/hallway-run.md): The one command agents should use to start a dev server, so it never becomes an orphan. - [Agent guide and llms.txt](https://hallway.edspencer.net/agents/agent-guide.md): The guide Hallway prints for agents, the snippet for your instruction files, and the optional hook. - [MCP server](https://hallway.edspencer.net/agents/mcp.md): Typed tools for apps and bookmarks, served on the dashboard's own port - and why none of them launch anything. - [The dev-server hook](https://hallway.edspencer.net/agents/hook.md): An optional Claude Code hook that stops an agent starting a dev server directly, and tells it the hallway run command to use instead. ## Reference - [CLI](https://hallway.edspencer.net/reference/cli.md): Every hallway command and its flags, as `hallway --help` lists them, with the milestone each belongs to. - [config.yaml](https://hallway.edspencer.net/reference/config-yaml.md): Global settings for the data home - the daemon port, mode, domain, proxy, probing, services, scanning, thumbnails and the dashboard. - [apps/.yaml](https://hallway.edspencer.net/reference/app-yaml.md): The format of a declared app - one file per app, named after its slug. - [Bookmarks and ignore files](https://hallway.edspencer.net/reference/bookmarks-yaml.md): The formats of bookmarks/.yaml and ignore.yaml. - [The data home](https://hallway.edspencer.net/reference/data-home.md): Where Hallway keeps everything - which files are yours to edit and which are machine-written. - [HTTP API](https://hallway.edspencer.net/reference/http-api.md): The daemon's JSON API and its live event stream. - [Environment variables](https://hallway.edspencer.net/reference/environment.md): The few environment variables Hallway reads, and the ones it sets for managed services. ## Guarantees & security - [No root in the daemon](https://hallway.edspencer.net/guarantees/no-root.md): Hallway's daemon never runs as root; the only privileged step is one explicit, printed command. - [Your ports stay put](https://hallway.edspencer.net/guarantees/ports.md): Hallway never moves an app to a different port, because apps hardcode their own. - [Localhost security](https://hallway.edspencer.net/guarantees/localhost-security.md): How the daemon defends against other web pages, DNS rebinding and cross-site requests. ## Project - [Roadmap](https://hallway.edspencer.net/roadmap.md): What shipped in which release (v0, v1 and most of v2 are out, plus Windows best effort), what is left, and the acceptance criteria each milestone is checked against. - [Why the name](https://hallway.edspencer.net/why-the-name.md): How Spaghetti Junction became Hallway, the names considered on the way, and the corridors behind the design. - [Contributing](https://hallway.edspencer.net/contributing.md): How the project is organised, how to help while it is young, and how to work on this site.