Sections

User Guide

Getting Started

Install Runyard, point it at your first project, and watch your dev environment come to life from the menu bar.

1. Install Runyard

Runyard ships as a signed, notarized DMG, so macOS Gatekeeper lets it open on first launch without complaint. Download the latest release from the Runyard releases page, open the .dmg, and drag Runyard.app into your Applications folder.

After that first install, future updates are delivered through the in-app Check for Updates button. You only need to download the DMG once.

2. Launch Runyard

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

The first time you open the popover, Runyard greets you with a welcome card. Your config is empty by default, so you choose how to fill it:

The welcome card disappears once your config has at least one tool. To get it back, delete every tool from Settings → Tools (or empty the tools array in config.json).

If you tap Load example tools, four entries appear:

The service entries run echo commands. Replace them with your real projects in the next step. The health checks work as-is and are useful for keeping an eye on any HTTP or TCP endpoint you don't manage as a process.

3. Where the config file lives

By default, Runyard reads from:

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

You can open it directly from the popover footer: click Settings, switch to the General tab, and use Files → Open in Editor. That 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:

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",
      "type": "service",
      "directory": "~/Code/my-project",
      "startCommands": [
        {
          "label": "Dev Server",
          "command": "npm",
          "args": ["run", "dev"],
          "startupFallbackPort": 3000
        }
      ],
      "actions": [
        { "label": "Open in Browser", "type": "url", "url": "http://localhost:{{port}}/" }
      ]
    }
  ]
}

What each piece does

5. Reload the config

After editing, open the popover and click the Reload tile in the footer. Your new tool appears immediately. If the config has a syntax error, Runyard shows an alert pointing to the line (with an Edit Configuration button that reopens the file).

6. Start your first tool

Open the popover, find your tool's card, and click Start at the bottom of the card. Runyard:

  1. Runs npm install automatically if node_modules/ is missing.
  2. Spawns each startCommand in order, respecting any waitFor dependencies.
  3. Detects the port the process is listening on and shows it as a blue :3000 tag on the card's meta-line.
  4. Polls the health check URL (or transitions straight to Running if none is configured).

The card's status pill turns green and reads Running once everything is healthy. Click your Open in Browser chip (or whatever action you added) to jump straight into your app.

What next