Ten commands, and a way back.
Roost is run with one command-line tool, roostctl, and two plain endpoints. Nothing in it needs a screen, and nothing in it is a one-way door.
The commands
| Command | What it does |
|---|---|
| init | Reads the stdio server entries from the clients' MCP configs and writes them into Roost's own config file, then prints the replacement URL entries. |
| status | One row per server: mode, process ID, memory, warm or cold, last use, calls, spawns, median latency, tool count, and the last restart with its reason. |
| top | The same table, redrawn every few seconds. The interval is a flag. |
| refresh | Re-reads each server's catalog. A cold server is started to be listed. A warm server whose watched files changed is restarted first, and the output says so. |
| restart | Stops and starts one server's child. |
| reload | Applies edits to the config file to the running daemon: servers added, removed, or changed. |
| verify | The parity gate. Starts each server directly, then compares its tool names and schemas with what Roost serves. |
| flip | Points the clients' MCP configs at Roost's URLs, after saving a backup of each. |
| revert | Restores the clients' original configs from the latest backup. |
| doctor | One line per health check. Exits non-zero on any hard failure. |
Switching over safely
The rule is simple: never point clients at a hub that has not proven it serves the same tools.
Verify
roostctl verify must pass for every configured server. A failure names the half that failed, the direct start or Roost, and the innermost error rather than a wrapped task-group message.
Flip
roostctl flip saves a backup of each client config and then swaps the entries for Roost's URLs. Clients are changed through their own command-line tool, never by hand-editing their files.
Keep going
Open sessions keep their own servers and are not affected. New sessions read the new configuration.
Revert if needed
roostctl revert puts the old direct-start configs back, in seconds, from the saved backup.
Health and status
- /healthz answers whether the daemon is healthy, and returns a failure with a reason when it is not.
- /status reports each server's state, memory, last use, idle time, calls, in-flight requests, spawns, restarts, median latency, tool count, and catalog age.
- /admin/refresh, /admin/restart, and /admin/reload do the work behind the matching commands. They answer on the loopback interface only.
- Every spawn, stop, refresh, and breaker change writes an INFO line to a JSON-lines log, and each child's error output is kept in its own file.
What doctor checks
- The config file parses and its names are valid.
- The port is free, or the daemon on it is Roost and answers its health check.
- The launchd job is loaded.
- Catalog snapshots exist and are not stale.
- The open-file limit leaves headroom.
- The Claude command-line tool is found.
- No server's interpreter lives on a path that a package-manager upgrade would move out from under the daemon.
Who can reach it
The daemon binds the loopback interface, so nothing on the network can reach it, and the admin endpoints are loopback only. Secrets that servers need, such as API keys in their environment, live in the config file, which is kept readable by one user and is never checked in.
Questions about this tool?
Write to Renkara Media Group and a person will answer.