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:

• “Available at …” — the CLI is installed and on your PATH, ready to use
• “Available at … — open a new terminal” — it’s installed and your shell profile is set up, but this terminal started before that happened. Open a new one; nothing needs fixing
• “Installed at … but not on PATH” — the binary is there but nothing points at it; click “Repair”
• “Not in PATH” — no CLI is installed; click “Add to PATH” to install it

Start Corral’s Services When I Log In

Registers Corral’s background service so it starts with your session: corral commands answer immediately and your projects are there without opening the app. Off means nothing comes back after a reboot until you run a corral command or open the app.

Corral will never re-enable this after you turn it off. It also appears in System Settings → General → Login Items & Extensions, where macOS lets you disable it independently.

Serve .test sites from login

Nested under the setting above, and a separate question. On, the service claims ports 80 and 443 and answers DNS for .test from login onward, so your sites work after a restart without opening Corral — the first request to a stopped project shows a progress page and starts it. Off, the service runs but claims nothing, and infrastructure waits for corral up.

Running a background process is a smaller ask than standing on two privileged ports, which is why the two are not one switch.

Show Corral in the Menu Bar at Login

Whether the app itself appears in your menu bar after you log in. Defaults on.

Turning this off means Corral is genuinely not running after you log in — your sites keep working, because they are served by Corral’s services rather than by the app, but nothing is there to show you a failure notification until you open Corral yourself. Leave it on if you want to be told when a dev server dies.

When I Quit Corral

What an ordinary Cmd+Q does: keep everything running (the default), or stop projects and infrastructure. Holding Option when quitting always offers “Quit and Stop Everything” regardless of this setting.

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

The package manager Corral falls back to when a project declares none, has no committed yarn release and no lockfile. Options: npm, yarn, pnpm, bun. When not set, Corral uses npm.

This applies everywhere the question is asked — the dev server, the Dependencies tab, corral pm and the cpm shim — not just the CLI. See Which package manager Corral uses for the full chain.

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, Open Login Items, 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 or not yet approved)

Background Service

The privileged helper daemon status:

State	Meaning
Green “Registered and approved”	Helper is ready and operational
Yellow “Needs approval”	macOS has the helper registered and is waiting for you to switch Corral on under System Settings → General → Login Items & Extensions → App Background Activity
Gray “Not installed”	Helper hasn’t been set up

Actions:

• Ping (when installed) — verifies the helper is reachable
• Install — registers the helper with SMAppService. macOS then files it as a background item for you to enable in Login Items; nothing pops up to accept, and the request cannot be re-fired, so Open Login Items… is the button that moves it from there
• 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.

Reset and Remove

Two destructive actions at the very bottom of Settings. They are separated on purpose, and the names say which is which.

Reset Corral infrastructure…

Puts the machine back to before setup: stops DNS and the proxy, removes the resolver file, untrusts the HTTPS certificate in both keychains, removes the installed corral command, and unregisters the background helper.

Corral, your projects and your data all stay. Rerun setup to restore HTTPS and .test domains. This is the action to reach for when local HTTPS or domain resolution has gone wrong and you want that part set up again.

Remove Corral completely…

Everything the reset does, plus Corral itself. A sheet lists what will go, asks you to type uninstall to confirm, and offers one choice:

Also delete my Corral data (on by default) covers ~/.corral — your projects, settings, license, installed Node.js versions and service data, with its current size shown beside the checkbox. Turn it off and all of that survives, ready for a reinstall — everything except Corral’s own shims and binaries, which are removed either way so nothing is left on your PATH pointing at an app that’s gone.

The app is moved to the Trash, not deleted, so a removal is recoverable for as long as you haven’t emptied it. Your project folders on disk are never touched.

Corral quits to finish — it can’t delete its own app bundle while it’s running. macOS asks you to authorise once, for the HTTPS certificate: clearing a trust setting needs a system authorisation prompt that nothing but a running app can present. Every other privileged step goes through the background helper Corral already has, before that helper is unregistered — so there is no sudo and no second prompt.

If something can’t be finished — most often a background helper macOS won’t unregister — Corral keeps the app rather than leaving you with orphaned system files and nothing to fix them with, reopens, and tells you what’s left.

About

• Corral version — the installed app version and its update status, with an Update button when a new build is staged
• Data directory — path to the Corral data directory (~/.corral)
• Legal and Open source — terms, privacy, and the third-party licenses

There’s no Wrangler row. Corral resolves Wrangler per project now, so there’s no single version to report app-wide — the version a project actually runs is on that project’s Wrangler card in its Overview tab.

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