Local Craft CMS development for Mac.

Craft is a Composer project with its public files in web/, settings in .env, schema in config/project/ (project config, committed to git) and content in the database. Craft supports MySQL, MariaDB and PostgreSQL; Bothy runs MySQL and MariaDB, several servers side by side if you need to match different production versions. If a project is on Postgres, Bothy isn't the right fit for its database.

Bothy runs Caddy, php-fpm and your database servers as ordinary Mac services, and the project stays in a normal folder. Everything else is standard Craft.

The Craft starter runs composer create-project craftcms/craft, creates the database, writes .env and can run the installer with an admin account, so you go straight to https://studio.test/admin. web/ is detected as the document root automatically.

The .env keys are the usual ones, with local database access as root, no password, on 127.0.0.1:

CRAFT_ENVIRONMENT=dev
CRAFT_DB_DRIVER=mysql
CRAFT_DB_SERVER=127.0.0.1
CRAFT_DB_PORT=3306
CRAFT_DB_DATABASE=studio
CRAFT_DB_USER=root
CRAFT_DB_PASSWORD=
PRIMARY_SITE_URL=https://studio.test

Extra MySQL or MariaDB servers have their own ports, shown in the Databases screen; change CRAFT_DB_PORT to use one.

Craft's CLI is php craft in the project root. Run it through bothy site exec so it uses the same PHP version the site is served with:

bothy site exec studio -- php craft up
bothy site exec studio -- php craft project-config/apply
bothy site exec studio -- composer require craftcms/ckeditor
bothy site exec studio -- php craft plugin/install ckeditor
bothy site exec studio -- php craft clear-caches/all

craft up runs pending migrations and applies project config changes in one go, which is what you want after pulling a colleague's branch. Each site has its own PHP version and FPM pool, so a Craft 4 client site and a Craft 5 build can run different PHP without interfering: bothy site php oldclient 8.1. See PHP versions.

Clone the repo into a new site, install dependencies and create an empty database in one command, then load a production backup. Imports accept .sql, .sql.gz and .zip (Craft's own database backups are fine) and strip DEFINER clauses:

bothy site add client --git git@github.com:you/client.git --composer --db
bothy db import client ~/Downloads/client-backup.sql.zip
bothy site exec client -- php craft up

Write the .env for the clone yourself (it shouldn't be in git) with PRIMARY_SITE_URL=https://client.test, the database settings above, and the same CRAFT_SECURITY_KEY as production if you need encrypted data to stay readable. The site's Git tab shows what's changed in config/project/ before you commit.

Craft and plugin updates run migrations, and migrations are the thing you want to be able to undo locally. Take a gzipped snapshot first and restore if it goes wrong:

bothy db snapshot client
bothy site exec client -- composer update
bothy site exec client -- php craft up
# not happy?
bothy db restore client client-2026-09-27.sql.gz

Restore drops and recreates the database. phpMyAdmin is at phpmyadmin.test for poking at tables (bothy pma client). More in MySQL and MariaDB.

Catch Craft's system email with Mailpit: in Settings → Email choose the SMTP transport with host 127.0.0.1, port 1025 and no authentication. Messages show up at mail.test.

Craft's queue normally runs on web requests; to watch it work, run bothy site exec client -- php craft queue/listen in a terminal. Redis is available as an add-on on 127.0.0.1:6379 (with bothy addon php-ext redis 8.3 for the extension) if you configure Craft's cache or sessions to use it. For Tailwind or Vite builds, enable the Node add-on and run npm through bothy site exec.

With CRAFT_DEV_MODE on, Craft shows full error pages; Bothy adds per-site PHP, access and slow logs, followed live in the Logs tab or with bothy logs client --kind php. Turn on Xdebug for one site with bothy site xdebug client on (port 9003).

Bothy's MCP server gives Claude, Codex, Cursor and other clients tools for sites, databases and raw SQL, logs, mail and PHP settings. Ask it to snapshot the database, run php craft up and tell you what failed. See AI development.