macOS App Overview

Corral's macOS app is a native application that lives in your menu bar. It provides a visual interface for managing all your projects, Node.js installations, and infrastructure.

App Behavior

• Menu bar app — Corral lives in the system menu bar. There's no persistent dock icon.
• On-demand window — the main window opens when you click "Open Corral" or use Cmd+O. A dock icon appears while the window is visible.
• Background daemon — the app communicates with a background daemon process that manages all running projects. The daemon starts automatically when the app launches. This means the CLI and app always share the same state.
• Stays running — closing the main window doesn't quit the app. Your projects continue running.
• Quit behavior — by default, quitting the app (Cmd+Q or "Quit Corral") stops all projects and infrastructure. You can change this in Settings to keep projects or infrastructure running after quit.
• Auto-refresh — the app polls the daemon for state updates every 2 seconds, so the UI stays current with process changes.
• CLI symlink — on first launch from /Applications, the app creates a symlink at /usr/local/bin/corral (or ~/.corral/bin/corral as a fallback) so the CLI is immediately available in your terminal.

Menu Bar

Status Icon

The menu bar icon indicates the overall state of your projects:

Icon	Meaning
Gray cloud	All projects stopped
Green cloud	One or more projects running
Red cloud	A project has errored

Popover (Left-Click)

Click the menu bar icon to open a popover with quick actions:

• Running count in the header
• Project list with status dots, port numbers, and start/stop buttons
• Click a running project's name to open it in your browser
• Start All / Stop All buttons
• Open Corral... (Cmd+O) to open the main window
• Quit Corral (Cmd+Q)

Context Menu (Right-Click)

Right-click the menu bar icon for a context menu with:

• Per-project submenus (open in browser, start, stop, restart)
• Status indicators per project
• Start All / Stop All
• Open Corral / Quit

Main Window

The main window uses a sidebar-and-detail layout.

Sidebar

• Projects — all registered projects, each with a colored status dot. Right-click a project for a context menu with start, stop, open on GitHub/GitLab/etc. (when a git remote is detected), and remove actions.
• Tools — Logs, Node.js, and Settings panels

Status dot colors:

Color	State
Green	Running
Yellow	Starting or stopping
Red	Errored
Gray	Stopped

Drag and Drop

Drag a project folder from Finder onto the main window to register it. A frosted-glass overlay with a drop zone indicator appears while dragging. On drop, the project is registered and automatically selected in the sidebar.

Toolbar

The toolbar shows contextual actions based on your selection:

• Add Project (+) — register a new project by selecting its folder
• Project selected: Start/Stop and Restart buttons (adapts to current state)
• Node.js Manager: "Install New Version..." and "Install to System..." buttons

First-Launch Setup

On first launch, Corral shows a setup wizard that explains domain routing and prompts you to install the privileged helper. This enables .test domain resolution and HTTPS.

You can skip the setup and install the helper later from Settings.