Settings

The Settings panel is accessible from the sidebar. It controls app-wide preferences, infrastructure, and system integration.

General

TLD

Choose the top-level domain for local routing:

• .test (recommended) — IANA-reserved for testing, no conflicts
• .localhost — also safe, supported on modern browsers
• Custom — enter any TLD you prefer

Auto-Start on Launch

When enabled, opening Corral (or running corral up) will automatically start infrastructure and all projects flagged with auto-start.

CLI

Shows whether the corral CLI is available on your PATH:

• Green checkmark — CLI is in PATH and ready to use
• “Not in PATH” — the symlink is missing; click “Add to PATH” to create it

Launch at Login

Toggle whether Corral starts automatically when you log in to macOS. Uses the system login items feature.

Default Node.js Version

Select the app-wide default Node.js version from installed versions. This is used when no project-specific version is configured. See Node.js Management for the full resolution chain.

Default Package Manager

Select the preferred package manager for corral pm (and the cpm shim). This is used when no lockfile is detected in the project directory. Options: npm, yarn, pnpm, bun. When not set, defaults to npm.

Port Range Start

The first port in the allocation pool. Corral assigns ports sequentially from this number, with a pool of 100 ports. Default: 8787.

Log Display

These preferences control how logs appear in the log viewer. They are persisted in the settings file and shared across sessions.

Font Size

The monospaced font size used in the log viewer. Adjustable with Cmd+Plus (increase), Cmd+Minus (decrease), and Cmd+0 (reset to default). Default: 11.

Word Wrap

When enabled, long log lines wrap to the next line (indented to the message column). When disabled, the log view scrolls horizontally. Toggle from the More options menu (ellipsis icon) in the log toolbar. Default: on.

Log Retention

Configure how much log data Corral keeps on disk per unit. Options:

• Per-unit size limit — default 10 MB. When a unit’s log file exceeds this limit, older entries are evicted automatically.
• Global retention duration — default 7 days. Log entries older than this threshold are evicted during daemon startup and periodic cleanup.

Failure snapshots (captured at failure time) are subject to a separate cap: 50 snapshots per unit, FIFO eviction.

Notifications

Corral posts a macOS notification when something needs your attention while the app is in the background — a failure, a tunnel link, an available update, or a lost daemon. Events that happen while Corral is frontmost surface in-app instead, so banners never duplicate what’s already on screen.

Enable notifications is the master toggle. When off, no new banners are posted and any already-delivered banner is removed. Suppression happens in the app before the OS authorization prompt, so it’s independent of the system-level permission.

Notify me about

Five per-category toggles, on by default, each AND-ed under the master toggle. Turning one off stops new banners from that source but still auto-removes ones already delivered.

