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

v1.15.0

What's New

Added

• Auto-Start on magebox open - magebox open now starts the project automatically when it is not running. It checks each required service (skipping optional Xdebug and Blackfire) and brings up anything that is down before opening the browser. If everything is already up, the browser opens immediately without extra output. (#86)
• MageOS 2.2.2 in Version Registry - magebox new can now scaffold MageOS 2.2.2 projects (base: Magento 2.4.8). (#89)

Fixed

• magebox run PHP Version Shadowing on Linux - magebox run previously prepended /usr/bin (the directory of the versioned PHP binary on Linux) to PATH, which silently shadowed the ~/.magebox/bin/php wrapper and made php in custom commands resolve to the system default (e.g. /usr/bin/php → PHP 8.4). With Magento 2.4.8-p3 and a mismatched system PHP, bin/magento degraded to minimal bootstrap mode and commands like deploy:mode:set were silently absent. magebox run now prepends ~/.magebox/bin instead, so php, composer, and blackfire in custom commands consistently resolve to the project-aware wrappers and pick the PHP version from .magebox.yaml. (#91)
• Database Import Progress Bar Reaching 100% - The database import progress bar now reaches 100% instead of stopping at the last tick before EOF (e.g. 98.9%). (#87)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.15.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.15.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.15.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.15.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.14.2

What's New

Changed

• Tideways API Key Scope - The Tideways API key is now configured per-project instead of globally. Because each Tideways API key is tied to a single Tideways project, storing it in ~/.magebox/config.yaml either pinned every local Magento project to the same Tideways project or silently got shadowed when reconfigured. The key now lives in the project's .magebox.local.yaml under php_ini.tideways.api_key and is rendered into the FPM pool as php_admin_value, so multiple local projects can each report to their own Tideways project. magebox tideways config prompts for the key when run inside a project that doesn't have one set, and magebox tideways status reports whether the current project has a key configured. Legacy global api_key entries still unmarshal and are detected, surfaced as a migration warning, and removed on save. Access token and environment label remain global. (#82)

Added

• --project-api-key Flag - magebox tideways config accepts a new --project-api-key flag for non-interactive per-project API key configuration. Only applied when MageBox is run from inside a project. (#82)

Removed

• TIDEWAYS_API_KEY Environment Variable - The TIDEWAYS_API_KEY env var is no longer read by magebox tideways config, since the API key is no longer a global setting. Use --project-api-key or set php_ini.tideways.api_key in .magebox.local.yaml instead. (#82)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.14.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.14.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.14.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.14.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.14.1

What's New

Fixed

• Tideways PHP Extension API Key - magebox tideways config now writes the tideways.api_key directive into the PHP extension ini file for every installed PHP version, which the Tideways PHP extension requires to transmit traces. Previously MageBox only wrote a daemon config file, and traces never reached Tideways. (#77)
• Composer Version Fallback - magebox new no longer errors when the daily-updated version registry contains Magento/MageOS versions not present in the hardcoded composer plugin constraint map. Unknown versions now fall back to sensible defaults instead of failing project creation. (#80)
• Self-Update Binary Sync - magebox self-update now syncs the updated binary to all known locations (~/.magebox/bin/magebox, ~/.magebox/bin/mbox, /usr/local/bin/magebox, /usr/local/bin/mbox) to prevent version mismatches between magebox and mbox. (#80)
• magebox new ./ Path Handling - magebox new ./ now correctly resolves the project name to the current directory name instead of literally .. Paths are normalized via filepath.Clean. (#80)

Added

• Tideways CLI Access Token - magebox tideways config now also prompts for (and stores) a separate Access Token used by the tideways commandline tool (tideways run, tideways event create, tideways tracepoint create). When provided, MageBox runs tideways import <token> automatically. A new --access-token flag and TIDEWAYS_CLI_TOKEN environment variable were added. The API key and access token are two different credentials — both are now managed. (#77)
• Tideways Environment Label - magebox tideways config now prompts for an environment label (defaulting to local_<username>) and writes a systemd drop-in for tideways-daemon on Linux so traces from developer machines are tagged with the local environment instead of the server-side default production. A --environment flag and TIDEWAYS_ENVIRONMENT env var are also supported. macOS prints a clear manual-config hint. (#77)

Changed

• Troubleshooting Docs - Updated troubleshooting documentation with entries for version mismatch between magebox/mbox binaries and unsupported Magento version errors. (#80)
• Tideways Docs - Updated Tideways service and global-config guide pages to document the API key vs. access token vs. environment credentials and the per-project Installation URL as the API key source. (#77)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.14.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.14.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.14.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.14.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.14.0

What's New

Fixed

• Xdebug Linux Support - Fixed Xdebug detection on Linux by adding a Linux case to findXdebugSo() using php-config to locate the extension directory. Also writes full Xdebug configuration (mode, start_with_request, client_host, client_port, idekey) when enabling, and updated install hint to use magebox ext install xdebug. (#75)
• Watch Command Cache Clean - The magebox watch command now checks for cache-clean.js in the project's vendor/bin directory before falling back to a global install. (#73)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.14.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.14.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.14.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.14.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.13.1

What's New

Changed

• Watch Command Theme Detection - The magebox watch command now detects any theme with an npm watch script instead of only Hyvä themes. Walks the full theme tree under app/design/frontend/ and prompts the user to select when multiple themes are found. (#70)
• MageOS Version Registry - Added MageOS 2.2.1 to the supported version registry. (#69)

Fixed

• Expose Revert NULL Handling - Fixed expose revert inserting literal string 'NULL' instead of SQL NULL into base_static_url and base_media_url config entries, corrupting the database values after reverting an expose session. (#71)
• Tmux Theme Watcher - Fixed tmux theme watcher pane closing immediately when npm watch fails. Errors now stay visible with a user-friendly message. (#72)
• FAQ: Composer Patches on macOS - Added FAQ entry for composer patches hanging on macOS due to BSD patch interactive behavior. (#63)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.13.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.13.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.13.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.13.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.13.0

What's New

Added

• Watch Command - New magebox watch command that runs mage-os/magento-cache-clean to watch for file changes and selectively clear affected cache types. Automatically detects Hyvä themes and launches a split tmux session with both the cache watcher and Tailwind CSS watcher. (#66)
• Magerun2 Fallback - Unknown commands are now automatically forwarded to magerun2 if available, so you can run commands like magebox cache:flush or magebox setup:upgrade directly without prefixing with magerun2. (#67)

---

Installation

macOS (Apple Silicon):

curl -L https://github.com/qoliber/magebox/releases/download/v1.13.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.13.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.13.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.13.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