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
- Open
PlugBench.dmgand drag PlugBench into Applications. - Open PlugBench. The first time, a welcome window lists what it needs: nginx, PHP, MariaDB and Mailpit, all from Homebrew.
- 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.
- 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.
| Choice | What you get |
|---|---|
| WordPress | Latest WordPress. Sample content: none, a blog with photos, a WooCommerce store with 17 products, categories, customers and orders, or test data. |
| Joomla | Latest Joomla, ready to sign in. |
| Drupal | Drupal with Drush. Optional magazine sample with articles and photos. |
| Grav | Flat-file CMS, no database. |
| Craft CMS, TYPO3, Statamic, Laravel, Symfony | Installed from recipes with Composer. |
| Custom ZIP | Any PHP site from a ZIP, with an optional SQL file to import. Use it to copy a client site locally. |
| Blank | An 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
- In Development, click Link Plugin Folder… and choose the folder you are coding in.
- PlugBench links it into the site and activates it. Nothing is copied: every save shows on the next page load.
- Turn on Debug mode to write PHP notices and warnings to the debug log, and click View Logs to read them.
- 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_filesizeandpost_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
- In Versions, install mkcert.
- Click Trust Local HTTPS… once. Terminal asks for your Mac password to add a local certificate authority.
- 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_DEBUGandWP_DEBUG_LOGon 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.
| Service | Use | Address |
|---|---|---|
| Redis | Object cache plugins | 127.0.0.1:6379 |
| Memcached | Object cache | 127.0.0.1:11211 |
| PostgreSQL 17 | Laravel, Drupal | 127.0.0.1:5433 |
| Node.js | Block development, build tools | in the Terminal path |
| mkcert | Local HTTPS | |
| Mailpit | Catches emails | localhost:8025 |
| cloudflared | Share 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.
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:
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 | status | Control services |
plugbench doctor | Show detected tools |
plugbench versions | List 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 list | List 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|off | Xdebug on port 9003 |
plugbench move-db <slug> <formula> | Move the database, or default |
plugbench https <slug> on|off | Local 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|off | WP_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 mail | List 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 adminer | Adminer address |
plugbench share on|off | Wi-Fi sharing |
plugbench share-online <slug> [emails|stop] | Public link |
plugbench iphone <slug> [path] | Simulator and screenshot |
plugbench recipes | List recipes |
plugbench license [activate <key> | deactivate] | License |
plugbench mcp | Run 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
| Free | Pro, $29 once | |
|---|---|---|
| Sites | 3 | Unlimited |
| All CMS, PHP and database versions, Xdebug, HTTPS, backups, phpMyAdmin, Mailpit | Yes | Yes |
| Share Online and Wi-Fi sharing | Yes | |
| iPhone tools | Yes | |
| 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 |
| Servers | Homebrew, /opt/homebrew |
Ports
| Sites | 8801 and up; HTTPS at the same port + 1000 |
| phpMyAdmin | 8799 |
| Adminer | 8800 |
| Mailpit | 8025 (web), 1025 (SMTP) |
| MariaDB, default | 3307 |
| Other database servers | 3308 and up |
| Redis, Memcached, PostgreSQL | 6379, 11211, 5433 |
| Xdebug | 9003 (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.