Skip to content
Butler

Per-project butler.yml

Drop a butler.yml file at the root of any linked or parked project to override Butler’s defaults for that project alone. Every field is optional — a site without the file inherits your global config and Butler’s auto-detection. A valet.yml file is accepted as a fallback name for projects coming from Valet.

Generate a starter file with butler init in the project directory.

Full example

Section titled “Full example”
php: "8.3"                        # runtime version
webserver: frankenphp-octane      # caddy | nginx | frankenphp | frankenphp-octane
driver: laravel                   # overrides auto-detection
publicPath: public                # overrides the driver's default docroot


env:                              # extra environment exposed to PHP
  APP_DEBUG: "true"


database:                         # optional DB hookup for `butler link`
  type: mysql
  name: my_app_local
  createOnLink: true


scripts:                          # lifecycle hooks (run with cwd = site dir)
  postLink: "composer install && php artisan migrate"
  preUnlink: "php artisan app:cleanup"


server:                           # web-server tuning
  clientMaxBodySize: "100M"
  phpSettings:
    memory_limit: "1G"


ssl:                              # bring your own cert instead of Butler's CA
  cert: /abs/path/to/site.pem
  key:  /abs/path/to/site-key.pem


proxy:                            # reverse-proxy mode (with driver: proxy)
  target: "127.0.0.1:3000"        # your own dev server (Vite, Next, etc.)
  websocket: true                 # tunnel WebSocket upgrades; default true
  headers:
    X-Source: butler


octane:                           # only when webserver is frankenphp-octane
  workers: 8
  max_requests: 500
  watch:
    - app
    - routes
    - config
    - .env

Field reference

Section titled “Field reference”

Runtime

Section titled “Runtime”
  • php — the PHP version for this site, e.g. "8.3". Equivalent to butler isolate but committed with the repo. See PHP versions.
  • webserver — caddy, nginx, frankenphp, or frankenphp-octane.
  • driver — force a framework handler instead of auto-detection (laravel, wordpress, symfony, drupal, statamic, craft, proxy, static, custom).
  • publicPath — the web root, relative to the project, when it isn’t the driver default.

Environment & database

Section titled “Environment & database”
  • env — extra environment variables exposed to PHP.
  • database — optionally have butler link connect (and, with createOnLink: true, create) a database. See Databases & services.

Lifecycle scripts

Section titled “Lifecycle scripts”
  • scripts.postLink — a shell command run after the site is linked (cwd is the site directory) — e.g. install dependencies and run migrations.
  • scripts.preUnlink — run before the site is unlinked.

Web server

Section titled “Web server”
  • server.clientMaxBodySize — max upload size, e.g. "100M".
  • server.phpSettings — per-site php.ini overrides such as memory_limit.

TLS

Section titled “TLS”
  • ssl.cert / ssl.key — absolute paths to your own certificate and key, used instead of Butler’s CA. See HTTPS & trusted certs.

Reverse proxy

Section titled “Reverse proxy”
  • proxy.target — with driver: proxy, forward to a dev server you run yourself (Vite, Next, etc.).
  • proxy.websocket — tunnel WebSocket upgrades (default true).
  • proxy.headers — extra headers to add to proxied requests.

Octane

Section titled “Octane”

Only applies when webserver is frankenphp-octane:

  • octane.workers — number of worker processes.
  • octane.max_requests — requests a worker handles before recycling.
  • octane.watch — paths that trigger a reload when they change.