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.10.2.dmg

System Requirements

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

Corral bundles its own Wrangler and can manage Node.js for you — no global installs of either are required.

Installing

Corral is a macOS app, and the corral CLI ships inside it. Installing Corral installs both: the app — which registers the privileged helper — and the CLI, symlinked 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 repoints the CLI symlink to the app-bundled binary.

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 prompting you to approve the helper installation through a standard macOS authorization dialog. You can skip this step and install it later from Settings, but domain routing won’t work until the helper is installed.

CLI Availability

When the macOS app launches from /Applications, it automatically creates a symlink at /usr/local/bin/corral pointing to the CLI binary inside the app bundle. If /usr/local/bin isn’t writable, it falls back to ~/.corral/bin/corral.

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. If the privileged helper is installed, 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

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 CLI symlink. You’ll be prompted for confirmation first.

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) and sudo rm -f /usr/local/bin/corral
5. Remove the app from Applications
6. Delete ~/.corral/ to remove all data
7. Remove the # >>> corral PATH block from your shell profile (~/.zshrc or ~/.bash_profile)