First run

The first time you open Butler.app, an onboarding window walks you from a fresh install to a working stack. This page explains each step so you know what you’re choosing.

1. Allow Butler at login

Butler needs your permission to run in the background and to bind the web ports. Onboarding sends you to System Settings → General → Login Items & Extensions where you flip Butler’s switch on. Until you do, macOS refuses to start the piece that binds ports 80 and 443, so .test sites won’t load.

This is a one-time step. If you ever miss it, butler doctor will point it out.

2. Grant the one-time permission

Setup needs your password once to install the DNS resolver, trust Butler’s certificate authority, and register the privileged port binder. You’ll see a standard macOS password prompt — approve it and you won’t be asked again.

3. Choose a web server

Butler can serve your sites with any of:

• Caddy — a great default. Fast, modern, and zero-config.
• nginx — familiar if your production stack uses it.
• FrankenPHP — PHP built into the web server; also powers Octane mode for long-running Laravel apps.

You can change this globally later, or override it per project in butler.yml.

4. Choose a PHP version

Pick the PHP version most of your projects use — for example 8.3 or 8.4. This becomes your global default. Individual sites can pin a different version at any time with butler isolate (see PHP versions), and you can install more versions whenever you need them.

5. Add optional services

A fresh Butler is deliberately lean: the router, your web server, and one PHP version. Onboarding offers the common extras so you can tick the ones you want:

• Databases — MySQL, PostgreSQL, MariaDB, MongoDB
• Caches — Redis, Valkey
• Mail — Mailpit, a local inbox that catches outgoing mail
• Search — Typesense
• Storage — S3-compatible object storage

Anything you skip can be added later with butler install or from the app — see Databases & services.

Done

When onboarding finishes, Butler is running. It lives in your menu bar; click the icon for the dashboard. To prove everything works, link a project:

butler link ~/Sites/my-app
open http://my-app.test

From here:

• Tour the menu bar app.
• Learn the ins and outs of linking sites.
• Turn on HTTPS.