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 — every registered project shows its 18pt brand mark (auto-detected favicon, manifest icon, or initials avatar) with a small corner status pip carrying the run state. Hovering a row reveals two icon buttons at the right edge: ↗ open in browser (when running) and a state-aware Start / Stop / Restart icon. Right-click for the full context menu (see below).
• Services — installed services with an 8pt status dot, the service name, and a mono version pill (e.g. 16.4). Hovering a row reveals the same right-edge action pair as project rows. Hover the section header to reveal a Browse button that opens the service catalog. Learn more →
• Tools — Logs, Node.js, and Settings panels

Status pip colors (project rows):

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

Status dot colors (service rows): same color mapping as the table above; service rows keep the smaller 8pt dot rather than a brand mark + pip.

Right-click context menus

Project tiles, project sidebar rows, service tiles, and service sidebar rows all share the same context menu component per surface — right-clicking a project on the home tile yields the same menu as right-clicking it in the sidebar.

Project menu (in look-at → do → modify → reveal → destroy order):

• Open in Browser · Open in Editor (disabled placeholder) · Open in Finder · Copy URL
• Restart · Stop (or Start when stopped) · Share via Tunnel…
• View Logs · Project Settings…
• Open on GitHub (when a git remote is detected; host name varies by remote)
• Remove…

Service menu:

• Open Web UI · Copy Connection String
• Restart · Stop (or Start when stopped)
• Set as CLI default
• Reveal Data Directory · View Service Logs

State-aware behavior: running rows show Restart + Stop; stopped rows show Start; errored rows show Restart (treated as "try again"). Slots like Open in Browser stay visible-but-disabled when the project is stopped, so you learn their position.

Keyboard shortcuts dispatch through app-level Project and Service command menus on the selected row, not from the right-click menu directly. This means a key press always acts on the row you've selected (the canonical Apple pattern), never on whichever row the responder chain happens to resolve first. The trade-off: SwiftUI's right-aligned shortcut hint next to context-menu items is intentionally absent — discover shortcuts from the menu bar instead.

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.