PlugBench Help

PlugBench is a local web server for your Mac, made to build and test plugins and themes. This page covers everything it can do.

Getting started

  1. Open PlugBench.dmg and drag PlugBench into Applications.
  2. Open PlugBench. The first time, a welcome window lists what it needs: nginx, PHP, MariaDB and Mailpit, all from Homebrew.
  3. Click Set Up PlugBench. Terminal opens and installs everything, Homebrew included if it is missing. Homebrew may ask for your Mac password once. PlugBench notices when setup is done.
  4. Click Start, then New Site.

Requirements: macOS 14 or later, Apple Silicon or Intel, about 2 GB of free space for the servers.

Closing the window keeps sites running. PlugBench stays in the menu bar. Quit PlugBench to stop everything.

The window

  • Sites, on the left: every site, with its CMS and address. Select one to see its details.
  • Services: only what is running now, such as nginx, PHP 8.5, MariaDB, Mailpit and Redis.
  • Toolbar buttons: phpMyAdmin, Adminer, Mail, Sites (opens the sites folder), Logs and Versions.
  • Sharing bar: appears while a site is shared, with buttons to copy the link or stop sharing.
  • Menu bar icon: start or stop, open any site signed in, stop sharing, open mail.

Each site’s page has these cards:

Header
Name, address, and a line such as WordPress · PHP 8.5 · MariaDB 13.0. Open Site and Open Admin buttons.
PHP and Server
PHP version, memory, upload size, time limit, Xdebug, database server, HTTPS and Terminal.
iPhone
Open in the iPhone Simulator, or scan a QR code with a real iPhone.
Share Online
A temporary public https link.
Development
Linked plugins, debug mode, logs and updates.
Backups
Back up, restore and clone.
Database
Name, user, password, port, and a button to open it in phpMyAdmin.

Creating sites

Click New Site, choose what to install, give it a name, and click Create Site.

ChoiceWhat you get
WordPressLatest WordPress. Sample content: none, a blog with photos, a WooCommerce store with 17 products, categories, customers and orders, or test data.
JoomlaLatest Joomla, ready to sign in.
DrupalDrupal with Drush. Optional magazine sample with articles and photos.
GravFlat-file CMS, no database.
Craft CMS, TYPO3, Statamic, Laravel, SymfonyInstalled from recipes with Composer.
Custom ZIPAny PHP site from a ZIP, with an optional SQL file to import. Use it to copy a client site locally.
BlankAn empty folder with PHP and a database, for your own code.

Options in the New Site window: PHP version, Database server, a specific CMS release, and WordPress network for Multisite.

Each site gets its own address, such as http://my-site.localhost:8801, its own database and its own administrator. Sites are only reachable from your Mac unless you share them.

One-click sign-in

Open Admin and Open Site sign you in as the administrator. No password to type. This works on WordPress, Joomla, Drupal, Craft and Statamic.

Each click creates a single-use sign-in link valid for 2 minutes. The administrator name and password are also shown on the site page if you need them.

Testing a plugin

  1. In Development, click Link Plugin Folder… and choose the folder you are coding in.
  2. PlugBench links it into the site and activates it. Nothing is copied: every save shows on the next page load.
  3. Turn on Debug mode to write PHP notices and warnings to the debug log, and click View Logs to read them.
  4. Remove unlinks it from the site. Your folder is never touched.

To test a plugin on several PHP versions, clone the site to another version (see Backups) or change the site’s PHP version.

PHP per site

Every site has its own PHP version. Change it in PHP and Server on the site page. The site restarts on the new version in a second.

Available: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 and 8.5. Install more in Versions. PHP 7.4 and 8.0 are end of life and come from the shivammathur/php Homebrew tap.

Per-site settings, to match a client’s host:

  • Memory: memory_limit, such as 128M or 512M.
  • Upload size: upload_max_filesize and post_max_size.
  • Time limit: max_execution_time, in seconds.

