Sections

User Guide

Menu Bar Guide

How each tool type renders in the Runyard popover, and what every action does.

Runyard's entire UI lives in the menu bar. Click the icon to open the popover; press Escape or click outside it to dismiss.

The Runyard icon

Left-click the icon to toggle the popover. Alongside the icon you may see, depending on your settings:

The status text is frozen while the popover is open. It refreshes once you close the popover. (Touching the title would resize the menu-bar button and visually disconnect the open popover from the icon, so the refresh is deferred.)

Popover layout

The popover is a fixed-width column with four sections:

The four tool types

Service

A service is a managed process: a backend, a dev server, a Docker stack. It renders as a card with:

When the card is collapsed, the header compresses to dot · name · port · pill so you can see the gist at a glance.

Shortcut

A shortcut is a flat list of links or actions under an uppercase section label. No process management. Each action renders as a full-width tile in a vertical stack, regardless of action type (URL, command, AppleScript, reveal, or health check). Top-level shortcut cards have their own chevron and participate in the Collapse all / Expand all toggle. Shortcuts nested inside a group render flat without a chevron; collapse the parent group instead.

{
  "name": "Quick Links",
  "type": "shortcut",
  "actions": [
    { "label": "Open Grafana", "type": "url", "url": "https://grafana.example.com" },
    { "label": "Open Jira", "type": "url", "url": "https://jira.example.com" }
  ]
}

Group

A group bundles related tools under one collapsible card. The header shows an aggregate status pill that adapts to the group's contents:

Below the header, each child renders as a single compact row to keep groups dense:

●  Service Name        :8080  [PILL]   ⏹  📄
●  Health Check Name   124 ms [PILL]   ⏸  ↻  📄

Layout per child:

A second chip row appears below the compact row only when the service has visible config-defined actions (gated by showWhen) and/or is in .error state. Errored services get a red Clear Error chip at the end of the second row.

Right-click any compact row to get a full text menu with all actions plus extras: Reveal Directory in Finder, Copy Start Command (services), Copy Endpoint URL (health checks).

Group-level actions live in a card footer under an uppercase ACTIONS section title. The buttons render as a 2-column grid (single actions span the full width; an odd third action gets its own full-width row). The first URL action gets the primary blue accent, and healthCheck actions render with their own inline status. Clear Errors (N) appears as a red full-width row at the bottom when ≥ 2 nested services are errored or have cached health-check failures.

Tip: nested health checks don't render the 20-bar latency sparkline (it would balloon group height). If you want the sparkline plus the full card UI, promote the health check to top-level in config.json (move it out of the parent group's tools array).

{
  "name": "QA Stack",
  "type": "group",
  "actions": [
    { "label": "Open Dashboard", "type": "url", "url": "https://qa.example.com" }
  ],
  "tools": [
    { "name": "API Server", "type": "service", "...": "..." },
    { "name": "Links", "type": "shortcut", "...": "..." },
    { "name": "Health", "type": "healthCheck", "http": { "url": "..." } }
  ]
}

Groups cannot be nested inside other groups.

Health check

A health check polls an HTTP or TCP endpoint on a fixed interval and renders as its own card with:

Health checks nested inside groups render as compact rows (no sparkline). Promote one to top-level if you want the sparkline + full card UI.

Pause and Resume are runtime-only controls: they do not modify your config.json. On next launch the probe respects the Auto-start on launch setting from Settings → Tools.

When any health check is failing, a red ⚠︎ triangle appears next to the Runyard menu bar icon.

Response time stats

Hover any health-check tile to see response-time statistics from a rolling 1-hour window of recent checks. On a collapsed healthy tile hover the sparkline; on a failing, paused, or expanded tile hover the status pill. The window is fixed (not configurable) and resets when Runyard quits.

With fewer than 5 successful checks, the popover shows the latest latency on its own with a "Need N more checks…" countdown. Tail and average estimates need at least 5 samples to be meaningful.

With 5 or more successful checks, the popover shows a four-metric breakdown:

