Settings Window

Open the Settings window from the menu bar dropdown — Runyard → Settings… — or with the standard ⌘, shortcut while Runyard is active. The window has four tabs: General, Tools, Advanced, and About.

Most options here mirror fields in config.json. A few don't — global keyboard shortcut, menu bar status text, and config file location are stored per-Mac in UserDefaults.

General tab

Launch at login

Runyard registers itself with macOS so it starts automatically on login. The toggle calls SMAppService directly — there is no launchAtLogin field in config.json. macOS shows the same entry under System Settings → General → Login Items & Extensions.

Global keyboard shortcut

Bind a system-wide hotkey that opens the Runyard menu from anywhere. Pressing the shortcut a second time closes the menu.

To record one:

1. Click the shortcut field in Settings → General → Shortcut.
2. A popover appears. Hold any combination of ⌃ ⌥ ⇧ ⌘ plus a non-modifier key.
3. The shortcut saves immediately and the popover closes. Press Esc to cancel without changing it.

If the combination is already taken by macOS (e.g., ⌘Space for Spotlight), Runyard rejects it and shows an error in the popover. Pick another combination.

To clear the shortcut, click the field and press Esc, or use a different combination.

Menu bar

Show status text

When enabled, Runyard appends a short summary to its menu bar icon:

• While at least one service is starting: the starting format with the {names} token replaced (e.g., Starting Backend, Frontend…). Three or more starting tools collapse to First +N.
• While services are running and none are starting: the running format with the {count} token replaced (e.g., 2 running).
• When idle: the icon shows on its own.

The two format strings are editable. Click the pencil button next to a field to unlock it, edit, then click the checkmark to confirm. A warning appears if you remove the required token ({names} for starting, {count} for running).

Failing-probe indicator

Independent of the status text, a small red ⚠︎ triangle appears next to the Runyard icon whenever any probe is in the failing state. It clears as soon as the probe recovers. See Health Checks.

Tooltip

Hovering the Runyard icon shows a dynamic tooltip listing every active service with its detected port and a state glyph (●, ◐, ✕). Stopped tools and shortcuts are omitted.

Paths

The same list as the top-level paths array in config.json. Add directories that should be prepended to PATH for every command Runyard spawns. Use the + to add, the − to remove (with a confirmation popover).

Files

Config file

Shows the current path to config.json (with ~ and iCloud Drive abbreviated). When using a custom location, a blue Custom Location badge appears.

• Open in Editor — opens the file in the system default editor for .json.
• Reveal in Finder — selects the file in Finder.
• Change Location… — pick a different directory; Runyard moves config.json there. If the destination already has a config.json, you can use that file as-is or replace it with your current one.
• Reset to Default — only shown when in a custom location. Copies config.json back to ~/Library/Application Support/Runyard/. The synced copy is not deleted.

See Troubleshooting → Syncing Across Macs for the recommended workflow.

Log directory

Shows the read-only path to ~/Library/Logs/Runyard/. The Open in Finder button reveals the folder.

Reload Configuration

Re-parses config.json and rebuilds the menu. Running tools are stopped first. Equivalent to the Reload Configuration menu item.

Tools tab — visual editor

A guided alternative to hand-editing config.json. Saves are written straight to the same file, so the JSON view and this editor stay in sync.

When you save changes, Runyard reloads the configuration in the background — services may briefly stop and restart if their definitions changed.

Sidebar

A list of every top-level tool. Each row has a small badge indicating the type:

• Drag rows to reorder them. Order changes save immediately and don't restart any processes.
• Right-click a row for a quick Delete menu.
• The + button at the bottom opens an "Add" menu — pick Service, Shortcut, Group, or Health Check to insert a new tool with sensible defaults.
• The − button deletes the selected tool (with a confirmation popover).

Detail pane

Editing a tool fills out a form whose sections appear conditionally based on the tool's type:

Identity

• Name — required.
• Type — Service / Shortcut / Group / Health Check. Switching between types that contain incompatible data (e.g., a Service with start commands switching to a Shortcut) shows a confirmation alert; confirming clears the abandoned fields.

Directory (service only)

The project root. ~ is expanded. Commands run from here unless a process overrides it via workingDir.

Options (service only)

• Auto-start — start this service when Runyard launches. Toggling this only changes what happens the next time Runyard launches; it does not start or stop the service right now. Use the Start/Stop buttons in the menu for that.
• Keep menu open — Start/Stop clicks won't dismiss the menu, so you can watch state transitions live.

Start commands / Stop commands (service only)

Process list editor. Each entry is collapsible and shows fields for command, arguments, working directory, startup check URL, fallback port, request timeout, and waitFor. Use the up/down chevrons on each row to reorder, or the trash icon to delete. Stop commands ignore the startup-check fields.

Health check (probe only)

• Auto-start polling — defaults to on. Toggling this only changes what happens the next time Runyard launches; it does not pause or resume the probe right now. Use the pause/play icon on the probe's menu row for that.
• Interval (seconds, minimum 5) and Failure threshold (1 or higher).
• Form — segmented control for HTTP / TCP.
• HTTP: URL, expected status codes entered as removable chips (one or more, validated to 100–599), an optional body contains substring, and a request timeout.
• TCP: host, port, and connect timeout.

Actions (service / shortcut / group)

A collapsible list of actions. Click a row to expand it and pick one of: Open URL, Run command, Reveal in Finder, AppleScript (inline), AppleScript file, or Health check. Use the chevrons to reorder, the red minus to delete.

showWhen is exposed for service-tool actions only — Always / Running / Stopped.

keepMenuOpen is a per-action toggle.

Nested tools (group only)

Add Service, Shortcut, or Health Check entries that live inside the group's submenu. Each nested tool expands inline into a sub-form identical to the top-level one. Groups themselves cannot be nested.

Install command (service only)

Toggle on to add a one-shot install (e.g., npm install). Fields: command, arguments, marker path. The install runs once before the first start whenever the marker path is missing.

Paths (service only)

Per-tool path entries that merge with the global paths list. The Replace global paths toggle (visible only when at least one entry is present) sets pathsOverride: true.

Save / Revert

The footer bar shows two buttons whenever you have unsaved changes:

• Revert — discard edits and reload from disk.
• Save (⌘S) — validate, write to config.json, and reload the registry.

If validation fails, the error message appears on the left of the footer.

Advanced tab

Tunes the timing of process startup, shutdown, and install. All values are optional in config.json (the advanced block); leaving them at their defaults stores nothing.

Each row has a number field, a stepper, and a hint line showing the default, minimum, and maximum. Out-of-range values show an orange warning and are clamped on save. Edits auto-save 300 ms after you stop typing.

Service startup

Processes

Reset to defaults

Restores every field to its default and removes the advanced block from config.json.

About tab

Shows the Runyard icon, version, and copyright.

• Visit Website — opens the Runyard website.
• Send Feedback — opens an alert with two options:
  • A checkbox Include config.json (on by default). Your config.json is attached to the email so we can reproduce issues.
  • The alert composes a new message using your default mail client (or copies the body to the clipboard if no compatible client is configured), pre-filled with the recipient, subject (Runyard <version> feedback), and a body containing your macOS and Runyard version info.
  • If your default mail client can't accept attachments through the standard share service, a warning shows the file path so you can attach it manually.