Each setting applies only to its site.

Xdebug and PHP extensions

In Versions, each installed PHP shows its extensions. Click one to build it for that PHP version (about a minute):

  • Xdebug: step debugging.
  • Redis: phpredis, for object cache plugins.
  • Imagick: ImageMagick image editing.
  • Memcached: for Memcached object cache.

Then turn on Xdebug on a site. Xdebug stays off for every PHP version no site needs it on, so it costs nothing.

VS Code: install the PHP Debug extension, click Copy VS Code Setup, paste it into .vscode/launch.json, and start Listen for Xdebug. PlugBench uses port 9003. PhpStorm listens on 9003 by default and works the same way.

Databases

The default server is MariaDB, on port 3307 so it never meets a MySQL you already run on 3306. Install more servers in Versions:

  • MariaDB 10.6, 10.11, 11.4, 11.8
  • MySQL 8.0, 8.4, 9.7

Each server runs on its own port. Pick one when you create a site, or move an existing site with the Database server menu: PlugBench dumps the database, imports it into the other server, and updates the site’s configuration.

phpMyAdmin and Adminer open already signed in, with every server listed. The Database card on a site opens its own database directly. Both tools only answer on your Mac.

PostgreSQL 17 is available as a service, on port 5433, user postgres, with the same password as the MySQL root user.

Local HTTPS

  1. In Versions, install mkcert.
  2. Click Trust Local HTTPS… once. Terminal asks for your Mac password to add a local certificate authority.
  3. Turn on HTTPS on a site. It is served at its port + 1000, such as https://my-site.localhost:9801.

On WordPress, PlugBench updates the site’s addresses in the database, Multisite included. Turning HTTPS off reverts them.

WordPress Multisite

Turn on WordPress network in New Site. You get a network with sites in subdirectories, such as /shop/. Add sites in My Sites, Network Admin, Sites. Clones, HTTPS and sharing keep the network working.

Terminal and WP-CLI

Open Terminal on a site opens a shell in its folder, with the site’s PHP first in the path and wp ready. php, composer and wp all use that site’s PHP version. Your own shell settings are loaded too.

wp plugin list
wp user create editor editor@example.com --role=editor
wp eval 'echo get_option("home");'

Mail, logs and debug

  • Mail opens Mailpit. Every email a site sends lands there: password resets, WooCommerce orders, contact forms. Nothing leaves your Mac.
  • Debug mode turns on WP_DEBUG and WP_DEBUG_LOG on WordPress.
  • Logs shows the debug log, the PHP error log and nginx errors. Clear empties them before a test.

Backups, clones and updates

  • Back Up Now saves the files and database. Restore brings back the latest backup.
  • Clone copies a site under a new name, optionally on another PHP version. Addresses inside the database are updated.
  • Update backs up the database, then updates the CMS. On WordPress, Update Plugins and Themes updates the rest.
  • Delete removes the site, its database and its certificate.

Services

Install from Versions. Once installed, they start and stop with PlugBench.

ServiceUseAddress
RedisObject cache plugins127.0.0.1:6379
MemcachedObject cache127.0.0.1:11211
PostgreSQL 17Laravel, Drupal127.0.0.1:5433
Node.jsBlock development, build toolsin the Terminal path
mkcertLocal HTTPS
MailpitCatches emailslocalhost:8025
cloudflaredShare Online

iPhone

  • Open in Simulator opens the site in the iPhone Simulator, signed in. It needs Xcode’s Simulator.
  • Real iPhone: click Share on Wi-Fi, then scan the QR code with the iPhone’s camera. The iPhone must be on the same Wi-Fi. Turn sharing off when you are done.

Sharing a site

Share Online gives a site a temporary https://…trycloudflare.com link through a free Cloudflare tunnel. No account needed. Send it to a client to review a site running on your Mac.

  • To limit who can open it, enter email addresses or *@client.com. Cloudflare asks visitors to confirm their email first.
  • Share Online and Copy Link starts sharing and puts the link in the clipboard. Copy Invitation copies a ready-to-send message with the link.
  • Stop Sharing Online on the site, Stop All in the sharing bar, or Stop All Sharing in the menu bar ends it at once. The link stops working.

WordPress pages, images and sign-in links follow whichever address the visitor uses.

AI tools (MCP)

PlugBench speaks the Model Context Protocol, so Claude Code, Claude Desktop, Cursor and other AI tools can drive it. Connect Claude Code with one command:

claude mcp add plugbench -- "/Applications/PlugBench.app/Contents/MacOS/plugbench" mcp

Then ask, for example: Create a WooCommerce store, link ~/Code/my-plugin, turn on debug, place an order and tell me if any PHP warnings appear.

The 26 tools:

list_sitessite_infostatusstart_servicescreate_siteclone_site list_versionsset_phpset_php_settingset_xdebugmove_database list_pluginslink_pluginunlink_pluginset_plugin_active set_debugread_logsclear_logsrun_phpread_mail backup_siterestore_sitelogin_urliphone_screenshot share_onlineshare_on_network

run_php runs code inside WordPress, signed in as the administrator. iphone_screenshot lets the AI look at the site on an iPhone.

Command line

Everything in the app also works from Terminal. Add the tool to your path:

ln -s /Applications/PlugBench.app/Contents/MacOS/plugbench /opt/homebrew/bin/plugbench
Services
plugbench start | stop | statusControl services
plugbench doctorShow detected tools
plugbench versionsList PHP, database servers and services
plugbench add <formula>Install one, such as php@7.4 or mysql@8.0
plugbench extension <php> <name>Build xdebug, redis, imagick or memcached
Sites
plugbench listList sites
plugbench install <cms> <name> [source]Create a site. Options: --sample, --version, --sql, --database, --php, --multisite
plugbench info <slug>Details and logins as JSON
plugbench login <slug> [admin|front]Print a one-time sign-in link
plugbench delete <slug>Delete a site
plugbench rename-address <slug>Move an older site to slug.localhost
PHP and server
plugbench php <slug> <version>Change PHP version
plugbench php-setting <slug> <name> <value>memory_limit, upload_max_filesize, max_execution_time
plugbench xdebug <slug> on|offXdebug on port 9003
plugbench move-db <slug> <formula>Move the database, or default
plugbench https <slug> on|offLocal HTTPS
plugbench terminal <slug>Terminal with the site’s PHP and WP-CLI
Plugins and debugging
plugbench link <slug> <folder>Link and activate a plugin
plugbench unlink <slug> <folder>Remove a linked plugin
plugbench plugins <slug>List plugins as JSON
plugbench debug <slug> on|offWP_DEBUG logging
plugbench logs <slug> [lines]Show logs
plugbench logs-clear <slug>Empty logs
plugbench run <slug> <file.php|->Run PHP inside a site
plugbench mailList caught emails
Backups and updates
plugbench backup | restore <slug>Back up or restore
plugbench clone <slug> <name> [php]Copy a site
plugbench version <slug>Installed and latest CMS version
plugbench update <slug>Update the CMS
plugbench update-extensions <slug>Update plugins and themes
Tools and sharing
plugbench phpmyadmin [slug]phpMyAdmin address
plugbench adminerAdminer address
plugbench share on|offWi-Fi sharing
plugbench share-online <slug> [emails|stop]Public link
plugbench iphone <slug> [path]Simulator and screenshot
plugbench recipesList recipes
plugbench license [activate <key> | deactivate]License
plugbench mcpRun the MCP server

Recipes: add your own CMS

A recipe is a small JSON file that tells PlugBench how to install a CMS or framework. Put yours in ~/Library/Application Support/PlugBench/recipes/ and it appears in New Site.

