Installation

Before you download

Vhostly manages the Homebrew stack, so that has to exist first. If you have never installed Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then Apache and PHP:

brew install httpd php mkcert
brew services start httpd

You can also skip all of this and let the app's setup wizard take you through each piece, with the exact command on screen before it runs. Homebrew's installer needs your password and a keypress, so the wizard opens it in Terminal, where you answer its prompts yourself.

Download

Grab the latest .dmg from the releases page, open it, and drag Vhostly.app to /Applications.

Getting past Gatekeeper

The build is not notarised by Apple yet, so macOS will refuse it on the first open and say it "cannot be opened because Apple cannot check it for malicious software". That is Gatekeeper reacting to the missing notarisation, not to anything about the app.

Open it once this way and macOS remembers the decision:

  1. Double-click Vhostly.app and dismiss the warning.
  2. Open System Settings → Privacy & Security, scroll to the Security section, and press Open Anyway next to the message about Vhostly.
  3. Confirm once more.

On macOS 14 and earlier, Control-clicking the app and choosing Open does the same job in one step.

If you would rather clear the quarantine flag directly:

xattr -dr com.apple.quarantine /Applications/Vhostly.app

Either way it is a one-time step. Once a notarised build ships, none of this will be needed.

The one-time permission

On first launch Vhostly checks whether it can already do its job. If it cannot, it asks for your administrator password once, with the prompt "Vhostly: one-time setup permission".

That prompt installs one thing that runs as root: a small helper that writes the Vhostly block of /etc/hosts. Nothing else Vhostly does needs your password.

  • Apache runs as you. Homebrew's httpd starts from your own LaunchAgent, and macOS lets any process listen on ports 80 and 443, so Vhostly restarts it without sudo.

  • /etc/hosts stays owned by root. The helper only accepts names ending in .test or .localhost, only writes 127.0.0.1 and ::1, and only touches the lines between Vhostly's markers. Even a program that calls it cannot point a real domain anywhere.

  • The sudoers rule allows exactly that helper, with no arguments:

    <you> ALL=(root) NOPASSWD: /Library/PrivilegedHelperTools/app.vhostly.hosts ""
    

    It is checked with visudo before it goes live. The helper is owned by root in a root-owned folder, so nothing running as you can change what it does.

The full list of commands is shown before you agree, and the helper's source is on the security page.

If you decline the prompt, the app cannot add sites — it explains why rather than half-working. The setup is re-checked on every launch, and Settings → Health shows its state.

The environment checks

On first launch, the setup wizard checks the machine and shows one step at a time: Homebrew, Apache, PHP, starting Apache, the one-time permission above, then optional tools. Each step shows its exact command before you press the button, and nothing is installed silently.

Required — Homebrew, PHP, Apache, whether Apache is running, whether its configuration parses, whether the vhosts file is writable, and whether the hosts helper is installed.

Recommended — OpenSSL, mkcert, Composer and Node. Vhostly runs without them; mkcert is the one that decides whether local HTTPS is trusted or merely encrypted. You can skip it here: enabling HTTPS on a site installs it then.

You can skip a step, or choose Set up later, and finish afterwards. The same screen is always available from Settings → Setup guide → Show it, and the same checks live under Environment → Health.

Uninstalling

Delete Vhostly.app. Your sites keep serving, because the configuration it wrote is ordinary Apache configuration and Apache does not know the app is gone.

To take the sites down too, disable each one in the app first — that removes the vhost block and the hosts entry — and then delete the app. To undo every trace, including the file ownership and the sudoers rule, follow reverting by hand.