Overview
Anatomy of the window
The main window is organized around four regions. Each numbered chip below points to the part documented in the sections that follow.
Diagram of the Corral macOS app window. The interactive callouts below name each region.
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 — quitting the app (Cmd+Q or “Quit Corral”) stops all projects and infrastructure and shuts down the background daemon.
- 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/corralas 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 or service has failed |
System Notifications
While Corral runs in the background, it posts macOS notifications when something needs attention: a failure (with Retry and a 15-minute Snooze), a tunnel link ready to copy, an available update, or a stopped daemon. Each banner carries the relevant one-tap actions, and tapping the body opens the app at the right place.
Choose which categories notify you — and toggle the sound — in Settings → Notifications.
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
- Stacks — the STACKS section at the top groups projects and services into runnable stacks; each row shows aggregate status and a member count, expands to reveal its members, and carries Start / Stop controls. Hover the header for a + to create one. Reads are free; running and editing stacks are Pro. Learn more →
- 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 / Retry icon (Retry appears for Failed or Abandoned units). 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. Failed services show a red pip and the Retry action. Learn more → - Tools — Logs, Node.js, Settings, Subscription, and Failure History (global view across all units) panels
Status pip colors (project rows):
| Color | State |
|---|---|
| Green | Running (Active/Ready) |
| Yellow | Starting or stopping (Active/Starting, Active/Initializing, Active/Stopping) |
| Red | Failed or Abandoned |
| Orange | Degraded health (Active/Ready but with degradation signals like DnsDown or LinkedServiceDown) |
| Gray | Stopped (Idle or Pending) |
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 · Open in Terminal · Open in Finder · Open in… (pick a specific browser/editor/terminal) · Copy URL
- Restart · Stop (or Start when stopped; Retry when failed) · Share via Tunnel…
- View Logs · View Failure History · 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”). Open in Browser stays available even when the project is stopped — it’s gated on the URL existing (like Copy URL), since a stopped project’s .test URL opens the branded dev-server-down page. Open in Editor, Open in Terminal, and Open in Finder open the project root and are likewise independent of run state (disabled only when no such app is installed).
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.
Two more surfaces carry right-click menus: binding tiles in a project’s Overview tab (Inspect, Copy Binding Name, Copy Resource ID) and log rows in any Logs view (Copy Line / Message, Open URL, Filter to Source / Severity, Star). See Binding Browsers and Logging.
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. Pro licensing — activation, status, deactivation — lives in the dedicated Subscription room.
Getting help
Hit a bug? Open Help → “Report a Problem…” to send the maintainers a description plus an optional, opt-in diagnostics bundle. It works even when the background daemon is down. See Reporting Problems for the full flow and what’s included.