The Slow tail, Average, and Failure rate rows each show a brief italic explanation underneath.

When a check is failing or paused, the popover swaps to the most relevant info for that state (last error, time since last success, and the consecutive-failure count when failing; the last-known stats dimmed when paused).

Actions

Actions are extra menu items per tool. Each action has a label and exactly one type:

Type Field What it does
Open URL url Opens the URL in your default browser. Supports {{port}} placeholders.
Run command command + args Runs a shell command (in the tool's directory by default). Output goes to an action log.
Reveal in Finder reveal Opens a folder in Finder. Relative paths resolve from the tool's directory.
Inline AppleScript applescript Executes an AppleScript snippet.
AppleScript file applescriptFile Runs a .applescript file.
Health check healthCheck Runs a one-shot HTTP or TCP check and shows the result inline (latency on success, "failed" on failure). See config.json Reference → Health Checks.

Port placeholders in URLs

Action URLs can include {{port}} and {{port:Label}} placeholders:

{ "label": "Open Frontend", "type": "url", "url": "http://localhost:{{port}}/" }
{ "label": "API Docs", "type": "url", "url": "http://localhost:{{port:Backend}}/swagger" }

If the tool isn't running (no port detected yet), the placeholder stays literal and the link won't open.

Controlling when actions appear

For service tools, actions have a showWhen field:

showWhen is ignored on shortcut and group actions; those are always visible.

Per-card collapse

Each card has a chevron in the top-right that collapses its body. The collapsed state persists across popover reopens and app restarts (stored in ~/Library/Preferences/ca.bonevil.runyard.plist under the collapsed.{toolName} keys). The header Collapse all / Expand all toggle overwrites every card's stored state in one click.

Port detection

Runyard uses lsof to watch the PID tree of each process you spawn and picks up the first TCP port it starts listening on. The detected port:

  1. Shows up next to the tool name as a blue :3001 tag on the meta-line.
  2. Gets auto-injected into startupCheck URLs that don't include an explicit port (e.g., http://localhost/api/health becomes http://localhost:3001/api/health).
  3. Replaces {{port}} placeholders in action URLs.

Fallback: if auto-detection doesn't find a port (rare, but some tools fork in unusual ways), set startupFallbackPort on the process.

Start, Stop, and Logs

Start

The Start button runs:

  1. installCommand if the marker path (default: node_modules) doesn't exist.
  2. Each startCommand in order. Commands with waitFor: "OtherLabel" pause until the other process passes its health check.
  3. Health check polling (if configured).

The tool transitions through starting → running once all processes are healthy.

Stop

The Stop button either:

View Logs

Every spawned process writes to its own log file under ~/Library/Logs/Runyard/. View Logs opens each log file in Console.app (or falls back to the directory if no log files exist yet). See Troubleshooting → Logs for the full path scheme.

Clearing errors

When a service fails to start or crashes, the card turns red and the menu bar icon shows a red warning triangle. The error message is shown inline below the meta-line, and the full reason is written to the tool's log file.

To dismiss the error indicator without restarting:

Clearing only changes what's displayed; your log files are kept on disk at ~/Library/Logs/Runyard/.

Keep Awake

Runyard ships caffeinate integration to prevent macOS from sleeping while important work is running. Three independent paths, any combination of which can be active at the same time:

When at least one source is active and no manual session is running, the toggle row swaps to a green active wash and reads Auto · (or Auto · <Name> +N for multiple). When manual and automatic sources are active together, the manual countdown wins the headline and the +N chip indicates additional automatic sources; hover the row to see the full list.

The menu-bar hover panel echoes the same summary as a ☕ 45 min · Auto · Big Build +2 line under the running/failing counts.

Lid-closed limitation: macOS does not keep your Mac awake when the lid is closed, regardless of which sleep-prevention tool you use. Runyard shows a one-time alert the first time you toggle Keep Awake on, to set the expectation correctly. This is a thermal-safety constraint and applies to any caffeinate-based tool.

The four tiles at the bottom of the popover: