v2.0.0

What's New

Added

• mysql-client as a Managed Dependency - magerun2's database commands (db:info, db:dump, …) shell out to mysql/mysqldump, but MageBox never checked for them, so those commands failed with no useful explanation. magebox bootstrap now detects mysqldump alongside Docker, Nginx and mkcert, includes mysql-client in the missing-dependency prompt, and installs it per platform (mysql-client on Homebrew, default-mysql-client on Ubuntu/Debian, community-mysql on Fedora, mariadb-clients on Arch). On macOS the formula is keg-only, so bootstrap prints the shell-specific line needed to put it on PATH and warns — without failing — when mysqldump is still missing afterwards. magebox check reports mysql-client status in its magerun2 section and surfaces the install command. (#114)
• Magento 2.4.9 and MageOS 3.3.0 - Added to the version registry. (#135)

Changed

• BREAKING: One Shared Search Container Per Engine - The global compose file was generated per search version, so each requested version got its own container, container name, volumes, and version-derived host port (OpenSearch 2.19 → 9259, Elasticsearch 7.17 → 9657). A machine running several projects on different versions therefore ran several search containers, each holding its own JVM heap. MageBox now runs at most one OpenSearch and one Elasticsearch container for the whole machine, shared across every project, on fixed host ports: OpenSearch 9200, Elasticsearch 9500 (distinct so both engines can run simultaneously). Service names (opensearch/elasticsearch), container names (magebox-opensearch/magebox-elasticsearch) and volumes (opensearch_data, opensearch_plugins, …) lost their version suffix. When projects request different versions, the version from global config wins, otherwise the highest requested version is used; the container is provisioned with the largest memory any project asks for. GetOpenSearchPort/GetElasticsearchPort return the fixed ports and no longer take a version argument, and the version→port helpers were removed. status, service-name matching, magebox new and magebox check follow the fixed names and ports. (#129)

  Upgrading: projects configured against a version-derived port must be repointed to 9200/9500, and the new container starts on a fresh volume, so catalogsearch_fulltext needs a reindex. The old per-version containers and volumes are orphaned and can be removed. See Upgrading from MageBox 1.x for the full procedure. Only rebuildable search indices are affected — no persistent data is lost.

Fixed

• Varnish Crash-Looped with Multiple Projects - buildVCLConfig emitted one backend per registered project, but the template only ever references DefaultBackend. Varnish 7.x treats a defined-but-unused backend as a fatal compile error, so with two or more projects the shared magebox-varnish container failed to compile its VCL and crash-looped, returning 502 on every request and recurring on each magebox start. Every generated backend was identical anyway, since Nginx already routes to the right project by Host header, so the VCL now emits a single magento backend. The health probe also used HEAD / expecting 301 while Magento returns 302, which marked the backend sick and returned 503; it now probes GET /health_check.php expecting 200. Both the embedded template and the lib/templates copy are fixed — the previous attempt patched only the latter, which is not the one rendered at runtime. (#131)
• Stale Container Names in OpenSearch Service Docs - The troubleshooting and container-logs examples still referenced magebox-opensearch-2.19 instead of the shared magebox-opensearch container.
• Order-Dependent Search Version Test - TestComposeService_Elasticsearch_FixedPortAndVolumes resolved a major.minor version without the Docker Hub mock installed, so it queried the real API and cached the unresolved fallback in the package-level tag cache, intermittently failing TestResolveElasticsearchVersion on CI depending on test order.

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v2.0.0/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v2.0.0/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v2.0.0/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v2.0.0/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.19.1

What's New

Fixed

• Self-Healing Web-UI Commands - phpmyadmin, elasticvue, and mailpit now start their container on demand instead of dead-ending when it is stopped (which happens routinely after a Docker Desktop or machine restart). phpmyadmin open and elasticvue open start the container when the service is enabled but stopped, then open the browser; mailpit open always starts it (Mailpit is always on). phpmyadmin enable and elasticvue enable are now idempotent — when already enabled but stopped, they restart the container instead of printing "already enabled" and doing nothing. Only the requested UI container is started (no full global start, no databases dragged in), and a clear message is shown when Docker itself is not running. status now points to the relevant open command. Shared helpers (isContainerRunning, openInBrowser, ensureGlobalServiceRunning, decideServiceUI) de-duplicate the logic across the three commands. (#128)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.1/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.1/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.1/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.1/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.19.0

What's New

Added

• Configurable PHP-FPM Process Manager - Pool configs previously hardcoded pm = dynamic with pm.max_children = 50, sized as if each pool had the machine to itself; on a host running several projects those defaults collectively oversubscribe it, and hand-edited pool files were overwritten on the next magebox start. A pm block can now be set in .magebox.yaml / .magebox.local.yaml, with a machine-wide default_pm baseline in ~/.magebox/config.yaml. Precedence is project > global > built-in, merged key by key so a local override can tune a single value. ondemand is the notable addition for multi-project machines: dormant projects start no workers at all. Only the directives valid for the selected mode are written, and values are validated before the pool file is written — a single malformed pool prevents the FPM master from starting, taking down every project on that PHP version. Lowering only max_children scales the untouched spare-server defaults down to fit rather than erroring. Defaults are unchanged, so existing installs render byte-identical pool files. (#133)

Fixed

• PHP-FPM Service Docs Showed Stale pm Values - The service documentation still listed 5/2/10/500 for start_servers/min_spare_servers/max_spare_servers/max_requests rather than the 8/4/12/1000 the code has been generating. (#133)
• CI Failed on Fork Pull Requests - The comment-artifacts job requests pull-requests: write, but GitHub caps GITHUB_TOKEN to read-only for pull_request runs originating from a fork, so posting the artifact comment failed with a 403 and marked the whole run as failed even when every build, test and lint job passed. This had broken every fork PR since the job was added. The job is now gated on the PR originating from this repository; PRs from branches in this repository keep their artifact comment. (#134)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.0/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.0/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.0/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.19.0/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.18.2

What's New

Fixed

• magebox open <worktree> Served the Wrong Project - The worktree branch skipped start when the shared global services (MySQL, Redis, …) were already running for the base project, so the worktree's Nginx vhost was never generated and requests fell through to Nginx's default server (a different project). The worktree is now started unconditionally.
• SSL for Nested Worktree Hosts - Certificates were generated only for the two-label base domain with a *.base wildcard, which matches a single label, so a nested host such as shop.nl.b2b-case.localhost was not covered and HTTPS failed. Certificate generation now adds each exact host as a SAN — regenerating only when the existing certificate does not already cover every host — fixing SSL for deeply nested domains.

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.2/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.2/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.2/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.2/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.18.1

What's New

Added

• Worktree Argument for magebox open - magebox open <name> now targets the git worktree at .claude/worktrees/<name>. MageBox derives a .magebox.local.yaml from the worktree's .magebox.yaml — appending .<name> to the project name and inserting .<name> before the TLD of each domain host (e.g. mystore.localhost → mystore.<name>.localhost) — then starts and opens the worktree as its own isolated project. Comments and layout from .magebox.yaml are preserved, and the override is rewritten on every run.

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.1/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.1/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.1/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.1/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.18.0

What's New

Added

• STOP Protocol Support - New magebox stop-protocol command group (enable, disable, status) that toggles the Static Precompilation & OPcache Protocol for the current project. Enabling writes the required opcache.* keys (including opcache.preload = <project>/app/preload.php, opcache.preload_user, JIT settings, and 512 MB memory) to .magebox.local.yaml and performs a full PHP-FPM restart (not a reload), because opcache.preload is only evaluated at master start. A new FPMController.Restart() was added for this purpose. See the STOP guide. (#121)
• PR Build Artifacts - CI now uploads binaries built from pull request branches as GitHub Actions artifacts and posts a comment on the PR with download links, so reviewers can test changes without building locally.

Changed

• Search Service Version Resolution - opensearch:2 or elasticsearch:7 (major-only shorthands) are now resolved to a concrete image tag that actually exists in the registry, instead of failing with a missing-image error. Hardcoded version defaults were removed in favour of registry lookups, and the docs for OpenSearch and Elasticsearch were updated. (#118)

Fixed

• Redis No Longer Starts Unconditionally - GenerateDefaultServices previously emitted a Redis service in the generated compose file even when globalCfg.DefaultServices.Redis was false, so magebox start would spin up Redis for every project. Redis is now only added when explicitly enabled, and docker compose up runs with --remove-orphans so previously-started Redis containers are cleaned up on the next start. (#115)
• Mailpit Sendmail Compatibility with Symfony Mailer - The generated PHP-FPM pool now sets sendmail_path to mailpit sendmail -t. Without -t, Symfony Mailer (used by recent Magento versions) fails to deliver mail through Mailpit because recipients aren't passed on the command line. (#125)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.0/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.0/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.0/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.18.0/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.17.0

What's New

Added

• Auto-Managed magerun2 Wrapper - Bootstrap now installs ~/.magebox/bin/magerun2, so no manual version management is required. The wrapper detects the Magento version from composer.lock and maps it to the correct n98-magerun2 release (7.5.0 for Magento < 2.4.5, latest GitHub release for 2.4.5+), downloads the phar once with SHA256 checksum verification, and runs fully offline on subsequent invocations. magebox check reports wrapper and phar status. (#101)
• AI-Accessible Documentation - The VitePress docs now generate llms.txt, llms-full.txt, and per-page .md files at build time via vitepress-plugin-llms, making magebox.dev consumable by AI agents per the llmstxt.org standard. (#110)

Changed

• OpenSearch/Elasticsearch Index Prefix Scoped to Project - magebox new now passes the project name as the index prefix in both the interactive wizard's displayed setup:install command and the quick-install execution path. Multiple MageBox projects share one Docker search engine instance, so the previous hardcoded magento2 prefix caused index collisions across projects. Docs were updated to use project-name placeholders with a warning callout explaining why a project-scoped prefix is required. (#111)

Fixed

• magebox start Touches Only This Project's Services - The Services summary lists services scoped to the current project, but docker compose up previously started every service in the shared global compose file, so the printed container list included mysql8.0, opensearch-2.12.0, rabbitmq, etc. owned by other projects. magebox start now passes the current project's compose service names to docker compose up -d, so the container output matches the Services summary.
• Installer Directory Creation - The install.sh script now creates the installation directory before copying the binary into it, instead of failing when the parent directory doesn't already exist. The redundant INSTALL_DIR definition was also removed. (#113)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.17.0/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.17.0/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.17.0/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.17.0/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.16.1

What's New

Added

• Interactive PHP Version Prompt on magebox init - magebox init now prompts for the PHP version, defaulting to the value detected from the project's composer.json (config.platform.php, falling back to require.php) and finally to the global default when no supported version is declared. Supported versions are listed as hints, and the prompt annotates (from composer.json) when the default came from the project. (#97)

Changed

• Multitail Scrollback Buffer - magebox logs and magebox logs php|nginx now keep 10000 lines of scrollback instead of 500, so meaningful log history is actually reachable when scrolling back. (#99)

Fixed

• MySQL/MariaDB Port 3306 Binding - Port 3306 is now bound strictly to the database version named by globalCfg.DefaultServices.MySQL (or MariaDB when no MySQL default is configured). Previously any MySQL/MariaDB container in the compose file would also grab 3306, which conflicted with a default-version container left running from another project. Only one container ever claims the standard port now. (#100)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.1/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.1/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.1/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.1/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.16.0

What's New

Changed

• macOS Port Forwarding: pf replaced with TCP proxy daemon - The previous approach used macOS pf (packet filter) kernel rules to redirect ports 80→8080 and 443→8443. These rules were unreliable — Apple's own pf management would override custom anchors after reboot and sleep/wake, silently breaking all .test domains. MageBox now uses a persistent TCP proxy daemon (magebox _portforward) managed by launchd with KeepAlive: true. The daemon listens on ports 80/443 and forwards connections to nginx on 8080/8443. This eliminates all interaction with the macOS pf subsystem. Legacy pf anchor files (/etc/pf.anchors/com.magebox), helper scripts, and /etc/pf.conf modifications are automatically cleaned up on upgrade. (#95)

Added

• Port forwarding self-healing on magebox start/magebox restart - On macOS, magebox start and magebox restart verify that the port forwarding daemon is running and restart it if needed. Domains work immediately without needing magebox bootstrap again.
• Port Forwarding Health Check - magebox check now includes a Port Forwarding section on macOS that reports whether the LaunchDaemon is installed and port forwarding is active.

Fixed

• macOS PHP Detection for Unversioned Homebrew Formula - When PHP was installed via brew install php (the unversioned/current formula), MageBox failed to find it because it only looked in Cellar/php@8.4/. The unversioned formula installs to Cellar/php/8.4.x/ instead. Both the Go binary detection and the PHP wrapper script now check both paths.

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.0/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.0/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.0/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.16.0/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update

v1.15.1

What's New

Fixed

• PHP-FPM Pool Group Lookup - getCurrentGroup() on Linux previously returned the username verbatim, assuming the primary group name matched the username (USERGROUPS_ENAB convention). On systems where the primary group is renamed or shared (e.g. user john with primary group john-doe), the generated FPM pool contained group = john and php-fpm refused to start with cannot get gid for group 'john'. Because the pool file is regenerated on every magebox start, hand-patching didn't stick. The group is now resolved via os/user + GID lookup, and getCurrentUser() routes through user.Current() so both resolutions share one source of truth. (#92)
• PHP Install on Ubuntu with PHP 8.5 - PHP 8.5 ships OPcache built into php8.5-cli, so the Ondřej PPA no longer publishes a separate php8.5-opcache package. The hardcoded install list caused bootstrap to fail with Unable to locate package php8.5-opcache. MageBox now filters the extension list through apt-cache show before invoking apt install, printing a note for any skipped packages. Self-heals future packaging consolidations without requiring version-specific branches. (#94)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.15.1/magebox-darwin-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

macOS (Intel):

curl -L https://github.com/qoliber/magebox/releases/download/v1.15.1/magebox-darwin-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (x86_64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.15.1/magebox-linux-amd64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Linux (ARM64):

curl -L https://github.com/qoliber/magebox/releases/download/v1.15.1/magebox-linux-arm64 -o /usr/local/bin/magebox
chmod +x /usr/local/bin/magebox

Verify Installation

magebox --version

Update Existing Installation

magebox self-update