• Failures — a project or service crashes. The banner offers Retry, failure-specific fixes (Edit port, Revert to last working config, Reinstall helper, …), and Snooze 15m (re-fires in 15 minutes, cancelled automatically if the unit recovers first).
• Sharing — a tunnel link is ready to copy. Actions: Copy link, Open in browser, Stop sharing.
• Updates — a new Corral version is available. Actions: Restart now, Later.
• Daemon stopped — Corral’s background services stop unexpectedly. Actions: Restart daemon, Quit Corral.
• Actions — a link from another app (a corral:// deep link) starts or stops a project. The banner confirms what happened; for a stop it offers Undo.

Play sound plays the default notification sound with each banner.

If macOS notification permission hasn’t been granted, the section shows the current status with an Open Notifications shortcut to System Settings.

Preferred Browser

Choose which browser opens when you click project URLs in Corral (localhost links, .test domains, menu bar, and project commands). Defaults to your system default browser.

The picker automatically discovers all installed browsers on your Mac and displays them with their app icon. If the selected browser is later uninstalled, Corral falls back to the system default.

This setting only applies to local development URLs. Git repository links (e.g., “Open on GitHub”) always open in the system default browser.

Preferred Editor

Choose which editor opens when you run Open in Editor (⇧⌘O) on a project — it opens the project’s root folder. The picker automatically discovers installed editors (VS Code, Cursor, the JetBrains family, Sublime Text, BBEdit, TextMate, and more) and displays them with their app icon.

macOS has no system “default editor”, so if you haven’t chosen one, the first Open in Editor prompts you to pick — and remembers your choice as the app-wide default. Each project can override this in its Settings tab.

Preferred Terminal

Choose which terminal opens when you run Open in Terminal (⌃⌘O) on a project — it opens a new window or tab with the working directory set to the project root. The picker automatically discovers installed terminals (Terminal.app, iTerm2, Ghostty, WezTerm, kitty, Alacritty).

If you haven’t chosen one, Corral falls back to Terminal.app (always present), so the command always works. Each project can override this in its Settings tab.

Infrastructure

DNS (dnsmasq)

Shows the current state of the DNS service:

• Status indicator — colored circle (green for running, gray for stopped, etc.)
• Start/Stop button — control the service independently

Proxy (Caddy)

Shows the current state of the reverse proxy:

• Status indicator and Start/Stop button — same as DNS above

Resolver

Displays the path to the macOS resolver file (/etc/resolver/{tld}) with:

• Checkmark if the file exists
• Warning if it’s missing (infrastructure may not be started, or the helper may not be installed)

Background Service

The privileged helper daemon status:

State	Meaning
Green “Installed”	Helper is ready and operational
Yellow “Needs approval”	Helper was registered but the user hasn’t approved it in System Settings
Gray “Not installed”	Helper hasn’t been set up

Actions:

• Ping (when installed) — verifies the helper is reachable
• Install — registers the helper (triggers a system authorization prompt)
• Uninstall — removes the helper

Network & Security

HTTPS for Local Domains

Toggle whether Corral serves your local .test domains over HTTPS. When on, Caddy terminates TLS using Corral’s own locally-trusted root certificate. See Domain Routing for how local HTTPS works.

CA Certificate

Shows whether Corral’s local root CA — the certificate that lets browsers accept your https://*.test URLs without warnings — is trusted in your macOS keychain:

• Trusted in macOS Keychain — ready; local HTTPS works.
• Not trusted — a Trust button installs it (a one-time macOS authorization prompt). Shown once the proxy is running.
• Start proxy to generate certificate — the certificate doesn’t exist yet; start the proxy first.

Corporate Proxy Support

Many corporate networks run a TLS-intercepting proxy that re-signs HTTPS traffic with a private root CA. macOS trusts that CA, but Node.js ships its own certificate bundle and ignores the keychain — so npm install, wrangler dev, and other Node tooling fail with SELF_SIGNED_CERT_IN_CHAIN.

When Corporate proxy support is on (the default), Corral automatically detects the corporate roots your Mac already trusts and makes the Node processes it spawns — and its own downloads — trust them too. It’s a complete no-op on a machine with no corporate CAs.

• Corporate certificates — a status row showing how many corporate roots were detected (None detected / 1 certificate detected / N certificates detected); hover to see their names. A Re-scan button re-reads the trust store on demand — handy after IT installs a new root.

Turn the toggle off to skip detection entirely. See Node.js Management → Corporate proxies for the full story and the errors it fixes.

AI Tools

Connect AI coding assistants to Corral’s MCP server so they can see and drive your local environment. This pane lists every AI client Corral knows how to configure — Claude Code, Cursor, VS Code, Codex, Continue, Zed, and Windsurf — that’s detected on your Mac, with its current configuration status:

Status	Meaning
Configured	Corral’s MCP entry is present and points at the right binary
Not configured	No Corral entry yet — click to add it
Mismatched	An entry exists but points elsewhere (e.g. a stale path); re-add to fix
Unparseable	The client’s config file couldn’t be parsed, so Corral won’t touch it

Add or remove the entry per client with one click, and use the test-connection action to confirm the daemon is reachable through the path the client would use. This is the GUI equivalent of corral mcp install / uninstall / status, and the same step is offered during first-run setup.

See AI Tools (MCP) for the full guide.

Automations

Corral’s project and service actions are available in the Shortcuts app, Spotlight, and Siri — start, stop, share, or open a project without opening Corral. Type a project’s name in Spotlight, or say “Start a Corral project.”

This pane lists the ready-made shortcuts that ship with Corral, with a button to open the Shortcuts app where you can run them or build your own. There’s no on/off switch — macOS decides when to surface Corral’s actions.

Managing services from a Shortcut requires Corral Pro. See Spotlight, Shortcuts & Siri for the full guide.

About

• Wrangler version — the pinned version Corral ships with (currently 3.114.1)
• Data directory — path to the Corral data directory (~/.corral)

License activation and Pro status live in the dedicated Subscription room.