documentation

Overview

agent-local is one Go binary that creates, serves and manages local PHP sites on macOS — WordPress end to end, and any other PHP app (Joomla, Laravel, Drupal, plain files) served with its own domain, certificate and database. Native processes on real files, no Docker, no prerequisites, and the same engine is exposed to you and to coding agents over MCP and HTTP.

Quick start

# install (Homebrew)
brew install jefrontv/agent-local/agent-local

# one-time root steps: hosts, certs, the bare-URL front daemon
agent-local sudo

# your first site, serving in about twenty seconds
agent-local create mysite
agent-local open mysite

A site gets its own database, its own php-fpm pool, a hosts entry and a TLS certificate the moment it is created. The admin credentials print at the end of create — no wizard, no email.

What it runs

  • A Go router + php-fpm — one pool per site, each pinned to the PHP version the site asks for (7.4 – 8.5). Static files stream from disk; PHP goes over FastCGI. Apache is available as an alternative front when a site needs its .htaccess honoured.
  • An embedded MariaDB — one instance, one database per site, snapshots as plain .sql.gz.
  • A front daemon — holds 127.0.0.2:80/443, so sites answer on https://name.test with no port suffix and no warning page.
  • A dashboard, a CLI and an agent API — the TUI is agent-local with no arguments; every site-facing command is also an MCP tool.
  • A tools page on every site — https://name.test/.agent-local: the database GUI, the captured-mail inbox, the error log, what the site served, and one click into wp-admin. In your system's light or dark appearance. Local only; a share link never exposes it.

Requirements

  • macOS on Apple Silicon or Intel. That is the whole list.
  • Homebrew, for installing PHP, MariaDB and Apache on first use — agent-local installs them for you.
  • Docker is never required. Imports *remove* the need for it: LocalWP sites and DDEV projects move in.

Where things live

PathWhat
~/.agent-local/sites/SLUG/wpdocroots of copied sites; imports and attached directories stay where they are
~/.agent-local/snapshots/SLUG/database restore points, gzipped SQL
~/.agent-local/checkpoints/SLUG/checkpoints: a database snapshot plus a copy-on-write clone of the files
~/.agent-local/dumps/db export output
~/.agent-local/logs/daemon, Apache, php-fpm and WordPress debug logs
~/.agent-local/engines/the installed PHP runtimes, MariaDB and Apache
/etc/hostsone line per domain, pointing at 127.0.0.2

Everything survives a reboot: the daemon starts at login through launchd, brings the database up, and restores every site and preview that was running.