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 five tabs: General, Tools, Advanced, About, and Purchases.

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-health-check indicator

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

Show filled cup when Keep Awake is on

Adds a ☕ glyph to the right of the Runyard status icon while caffeinate is manually activated. It is hidden during service-triggered caffeinate. On by default.

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.

Keep Awake

Default duration

Sets the duration used when you click the Keep Awake toggle without choosing a duration. Options: 15 minutes, 30 minutes, 1 hour, 2 hours, or Until I disable it (indefinite). Defaults to 1 hour.

Also prevent display sleep when activated manually

Equivalent to caffeinate -d: keeps the display awake too, not just the system. Off by default, since it stops your screen from dimming or locking. This applies only to manual activation, not to services with keepSystemAwake.

Popover

Default state when opening

A segmented control with three choices for how cards appear when the popover opens: All expanded, All collapsed, or Last used (the default). The expanded/collapsed choices are applied the first time a tool appears; per-card collapse choices are remembered after that.

Show summary in header

When on (the default), the popover header shows the running and error counts under the Runyard label.

Reset all card collapse states

A Reset… button (with a confirmation) that clears every per-card collapse memory so all cards expand on the next open.

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. The tab is split into a sidebar on the left and an editor pane on the right (master-detail). The sidebar mirrors config.json order, with nested children indented under their parent group. The editor pane swaps its form fields based on the focused tool's type.

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

Sidebar

The sidebar lists every tool in the order it appears in config.json, with no type-based regrouping. Top-level tools are flush-left; children of a group are indented underneath with a chevron on the parent to expand or collapse them.

• Type icon identifies each tool: gear (service), antenna (health check), arrow (shortcut), folder (group).
• Search at the top of the sidebar filters as you type. Config-order is preserved, non-matching tools are hidden, and parent groups stay visible if any descendant matches. A "N tools hidden" line appears at the bottom when the filter is hiding items. Match counts ("3 matches") show next to filtered group rows.
• Right-click a row for Delete (with confirmation) and, for services, Show in Finder.
• + Add tool ▾ at the bottom of the sidebar opens a type picker (Service / Health Check / Shortcut / Group). New tools are inserted at the bottom of the list with sensible defaults and immediately selected for editing.

Type is set at creation and cannot be changed afterwards. To change a tool's type, delete it and recreate.

Editor pane

The right side is a sticky header followed by a scrolling form. The header shows the tool's name, a small uppercase type badge, and a row of action buttons:

• ? Help: opens the help menu (User Guide and config examples).
• Export (up-arrow icon): write this tool to a portable .runyard file. See Exporting & Importing Tools.
• 🗑 trash: delete the focused tool (with confirmation). Keyboard shortcut: ⌘⌫.
• Cancel: discard unsaved edits and reload from disk. If you have unsaved changes when selecting another tool, Runyard prompts before discarding.
• Save (⌘S): validate, write to config.json, and reload the registry. Disabled while validation has any errors or no changes are pending.

Inline validation is field-anchored: errors appear in red directly under the field that failed. The Save button stays disabled while any error is present.

Service editor

Sections in lifecycle order:

