Installation

Download the macOS App

Drag the latest signed build to your Applications folder. The app includes the CLI and will set it up automatically on first launch.

↓ Corral-0.11.1.dmg

System Requirements

• macOS 26 (Tahoe) or later
• Apple Silicon (arm64)

Corral supplies Wrangler when your project doesn’t bring its own, and can manage Node.js for you — no global installs of either are required.

Installing

Corral is a macOS app, and it carries the corral CLI inside it. Installing Corral installs both: the app — which registers the privileged helper — and the CLI, copied out of the bundle and onto your PATH. The app is required, not optional: it’s the only thing that can set up the helper, so a CLI-only install can’t route .test domains or serve HTTPS. After the one-time first-run setup you can work entirely from the terminal — the app doesn’t need to stay open.

Install Script

curl -fsSL https://dl.corral.sh/releases/install.sh | sh

This installs the CLI, then the app to /Applications, and offers to open the app so you can finish setup. Prefer a graphical install? Download Corral.dmg from corral.sh and drag it to Applications — it sets up the CLI automatically on first launch.

Reinstalling the App

If the app bundle is removed or you want to repair the installation, re-fetch it from the terminal:

corral install app --force

This downloads Corral.app to /Applications and refreshes the installed corral CLI from the new bundle.

The Privileged Helper

Corral needs elevated privileges to:

• Write the DNS resolver file to /etc/resolver/
• Run dnsmasq for local DNS resolution
• Run Caddy on ports 80 and 443 for HTTPS

Only the app can install this helper — macOS (via SMAppService) requires the registering app bundle to do it, which is why Corral ships as an app rather than a standalone CLI.

On first launch, the app shows a setup wizard. Press Authorize and macOS files Corral as a background item — then finish it yourself in System Settings → General → Login Items & Extensions, switching on Corral under App Background Activity and authenticating. There is no dialog to accept in the app, and macOS gives Corral no way to ask again, so the wizard simply waits for you: take as long as you like, and the step turns green on its own once you flip the switch.

You can skip it and install the helper later from Settings, but domain routing won’t work until the helper is approved.

CLI Availability

When the macOS app launches from /Applications, it installs the corral CLI to /Library/Application Support/Corral/bin/corral and points /usr/local/bin/corral at it. That copy lives outside the app bundle on purpose: moving Corral to the Trash leaves your node, npm and npx working and leaves corral uninstall able to finish the job.

Placing it needs the privileged helper, so until you have approved that, the CLI is installed to ~/.corral/bin/corral instead and Corral adds that directory to your PATH.

You can check the CLI status in the app under Settings → General.

Verifying Your Installation

corral status

You should see the infrastructure state (DNS and proxy) and an empty project list. The System helper row reads needs-setup until you have approved it. Once it does not, you can start infrastructure:

corral up

Updating

Self-update the CLI:

corral update

Check for updates without installing:

corral update --check

Data Directory

Corral stores all its data in ~/.corral/. This includes project registrations, settings, installed Node.js versions, logs, and infrastructure configuration. You can override this location with the CORRAL_DATA_DIR environment variable.

See Configuration for the full directory layout.

Uninstalling

From the app

Open Settings, scroll to the bottom, and choose one of two actions — they do different things and the names say which:

• Reset Corral infrastructure… stops DNS and the proxy, removes the resolver file, untrusts the HTTPS certificate, removes the installed corral command and unregisters the background helper. Corral, your projects and your data all stay. This is the one to reach for when local HTTPS or .test resolution has gone wrong and you want to set it up again.
• Remove Corral completely… does all of that and removes Corral. The app goes to the Trash, and a checkbox decides whether your data goes with it.

The removal asks you to type uninstall to confirm, then 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; everything else privileged goes through the background helper Corral already has, so there is no sudo and no second prompt.

“Also delete my Corral data” (on by default) covers ~/.corral: your projects, settings, license, installed Node versions and service data, with the current size shown beside it. Turn it off and all of that stays where it is, 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.

From the terminal

The fastest way to remove Corral completely — symmetric with the install one-liner:

curl -fsSL https://dl.corral.sh/releases/uninstall.sh | sh

This locates your installed corral and runs corral uninstall; if no local corral is found, it downloads a verified copy (Apple Silicon only) to run it. If the CLI is already on your PATH, you can run it directly instead:

corral uninstall

Either way removes the CA certificate (both the system and user keychains), kills orphaned processes, removes the DNS resolver file, uninstalls the privileged helper, deletes ~/.corral/, clears app preferences, removes shell shims, and removes the installed CLI along with its /usr/local/bin entry. The app itself goes to the Trash. You’ll be prompted for confirmation first.

To keep your data — the same choice the app’s checkbox offers:

corral uninstall --keep-data

See corral uninstall for details.

Manual uninstall (if neither the CLI nor the script is available):

1. Quit Corral from the menu bar
2. Uninstall the privileged helper: System Settings → General → Login Items & Extensions → App Background Activity → remove “Corral”
3. Untrust the root CA in both keychains, before deleting data (so the cert file still exists): security remove-trusted-cert ~/.corral/caddy/root-ca.crt and sudo security remove-trusted-cert -d ~/.corral/caddy/root-ca.crt (the -d form covers Corral’s legacy system-domain trust)
4. sudo rm -f /etc/resolver/test (replace test with your TLD), then sudo rm -f /usr/local/bin/corral and sudo rm -rf "/Library/Application Support/Corral"
5. Remove the app from Applications
6. Delete ~/.corral/ to remove all data (or keep it for a reinstall, but do delete ~/.corral/{shims,bin,libexec} either way — they’re what puts Corral on your PATH)
7. Remove the # >>> corral PATH block from your shell profile (~/.zshrc or ~/.bash_profile)