Getting Started

Install Runyard from the Mac App Store, open it for the first time, and edit your config.

1. Install from the Mac App Store

Runyard is distributed through the Mac App Store. Open the App Store, search for Runyard, and click Get (or Install). macOS handles everything — no terminal commands, no security prompts to dismiss.

Once installed, Runyard appears in your Applications folder.

2. Launch Runyard

Open Runyard from Launchpad or Spotlight. It doesn't show a window or a Dock icon — instead, look for the Runyard icon in your menu bar (top-right of the screen). Click it to open the menu.

The first time you launch, Runyard creates a sample config so you can see how the menu is organized. Three example tools appear:

My App — a service with a Backend + Frontend pair of processes, plus actions like "Open Frontend" and "Clear Cache."
Quick Links — a shortcut with a few external URLs (Grafana, Jira, docs).
My Stack — a group that nests a service, a reverse proxy, and a set of quick links under a single submenu.

These are stubs — they run echo commands just to demonstrate the UI. Replace them with your real projects in the next step.

3. Where the config file lives

By default, Runyard reads from:

~/Library/Application Support/Runyard/config.json

You can open it directly from the menu: Runyard → Edit Configuration. That command opens config.json in your default editor for .json files.

You can also move the file to a different directory (for example, a synced folder) — see Syncing Across Macs.

4. Replace the sample with your own project

You can edit your tools two ways:

Settings → Tools — a guided form with a sidebar list, type picker, and per-field validation. Saves write directly to config.json. See the Settings Window guide.
Edit config.json directly — better for diffing, copy-pasting between machines, or version control.

The rest of this section uses the JSON path. Open config.json and replace the first tool with one that points at a real project on your Mac. A minimal working example:

{
  "paths": ["/opt/homebrew/bin"],
  "tools": [
    {
      "name": "My Project",
      "directory": "~/Code/my-project",
      "startCommands": [
        {
          "label": "Dev Server",
          "command": "npm",
          "args": ["run", "dev"],
          "startupFallbackPort": 3000
        }
      ],
      "actions": [
        { "label": "Open in Browser", "url": "http://localhost:{{port}}/" }
      ]
    }
  ]
}

What each piece does

paths — directories prepended to PATH before running commands. Add /opt/homebrew/bin if you installed tools via Homebrew; add your Node.js bin directory (e.g., ~/.nvm/versions/node/v22.0.0/bin) so npm and node resolve correctly.
directory — the folder to run commands from. ~ is expanded automatically.
startCommands — the process(es) to spawn. Each one has a label, a command, and optional args.
startupFallbackPort — used if Runyard can't auto-detect the listening port.
actions — extra menu items, like opening a URL in the browser. {{port}} is replaced with the detected port at runtime.

5. Reload the config

After editing, click the Runyard menu and choose Reload Configuration. Your new tool appears immediately. If the config has a syntax error, Runyard shows an alert pointing to the line.

6. Start your first tool

Click the menu item for your tool and hit Start. Runyard:

Runs npm install automatically if node_modules/ is missing.
Spawns each startCommand in order, respecting any waitFor dependencies.
Detects the port the process is listening on and shows it next to the tool name (e.g., "My Project • :3000").
Polls the health check URL (or skips to "running" if none is configured).

A green dot next to the tool name means it's healthy. Click Open in Browser (or whatever action you added) to jump straight into your app.

What next

Menu Bar Guide — the three tool types (service, shortcut, group) and every action type.
config.json Reference — the full list of fields.
Troubleshooting — where logs live, how to recover from a broken config, and how to force a specific language.

User Guide