The binary is hallway. (A short alias, hw, has been proposed but not decided.) Every listing command takes
--json for agents and scripts. hallway --help prints the same list, grouped the same way.
Exit codes: 0 success, 1 error, 2 usage error (the usage is printed).
Each command is marked with the milestone it belongs to. Everything on this page is in the current release.
| Command | Description | |
|---|
hallway / hallway serve [--port N] [--quiet] | Run the daemon in the foreground (the default command): the dashboard and API on http://localhost:<port>, 127.0.0.1 only. The port is --port, else $PORT, else port: in config.yaml, else 4255. --quiet (-q) prints just the “Hallway on ” line. | v0 |
hallway open | Open the dashboard in your browser (https://hallway.localhost, or your domain’s, in fronted mode). | v0 |
hallway service install | Generate and load the daemon’s service, so it runs at every login: ~/Library/LaunchAgents/hallway.daemon.plist on macOS, ~/.config/systemd/user/hallway-daemon.service on Linux, the scheduled task \hallway.daemon on Windows (best effort; starts at logon). Idempotent. | v0 |
hallway service uninstall | Unload and remove it. | v0 |
hallway service status [--json] | Whether the daemon’s job is loaded and running, and its last exit code. | v0 |
hallway service restart | Restart the daemon’s service. | v0 |
hallway --version, hallway --help | | v0 |
| Command | Description | |
|---|
hallway status [slug] [--json] | Every app’s state, address, port and 24-hour uptime. Works without the daemon (it reads the files and probes once), but is richer with it. | v0 |
hallway scan [--json] | Look for listeners nobody has named, and print them with identity. | v0 |
hallway claim <port|id> [--slug S] [--name N] [--expected E] | Turn an observed listener into a declared app. | v0 |
hallway ignore <port|id> [--by port|process|dir] | Hide an observed listener. | v0 |
hallway lost [--json] | What was running before the last reboot and isn’t now. See Lost at last reboot. | v1 |
hallway lost restart|service <id|port> [--slug S] | Start one again: once, or as a service, the way hallway run would. Needs the daemon. | v1 |
hallway lost dismiss <id|port> / hallway lost dismiss --all | Clear one, or the whole notice. | v1 |
hallway app add <slug> [--port N] [--name N] [--expected E] [--health PATH] | Declare an app (writes apps/<slug>.yaml); without --port it gets a free port from the assignment range. | v0 |
hallway app ls [--json] | List the declared apps. | v0 |
hallway app edit <slug> | Open the app’s YAML in $VISUAL or $EDITOR. | v0 |
hallway app rm <slug> | Remove an app: its file moves to backups/removed/, and its service is removed first if it has one. | v0 |
| Command | Description | |
|---|
hallway run <slug> [--cwd DIR] [--port N] [--persist] [--name N] -- <command...> | Start a server as a user service (launchd, systemd, or a scheduled task on Windows) on a stable port, wait for it to listen, print its URL and exit. $PORT in the command (quote it: '$PORT') becomes the app’s port. See hallway run. | v1 |
hallway stop <slug> / start <slug> / restart <slug> | Stop, start or restart a managed app. | v1 |
hallway logs <slug> [--lines N] [--follow] | Tail a managed app’s logs. | v1 |
hallway service add <slug> [-- <command...>] | Keep a declared app running: at login, and restarted if it exits. | v1 |
hallway service rm <slug> | Stop managing it; the app stays declared. | v1 |
hallway service regenerate [slug] | Rewrite the generated services, e.g. after a Node upgrade broke an absolute path. | v1 |
| Command | Description | |
|---|
hallway bookmark add <group> <url> [--title T] [--description D] | Add a link to a group (creating the group if needed). | v0 |
hallway bookmark ls [group] [--json] | List groups and links. | v0 |
hallway bookmark rm <group> <url|number> | Remove a link, by its URL or its position in the list. | v0 |
hallway bookmark edit <group> | Open the group’s YAML in $VISUAL or $EDITOR. | v0 |
| Command | Description | |
|---|
hallway setup [--domain BASE] [--print] | Run Caddy for your apps, redirect ports 443 and 80 to it and trust its certificates, so apps are at https://<app>.localhost (or under BASE). Prints each step first; the privileged ones run through sudo. --print shows the plan and runs nothing. macOS and Linux only: on Windows it refuses and changes nothing. See Setup. | v1 |
hallway teardown [--uninstall-packages] [--print] | Undo setup and go back to http://localhost:<port> links. --uninstall-packages also uninstalls Homebrew’s Caddy and dnsmasq. | v1 |
| Command | Description | |
|---|
hallway guide [--snippet] | Print the agent guide (AGENT-GUIDE.md), or just the paragraph for an agent instruction file (CLAUDE.md, AGENTS.md). | v0 |
hallway mcp | An MCP server on stdio: a bridge that forwards every message to the running daemon’s /mcp, found on config.yaml’s port. Exits 1 with a message if the daemon isn’t running. See MCP server. | v2 |
hallway hook check-command | A pre-tool-use hook (Claude Code’s PreToolUse on Bash): reads the payload on stdin and denies a bare dev-server start, suggesting the hallway run for it. See The dev-server hook. | v2 |
| Command | Description | |
|---|
hallway thumbs enable | Screenshots of your apps on their doors: installs a browser (Chromium’s headless shell, about 300 MB) into the data home, never anywhere else, and sets thumbnails.mode: screenshot. Healthy apps get a picture within a minute. | v2 |
hallway thumbs disable | Turn them off: sets thumbnails.mode: favicon and deletes the browser and the screenshots. | v2 |
hallway thumbs refresh [slug] | Take new screenshots now, of one app or every healthy one. Needs the daemon, which does the shooting. | v2 |
hallway thumbs status | The mode, whether a browser is installed and how big it is, and how many screenshots there are. | v2 |
See Thumbnails.
| Command | Description | |
|---|
hallway doctor [--json] | Check the daemon, the data home, the services and fronted mode, with suggested fixes. Read-only. See doctor. | v0; fronted-mode checks v1 |
Environment variables are on their own page.