{
  "id": "winter",
  "title": "Winter CMS",
  "summary": "The Laravel-based CMS.",
  "minimumPHP": "8.1",
  "composer": "wintercms/winter",
  "docroot": "",
  "adminPath": "/backend",
  "env": {
    "file": ".env",
    "copyFrom": ".env.example",
    "values": {
      "APP_URL": "{url}",
      "DB_HOST": "{db_host}",
      "DB_PORT": "{db_port}",
      "DB_DATABASE": "{db_name}",
      "DB_USERNAME": "{db_user}",
      "DB_PASSWORD": "{db_password}"
    }
  },
  "steps": [ ["php", "artisan", "winter:up"] ]
}

Main fields: composer or zip for the source, docroot for the served folder, database: false for flat-file CMS, loginWithEmail and loginCommand for one-click sign-in. Placeholders: {url}, {root}, {db_host}, {db_port}, {db_name}, {db_user}, {db_password}, {admin_user}, {admin_password}, {admin_email}.

You can also click Add a Recipe… in New Site. Only add recipes you trust: their steps run as your user.

plugbench recipes lists the recipes PlugBench sees.

Free and Pro

FreePro, $29 once
Sites3Unlimited
All CMS, PHP and database versions, Xdebug, HTTPS, backups, phpMyAdmin, MailpitYesYes
Share Online and Wi-Fi sharingYes
iPhone toolsYes
AI tools (MCP)Yes

Activate a key in the License card on the main page, or with plugbench license activate KEY. A key works on your Macs; deactivate one to move it. PlugBench checks the key once a week and keeps working 30 days offline.

Where things are

Sites~/PlugBench/<slug>
Settings, logs, databases, backups~/Library/Application Support/PlugBench
Your recipes…/PlugBench/recipes
Backups…/PlugBench/backups
Logs…/PlugBench/logs
ServersHomebrew, /opt/homebrew

Ports

Sites8801 and up; HTTPS at the same port + 1000
phpMyAdmin8799
Adminer8800
Mailpit8025 (web), 1025 (SMTP)
MariaDB, default3307
Other database servers3308 and up
Redis, Memcached, PostgreSQL6379, 11211, 5433
Xdebug9003 (your editor listens)

Everything listens on 127.0.0.1 only, except sites while Wi-Fi sharing is on.

Troubleshooting

Start fails or a service stays off

Open Logs and read the error. A port may already be used by another server, such as MAMP or Valet: quit it and click Start again. plugbench doctor lists what PlugBench found.

Setup stopped in Terminal

Read the last lines in Terminal. Often Homebrew asked for your password or for the Xcode command line tools. Answer, then click Set Up PlugBench again: it continues where it stopped.

Open Admin shows the sign-in page

Sign-in links last 2 minutes and work once. Click Open Admin again. If it still fails, the admin password is on the site page.

The browser warns about HTTPS

Click Trust Local HTTPS… in Versions once, then restart the browser. Firefox needs nss from Homebrew to trust it.

An extension does not build

Extensions can only be added to PHP from Homebrew. Read the Terminal output in Logs; installing the latest Xcode command line tools with xcode-select --install often fixes it.

Xdebug does not stop at breakpoints

Check that Xdebug is on for the site, that your editor listens on port 9003, and that the browser request comes from the same site. Commands in Terminal run with Xdebug off.

The iPhone cannot open the site

Turn on Wi-Fi sharing, check that both are on the same Wi-Fi, and allow incoming connections if macOS asks. Guest networks often block devices from seeing each other.

A shared link stopped working

Cloudflare Quick Tunnel links are temporary and end when sharing stops or the Mac sleeps. Share again for a new link.

How do I remove PlugBench completely?

Quit PlugBench, delete it from Applications, and delete ~/Library/Application Support/PlugBench and ~/PlugBench. Homebrew packages stay; remove them with brew uninstall if you like.

Questions: support@nextstarsystems.com.