• Basics: Name (required), Directory (required, with Browse… picker), Auto-start on launch.
• Install Command: always visible. The first row is Enable auto-install; the command, arguments, and marker-path fields below are editable when the toggle is on and grayed out when off. Toggling off preserves your configuration (the install step is skipped at runtime instead of being deleted).
• Start Commands: collapsible list of processes. Per entry: label, command, arguments, working directory, Startup Check URL (with {{port}} placeholder), Startup Fallback Port, Startup Request Timeout, and Wait For (depends on a preceding command's label).
• Stop Commands: same shape as start commands but only the first four fields apply.
• Actions: collapsible list of action buttons. Each row picks one of: Open URL, Run command, Reveal in Finder, AppleScript (inline), AppleScript file, or Health Check. The Show When picker (Always / Running / Stopped) appears for service-level actions. The Confirm checkbox (Ask for confirmation before running) gates the action behind a confirmation alert, useful for destructive actions like killing dev servers.
• Tool-Specific Paths: additional PATH entries for this service. Override global replaces the global PATH instead of merging.

Wherever a command takes Arguments (install command, start/stop commands, and Run-command actions), the field is a list with one row per argument. Use Add Argument to append a row and the ✕ button to remove one. Each row is passed to the command as a single, literal argument — Runyard never splits a row on spaces — so a value that legitimately contains spaces (like --command=zsh -lc 'npm start') stays one argument. Enter each flag and value in its own row rather than typing a whole command line into one.

Health-check editor

• Basics: Name, Auto-start on launch.
• Endpoint: Protocol picker (HTTP / TCP). HTTP: URL, expected status codes, optional body-contains substring, request timeout. TCP: host, port, connect timeout.
• Polling: Interval (seconds, minimum 5), Failure threshold (consecutive failures before marking the health check failing).

Shortcut editor

• Basics: Name only.
• Actions: the same list editor as services. Shortcuts have no running state, so the Show When picker is hidden and showWhen is not written to JSON for shortcut actions.

Group editor

• Basics: Name only.
• Group-level Actions: actions that appear in the popover's group footer. The Show When picker is hidden here (groups have no running state).
• Nested Tools: list of child tools (Service / Shortcut / Health Check; no nested groups). Click a child's name to jump to its editor (the sidebar selection updates). The trash icon removes a child after confirmation.

Deleting tools

Three entry points all funnel through the same confirmation alert:

1. Click the trash icon in the editor header.
2. Right-click a sidebar row and pick Delete.
3. Select a row and press ⌘⌫.

After confirming, the next sibling (or the previous, if it was the last) is selected automatically. Deleting a nested child re-saves the parent group; deleting a top-level tool reloads the registry in the background.

Empty state

When the configuration has no tools, the sidebar shows an italic "No tools configured" message and the right pane shows a centered prompt with four primary CTAs (one per tool type) for quick onboarding.

Export and import

Each tool's editor has an Export button (up-arrow icon) in the top bar, and right-clicking a tool in the sidebar offers Export…. Both write a portable .runyard file. The Import Tool… control next to + Add (and double-clicking a .runyard file in Finder) opens the review-and-set-up import sheet. See Exporting & Importing Tools.

Advanced tab

Tunes the timing of process startup, shutdown, and install, plus log rotation. All advanced fields are optional in config.json, but editing any of them writes a complete advanced block back to config.json with every value populated (defaults are written out explicitly).

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

Logs

Controls log rotation and cleanup. Runyard rotates each log file when it reaches the size limit, gzips older rotations, and deletes anything past the age cap at launch.

Reset to defaults

Restores every field to its default value. It writes those defaults back into a fully populated advanced block; it does not remove the advanced block from config.json.

About tab

Shows the Runyard icon, version, and copyright, followed by a What's new section and a row of buttons.

The What's new section displays the release notes for the current version. A View all releases link opens the full release history. The notes refresh from the live update feed when the tab appears, so corrections published after a release still show up.

The button row:

• Visit Website: opens the Runyard website.
• Acknowledgements: shows the open-source acknowledgements.
• Check for Updates: runs the same update check as the popover footer's Updates tile.
• Help (dropdown): opens a menu with the User Guide and config examples.
• 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.

Purchases tab

Manages the one-time Unlimited Tools purchase and the optional tip jar. Two sections.

Unlimited Tools

The section's content depends on whether this Mac is activated.

When not activated, you see the free-tier hero card and one of two CTAs:

• The unlock button opens Dodo Payments' hosted checkout in your default browser, with the current price embedded in the label. After a successful payment, this Mac activates automatically via the runyard://activate return URL.
• I have a license key reveals a text field. Paste a key from a previous purchase and click Activate to bind it to this Mac without going through checkout again.

When activated, the section shows the masked license key, the activation date, and two actions:

• Deactivate this Mac removes the activation so the license can be used on a different Mac.
• Manage activations → opens Dodo Payments' customer portal in your browser, where you can sign in with your email to see every active Mac across every license.

Tip jar

Four tiles, side by side: ☕ Coffee, 🥪 Lunch, 🍱 Dinner, and 🍽️ Your choice (Pay What You Want). Each tile opens its own Dodo Payments checkout in your default browser. The first three are fixed amounts (shown on each tile); the fourth lets you pick the amount on Dodo's hosted page.

Once you've tipped at least once, a row of lifetime counters appears above the tiles, with one number per tile. Counters are stored in your iCloud account so they're shared across your Macs.

See Purchases for the full reference, including refunds and privacy.