A modern, fast development environment for Magento 2.
Built for solo developers and teams alike.

A modern, fast development environment for Magento 2. Uses native PHP-FPM and Nginx for maximum performance, with Docker for services like MySQL, Redis, OpenSearch, and Varnish.

Unlike Docker-based solutions (Warden, DDEV) or Laravel Herd, MageBox runs PHP and Nginx natively on your machine:

• No file sync overhead - Native filesystem access means instant file changes
• Native performance - PHP runs at full speed, not inside a container
• Simple architecture - Docker only for databases and search engines
• Multi-project support - Run multiple Magento projects simultaneously
• Automatic PHP switching - Smart wrapper automatically uses the right PHP version per project
• No sudo required - After one-time setup, all commands run as your user (macOS uses port forwarding)
• Team collaboration - Share repository configs, fetch projects with one command, sync databases from backup servers

Want to get started quickly? Just 4 commands:

# 1. Install MageBox (auto-detects your platform)
curl -fsSL https://get.magebox.dev | bash

# Optional: Create short aliases for faster typing
sudo ln -sf /usr/local/bin/magebox /usr/local/bin/mb    # shortest
sudo ln -sf /usr/local/bin/magebox /usr/local/bin/mbox  # descriptive

# 2. Set up your environment (one-time)
magebox bootstrap  # or: mb bootstrap

# 3. Create a new store with sample data (no questions asked!)
magebox new mystore --quick

# 4. Start your store
cd mystore && magebox start

Then run the Magento installer:

php bin/magento setup:install \
    --base-url=https://mystore.test \
    --backend-frontname=admin \
    --db-host=127.0.0.1:33080 \
    --db-name=mystore \
    --db-user=root \
    --db-password=magebox \
    --search-engine=opensearch \
    --opensearch-host=127.0.0.1 \
    --opensearch-port=9200 \
    --opensearch-index-prefix=magento2 \
    --opensearch-timeout=15 \
    --session-save=redis \
    --session-save-redis-host=127.0.0.1 \
    --session-save-redis-port=6379 \
    --session-save-redis-db=2 \
    --cache-backend=redis \
    --cache-backend-redis-server=127.0.0.1 \
    --cache-backend-redis-port=6379 \
    --cache-backend-redis-db=0 \
    --page-cache=redis \
    --page-cache-redis-server=127.0.0.1 \
    --page-cache-redis-port=6379 \
    --page-cache-redis-db=1 \
    --amqp-host=127.0.0.1 \
    --amqp-port=5672 \
    --amqp-user=guest \
    --amqp-password=guest

That's it! Open https://mystore.test in your browser.

Note: The --quick flag installs MageOS (no Adobe auth required) with sample data, PHP 8.3, MySQL 8.0, Redis, RabbitMQ, OpenSearch 2.19, and Mailpit - perfect for learning or testing.

Migrating from Herd? See our Migration Guide for step-by-step instructions to switch from Laravel Herd to MageBox.

# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install PHP versions you need
brew install php@8.1 php@8.2 php@8.3

# Install Nginx
brew install nginx

# Install mkcert for SSL certificates
brew install mkcert nss

# Install Docker Desktop
brew install --cask docker

# Install Composer
brew install composer

# Add PHP repository
sudo add-apt-repository ppa:ondrej/php
sudo apt update

# Install PHP 8.2 (example - install versions you need)
sudo apt install php8.2-fpm php8.2-cli php8.2-common php8.2-mysql php8.2-xml \
    php8.2-curl php8.2-mbstring php8.2-zip php8.2-gd php8.2-intl php8.2-bcmath php8.2-soap

# Install PHP 8.3
sudo apt install php8.3-fpm php8.3-cli php8.3-common php8.3-mysql php8.3-xml \
    php8.3-curl php8.3-mbstring php8.3-zip php8.3-gd php8.3-intl php8.3-bcmath php8.3-soap

# Install Nginx
sudo apt install nginx

# Install mkcert
sudo apt install mkcert libnss3-tools

# Install Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Install PHP (Remi repository)
sudo dnf install https://rpms.remirepo.net/fedora/remi-release-$(rpm -E %fedora).rpm
sudo dnf module enable php:remi-8.2
sudo dnf install php php-fpm php-cli php-common php-mysqlnd php-xml \
    php-curl php-mbstring php-zip php-gd php-intl php-bcmath php-soap

# Install Nginx
sudo dnf install nginx

# Install mkcert
sudo dnf install mkcert nss-tools

# Install Docker
sudo dnf install docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

macOS (Apple Silicon):

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

macOS (Intel):

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

Linux (x86_64):

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

Linux (ARM64):

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

git clone https://github.com/qoliber/magebox.git
cd magebox
go build -o magebox ./cmd/magebox
sudo mv magebox /usr/local/bin/

magebox --version

Run the bootstrap command to set up your environment:

magebox bootstrap

This performs:

1. Dependency Check - Verifies Docker, Nginx, mkcert, PHP are installed
2. Global Config - Creates ~/.magebox/config.yaml
3. SSL Setup - Installs mkcert CA (all .test domains get valid HTTPS)
4. Port Forwarding (macOS only) - Sets up transparent port forwarding (80→8080, 443→8443)
   • Allows Nginx to run as your user without sudo
   • Requires sudo password once during bootstrap
   • After setup, no sudo needed for daily operations
5. Nginx Config - Configures Nginx to include MageBox vhosts
   • Linux: Configures nginx to run as your user (required for SSL cert access)
   • Fedora: Configures SELinux contexts for nginx config/certs access
6. Docker Services - Starts MySQL 8.0, Redis, Mailpit containers
7. DNS Setup - Configures DNS resolution for .test domains
   • Linux: Configures dnsmasq + systemd-resolved for .test wildcard DNS
   • macOS: Creates /etc/resolver/test
8. PHP Wrapper - Installs smart PHP wrapper that automatically uses the correct version
9. PHP-FPM Setup (Linux) - Enables and starts PHP-FPM services
10. Sudoers Config (Linux) - Sets up passwordless sudo for nginx/php-fpm control

After bootstrap, these services are running:

magebox new mystore --quick

This installs MageOS with sensible defaults:

• MageOS 1.0.5 (no Adobe authentication required)
• PHP 8.3, MySQL 8.0, Redis, OpenSearch
• Sample data included
• Domain: mystore.test

magebox new mystore

This launches an interactive wizard where you choose:

1. Distribution - Magento Open Source or MageOS
2. Version - 2.4.7-p3, 2.4.6-p7, etc.
3. PHP Version - Shows compatible versions only
4. Composer Auth - Marketplace keys (Magento) or skip (MageOS)
5. Database - MySQL 8.0/8.4 or MariaDB 10.6/11.4
6. Search Engine - OpenSearch, Elasticsearch, or none
7. Services - Redis, RabbitMQ, Mailpit
8. Sample Data - Optional demo products
9. Project Details - Name and domain

After completion:

cd mystore
magebox start
php bin/magento setup:install \
    --base-url=https://mystore.test \
    --backend-frontname=admin \
    --db-host=127.0.0.1:33080 \
    --db-name=mystore \
    --db-user=root \
    --db-password=magebox \
    --search-engine=opensearch \
    --opensearch-host=127.0.0.1 \
    --opensearch-port=9200 \
    --opensearch-index-prefix=magento2 \
    --opensearch-timeout=15 \
    --session-save=redis \
    --session-save-redis-host=127.0.0.1 \
    --session-save-redis-port=6379 \
    --session-save-redis-db=2 \
    --cache-backend=redis \
    --cache-backend-redis-server=127.0.0.1 \
    --cache-backend-redis-port=6379 \
    --cache-backend-redis-db=0 \
    --page-cache=redis \
    --page-cache-redis-server=127.0.0.1 \
    --page-cache-redis-port=6379 \
    --page-cache-redis-db=1 \
    --amqp-host=127.0.0.1 \
    --amqp-port=5672 \
    --amqp-user=guest \
    --amqp-password=guest

Note: Remove --amqp-* options if RabbitMQ is not configured, and --opensearch-* if using Elasticsearch or no search engine.

cd /path/to/your/magento/project
magebox init

Answer the prompts to create a .magebox.yaml config file.

magebox start

This will:

• Verify PHP version is installed
• Generate SSL certificates for your domain
• Create PHP-FPM pool configuration
• Create Nginx vhost configuration
• Ensure database containers are running
• Create the project database
• Configure DNS for your domain

Open your browser and navigate to:

https://mystore.test

HTTPS works automatically with a valid certificate!

magebox start             # Start project services
magebox stop              # Stop project services
magebox status            # Show project status
magebox restart           # Restart project services

php bin/magento cache:clean          # MageBox PHP wrapper uses correct version
php bin/magento setup:upgrade
php bin/magento indexer:reindex

MageBox provides two ways to ensure you're using the correct PHP version:

1. PHP Wrapper (Recommended)

After running magebox bootstrap, add MageBox bin to your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.magebox/bin:$PATH"

# Reload shell
source ~/.zshrc  # or source ~/.bashrc

Now the php command automatically uses the version from .magebox.yaml:

cd /path/to/your/project
php -v                              # Automatically uses PHP 8.1 (from .magebox.yaml)
composer install                    # Uses correct PHP version
bin/magento cache:flush             # Uses correct PHP version

cd /path/to/another/project
php -v                              # Automatically uses PHP 8.2 (from that project's config)

2. Manual Switching

magebox php                          # Show current PHP version
magebox php 8.3                      # Switch to PHP 8.3 (updates .magebox.local.yaml)

magebox db shell                     # Open MySQL shell
magebox db import dump.sql           # Import database
magebox db export                    # Export to {project}.sql
magebox db export backup.sql         # Export to specific file

# Snapshots (quick backup/restore)
magebox db snapshot create           # Create snapshot with timestamp name
magebox db snapshot create mybackup  # Create named snapshot
magebox db snapshot list             # List all snapshots
magebox db snapshot restore mybackup # Restore from snapshot
magebox db snapshot delete mybackup  # Delete snapshot

magebox redis shell                  # Open Redis CLI
magebox redis flush                  # Flush all data
magebox redis info                   # Show server info

magebox logs                         # Show last 20 lines of all logs
magebox logs -f                      # Follow mode (live tail)
magebox logs -n 100                  # Show last 100 lines
magebox logs system.log              # Specific log file
magebox logs "exception*"            # Wildcard pattern

Define in .magebox.yaml:

commands:
  deploy: "php bin/magento deploy:mode:set production"
  reindex:
    description: "Reindex all"
    run: "php bin/magento indexer:reindex"

Run with:

magebox run deploy
magebox run reindex

MageBox makes it easy to onboard new developers and keep teams in sync.

# 1. Configure your team (one-time)
magebox team add mycompany

# 2. Add projects to the team
magebox team mycompany project add storefront \
  --repo mycompany/magento-storefront \
  --db backups/storefront/latest.sql.gz \
  --media backups/storefront/media.tar.gz

# 3. Share ~/.magebox/teams.yaml with your team

New team members can get started with a single command:

# Fetch everything: clone repo + download DB + import + download media
magebox fetch mycompany/storefront

# Initialize and start
cd storefront
magebox init
magebox start

# In your project directory, sync latest DB and media
magebox sync

# Or sync just the database with backup
magebox sync --db --backup

• Multiple Git providers - GitHub, GitLab, Bitbucket
• Asset storage - SFTP/FTP for database dumps and media files
• Progress tracking - Download speed, ETA, percentage complete
• Secure credentials - Environment variables, no passwords in config files

See the full Team Collaboration Guide for detailed setup instructions.

For enterprise teams needing centralized SSH key management with audit trails and ISO 27001 compliance:

# Initialize and start the team server
magebox server init --data-dir /var/lib/magebox/teamserver
magebox server start --port 7443

# Create a project and add environments
magebox server project add myproject --description "My Application"
magebox server env add staging --project myproject --host staging.example.com --deploy-user deploy --deploy-key ~/.ssh/deploy_key

# Invite team members and grant project access
magebox server user add alice --email alice@example.com --role dev
magebox server user grant alice --project myproject

Features include:

• Project-Based Access Control - Users granted access to projects containing environments
• Centralized User Management - Invite/revoke team members with admin approval
• Automatic SSH Key Deployment - Keys deployed to all environments in granted projects
• Role-Based Permissions - Admin, Dev, Readonly roles
• Multi-Factor Authentication - TOTP support (Google Authenticator compatible)
• Tamper-Evident Audit Logs - Hash chain verification for ISO 27001 compliance
• Email Notifications - Invitations, security alerts via SMTP
• Security Features - AES-256-GCM encryption, Argon2id hashing, IP lockout

See the full Team Server Guide for detailed documentation including ISO 27001 compliance.

name: mystore                    # Required: project name (used for DB name)

domains:                         # Required: at least one domain
  - host: mystore.test           # Required: domain name
    root: pub                    # Optional: document root (default: pub)
    ssl: true                    # Optional: enable SSL (default: true)
  - host: api.mystore.test       # Additional domains
    root: pub

php: "8.2"                       # Required: PHP version

php_ini:                         # Optional: PHP INI overrides
  opcache.enable: "0"            # Disable OPcache for development
  display_errors: "On"           # Show PHP errors
  xdebug.mode: "debug"           # Enable Xdebug debugging
  max_execution_time: "3600"     # Increase execution time
  memory_limit: "2G"             # Override memory limit

services:
  mysql: "8.0"                   # MySQL version
  # mariadb: "10.6"              # Or MariaDB (choose one)
  redis: true                    # Enable Redis

  # OpenSearch with ICU and Phonetic plugins (installed automatically)
  opensearch:
    version: "2.19.4"            # Latest OpenSearch version
    memory: "2g"                 # RAM allocation (default: 1g)

  # Elasticsearch with ICU and Phonetic plugins (installed automatically)
  # elasticsearch:
  #   version: "8.11"
  #   memory: "2g"               # RAM allocation (default: 1g)

  rabbitmq: true                 # Enable RabbitMQ
  mailpit: true                  # Enable Mailpit (email testing)

  # Varnish HTTP cache (runs in Docker)
  varnish: true                  # Simple enable
  # varnish:
  #   version: "7.5"             # Varnish version
  #   memory: "256m"             # Cache memory allocation

env:                             # Optional: environment variables
  MAGE_MODE: developer

commands:                        # Optional: custom commands
  deploy: "php bin/magento deploy:mode:set production"
  reindex:
    description: "Reindex all Magento indexes"
    run: "php bin/magento indexer:reindex"
  setup:
    description: "Full project setup"
    run: |
      composer install
      php bin/magento setup:upgrade
      php bin/magento cache:flush

Override settings locally (add to .gitignore):

php: "8.3"                       # Use different PHP locally

php_ini:                         # Override PHP settings locally
  opcache.enable: "0"            # Disable OPcache for local dev
  xdebug.mode: "debug,coverage"  # Enable Xdebug
  display_errors: "On"

services:
  mysql:
    version: "8.0"
    port: 3307                   # Different port

Location: ~/.magebox/config.yaml

magebox config show              # View current config
magebox config set dns_mode dnsmasq
magebox config set default_php 8.3
magebox config set tld test
magebox config set portainer true

MageBox automatically installs the ICU Analysis and Phonetic Analysis plugins for both OpenSearch and Elasticsearch. These plugins are required by Magento for proper search functionality.

Plugins included:

• analysis-icu - International Components for Unicode (ICU) analyzer
• analysis-phonetic - Phonetic token filter for soundex and metaphone algorithms

Memory Configuration:

By default, search engines are allocated 1GB of RAM. You can customize this in your .magebox.yaml:

services:
  # Recommended: with memory allocation (2GB for production-like performance)
  opensearch:
    version: "2.19.4"
    memory: "2g"

  # Simple version string (uses default 1GB RAM)
  # opensearch: "2.19.4"

Supported versions:

• OpenSearch: 2.19.x (latest), 2.x series
• Elasticsearch: 8.11, 7.17 (for Magento 2.4.4+)

┌──────────────────────────────────────────────────────────────────┐
│                          Your Machine                             │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Browser                                                          │
│     │                                                             │
│     │ https://mystore.test (port 443)                            │
│     ▼                                                             │
│  ┌──────────────┐                                                 │
│  │ pf (macOS)   │  Port forwarding: 80→8080, 443→8443           │
│  └──────┬───────┘                                                 │
│         │ port 8443                                               │
│         ▼                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌───────────────────────┐  │
│  │   Nginx     │    │  PHP-FPM    │    │   Docker Containers   │  │
│  │  (native)   │    │  (native)   │    │                       │  │
│  │  as user    │    │  as user    │    │  ┌───────┐ ┌────────┐ │  │
│  │ 8080/8443   │───▶│ Unix Socket │    │  │ MySQL │ │  Redis │ │  │
│  │             │    │             │    │  └───────┘ └────────┘ │  │
│  └─────────────┘    └─────────────┘    │  ┌────────────┐       │  │
│         │                  │           │  │ OpenSearch │       │  │
│         │                  │           │  └────────────┘       │  │
│         │                  │           │  ┌─────────┐          │  │
│         ▼                  ▼           │  │ Mailpit │          │  │
│  ┌─────────────────────────────────┐   │  └─────────┘          │  │
│  │        Project Directory        │   └───────────────────────┘  │
│  │         /path/to/magento        │◀──────────────┘              │
│  └─────────────────────────────────┘                              │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

Key Features:

• No sudo after setup - Services run as your user (pf handles port forwarding)
• Native performance - PHP and Nginx run directly on your machine
• Unix sockets - Fast PHP-FPM communication via sockets instead of TCP
• Docker for services - MySQL, Redis, OpenSearch in isolated containers
• Clean URLs - Access sites at https://mystore.test (no :8443 suffix)

On macOS, MageBox uses packet filter (pf) to enable services to run as your regular user without requiring sudo for daily operations. This is the same approach used by ddev and other professional development tools.

The Problem:

• Web servers need to listen on privileged ports 80 (HTTP) and 443 (HTTPS)
• Only root can bind to ports below 1024
• Running services as root is a security risk

MageBox Solution:

1. Nginx runs on unprivileged ports 8080 and 8443 as your user
2. macOS pf (packet filter) transparently forwards:
   • Port 80 → 8080
   • Port 443 → 8443
3. You access sites at clean URLs like https://mystore.test (no port suffix)
4. Behind the scenes, traffic is forwarded to high ports

When you run magebox bootstrap, it creates (requires sudo password once):

Location: /etc/pf.anchors/com.magebox

# MageBox port forwarding rules
rdr pass on lo0 inet proto tcp from any to any port 80 -> 127.0.0.1 port 8080
rdr pass on lo0 inet proto tcp from any to any port 443 -> 127.0.0.1 port 8443

Location: /Library/LaunchDaemons/com.magebox.portforward.plist

This daemon:

• Loads the pf rules automatically on system boot
• Runs as root (required for pf)
• Enables the forwarding transparently

✅ No sudo after setup - All daily commands (start, stop, restart) run as your user ✅ Secure - Services don't run as root ✅ Transparent - Clean URLs without port numbers ✅ Persistent - Survives reboots ✅ Standard approach - Same method used by ddev, Lando, etc.

Check if port forwarding is installed:

# Check if LaunchDaemon exists
ls -la /Library/LaunchDaemons/com.magebox.portforward.plist

# Check if pf rules exist
cat /etc/pf.anchors/com.magebox

# Test that it works
curl -I https://mystore.test  # Should connect without :8443

Port forwarding not working?

1. Verify LaunchDaemon is loaded:

   sudo launchctl list | grep magebox

   Should show: com.magebox.portforward

2. Reload pf rules manually:

   sudo pfctl -ef /etc/pf.anchors/com.magebox

3. Check nginx is listening on 8080/8443:

   lsof -nP -iTCP:8080 -sTCP:LISTEN
   lsof -nP -iTCP:8443 -sTCP:LISTEN

4. Re-run bootstrap:

   magebox bootstrap

If you need to remove the port forwarding setup:

# Unload LaunchDaemon
sudo launchctl unload /Library/LaunchDaemons/com.magebox.portforward.plist

# Remove files
sudo rm /Library/LaunchDaemons/com.magebox.portforward.plist
sudo rm /etc/pf.anchors/com.magebox

On Linux, MageBox doesn't need port forwarding because:

• Services are managed by systemd (which can bind to privileged ports)
• Alternatively, you can use setcap to grant capabilities to the nginx binary

~/.magebox/
├── config.yaml            # Global configuration
├── certs/                 # SSL certificates
│   └── {domain}/
│       ├── cert.pem
│       └── key.pem
├── nginx/
│   └── vhosts/            # Generated Nginx configs
├── php/
│   └── pools/             # Generated PHP-FPM pools
├── docker/
│   └── docker-compose.yml # Docker services
└── run/                   # Runtime files (sockets, PIDs)

MageBox allows you to override PHP configuration settings per-project using the php_ini section in your .magebox.yaml or .magebox.local.yaml file. These settings are injected into the PHP-FPM pool configuration and take precedence over system-wide PHP settings.

Add php_ini settings to your .magebox.yaml file:

php_ini:
  opcache.enable: "0"            # Disable OPcache
  display_errors: "On"           # Show errors
  error_reporting: "E_ALL"       # Report all errors
  max_execution_time: "3600"     # 1 hour timeout
  memory_limit: "2G"             # 2GB memory

By default, OPcache is enabled for performance. Disable it during active development to see code changes immediately:

php_ini:
  opcache.enable: "0"

Configure Xdebug for debugging and profiling:

php_ini:
  xdebug.mode: "debug,coverage"
  xdebug.start_with_request: "yes"
  xdebug.client_host: "localhost"
  xdebug.client_port: "9003"

For heavy operations like database imports or product imports:

php_ini:
  max_execution_time: "7200"     # 2 hours
  memory_limit: "4G"             # 4GB
  post_max_size: "256M"
  upload_max_filesize: "256M"

Optimize for production (use in .magebox.yaml, not .magebox.local.yaml):

php_ini:
  opcache.enable: "1"
  opcache.validate_timestamps: "0"  # Don't check file changes
  display_errors: "Off"
  error_reporting: "E_ALL & ~E_DEPRECATED & ~E_STRICT"

Use .magebox.local.yaml for development-specific overrides:

.magebox.yaml (committed to git):

php: "8.2"
# Production settings

.magebox.local.yaml (in .gitignore):

php_ini:
  opcache.enable: "0"            # Development only
  display_errors: "On"
  xdebug.mode: "debug"

You can override any PHP INI directive that can be set via php_admin_value in PHP-FPM. Common ones include:

• Performance: opcache.*, realpath_cache_size, realpath_cache_ttl
• Debugging: display_errors, error_reporting, xdebug.*
• Limits: memory_limit, max_execution_time, max_input_time, max_input_vars
• Uploads: post_max_size, upload_max_filesize
• Session: session.save_handler, session.gc_maxlifetime

After modifying php_ini settings, restart your project:

magebox restart

This regenerates the PHP-FPM pool configuration and reloads PHP-FPM.

The generated PHP-FPM pool configuration is located at:

~/.magebox/php/pools/{project-name}.conf

You can view it to see all applied settings:

cat ~/.magebox/php/pools/mystore.conf

During the one-time magebox bootstrap setup, you'll be prompted for your sudo password to:

• Install port forwarding rules (macOS only) - allows Nginx to run as your user
• Configure system-level services (Nginx, PHP-FPM symlinks)

After bootstrap is complete, you never need sudo again. All daily commands (start, stop, restart) run as your regular user.

No! After running magebox bootstrap once, all project commands run without sudo:

magebox start   # No sudo needed
magebox stop    # No sudo needed
magebox restart # No sudo needed

This is possible because:

• Port forwarding (pf) runs as a system daemon
• Nginx listens on unprivileged ports (8080/8443)
• PHP-FPM pools run as your user

For web ports (80/443):

• MageBox uses port forwarding (macOS) or systemd (Linux)
• Nginx actually listens on 8080/8443
• Port forwarding makes it accessible on 80/443
• If you're using other tools (MAMP, Valet, etc.), stop them first

For database ports:

• MySQL: 33080 (not standard 3306)
• Redis: 6379 (standard, may conflict)
• OpenSearch: 9200 (standard, may conflict)

MageBox installs a smart PHP wrapper at ~/.magebox/bin/php that:

1. Walks up the directory tree looking for .magebox.yaml or .magebox.local.yaml
2. Extracts the PHP version from the config file
3. Executes the correct PHP binary (e.g., /opt/homebrew/opt/php@8.1/bin/php)
4. Falls back to system PHP if no config file is found

This means:

• php -v automatically uses the right version
• composer install uses the right PHP
• bin/magento commands use the right PHP
• Works in any subdirectory of your project

To enable, add this to your ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.magebox/bin:$PATH"

Yes, but not simultaneously. MageBox uses the same approach (port forwarding on macOS), so:

✅ Safe: Run MageBox and ddev on different days ✅ Safe: Stop ddev before starting MageBox ❌ Conflict: Running both at the same time will cause port conflicts

# If you have ddev running:
ddev poweroff

# Then start MageBox:
magebox start

Performance! Native PHP is significantly faster than containerized PHP:

• No file sync overhead (Docker on macOS syncs files slowly)
• Direct filesystem access
• No virtualization layer
• Faster composer installs
• Faster Magento compilation

Docker is still used for services that benefit from isolation (MySQL, Redis, OpenSearch).

MageBox does NOT move your project files. Your Magento installation stays exactly where it is:

• /Volumes/qoliber/jbfurniturem2 ← Your project
• ~/.magebox/ ← MageBox configuration only

MageBox only creates:

• Nginx vhost configs pointing to your project
• PHP-FPM pool configs for your project
• SSL certificates for your domains

Everything persists across reboots:

• ✅ Port forwarding LaunchDaemon loads automatically
• ✅ Docker containers start automatically (if configured)
• ⚠️ You need to run magebox start again for project-specific services

Yes! Each project can use a different PHP version:

# Project 1 uses PHP 8.1
cd /path/to/project1
cat .magebox
php: "8.1"

# Project 2 uses PHP 8.3
cd /path/to/project2
cat .magebox
php: "8.3"

MageBox creates separate PHP-FPM pools for each project with the correct version.

Add to your .magebox or .magebox.local file:

php_ini:
  opcache.enable: "0"

Then restart:

magebox stop && magebox start

Magento's Nginx configuration routes all .php files through index.php. For direct PHP file access (like info.php), the file needs to exist and not be routed through Magento.

MageBox now allows all .php files to execute directly, so files like info.php in the pub/ directory will work.

Yes! Configure it in your .magebox file:

php_ini:
  xdebug.mode: "debug"
  xdebug.start_with_request: "yes"
  xdebug.client_host: "localhost"
  xdebug.client_port: "9003"

Make sure xdebug is installed:

# macOS
brew install php@8.1-xdebug  # or php@8.2-xdebug, php@8.3-xdebug

# Linux
sudo apt install php8.1-xdebug

[ERROR] PHP 8.3 not found

Install it with:
  macOS:  brew install php@8.3
  Ubuntu: sudo apt install php8.3-fpm php8.3-cli ...

[ERROR] Configuration file not found: /path/.magebox

[INFO] Run magebox init to create one

MageBox needs sudo to modify /etc/hosts. You'll be prompted for your password.

lsof -i :80
lsof -i :443
lsof -i :33080

sudo nginx -t

If which php in PhpStorm terminal shows /usr/bin/php instead of MageBox wrapper:

1. Check PhpStorm Settings → Tools → Terminal - uncheck any "Add PHP interpreter to PATH" option
2. Create symlink (recommended for Fedora/RHEL):

   sudo ln -sf ~/.magebox/bin/php /usr/local/bin/php

3. Add to ~/.zshenv:

   export PATH="/usr/local/bin:$PATH"

4. Fully restart PhpStorm (not just terminal tab)

See CLI Wrappers documentation for detailed troubleshooting.

# macOS
open -a Docker

# Linux
sudo systemctl start docker

magebox ssl trust      # Re-trust CA
magebox ssl generate   # Regenerate certs

If nginx is not binding to port 443, check:

1. SSL cert permissions - nginx must be able to read ~/.magebox/certs/
2. Nginx user - Must run as your user on Linux:

   # Check nginx user
   grep "^user" /etc/nginx/nginx.conf
   # Should show: user yourusername;
   
   # Fix if needed (run bootstrap or manually)
   sudo sed -i "s/^user .*/user $USER;/" /etc/nginx/nginx.conf
   sudo systemctl restart nginx

3. Check if 443 is listening:

   ss -tlnp | grep 443

If .test domains don't resolve:

1. Check dnsmasq is running:

   systemctl status dnsmasq

2. Check systemd-resolved config:

   cat /etc/systemd/resolved.conf.d/magebox.conf
   # Should contain:
   # [Resolve]
   # DNS=127.0.0.1
   # Domains=~test

3. Test DNS resolution:

   resolvectl query mystore.test
   # Should return 127.0.0.1

4. Re-run bootstrap if needed:

   magebox bootstrap

Fedora has SELinux enabled by default. MageBox bootstrap automatically configures SELinux, but if you encounter issues:

Nginx can't read configs or certs (HTTPS not working):

# Allow nginx to read MageBox configs and certs
sudo chcon -R -t httpd_config_t ~/.magebox/nginx/
sudo chcon -R -t httpd_config_t ~/.magebox/certs/

Nginx can't proxy to Docker containers (502 Bad Gateway):

# Allow nginx to make network connections
sudo setsebool -P httpd_can_network_connect on

Nginx can't read files from home directory (Permission denied):

# Allow nginx to read user content
sudo setsebool -P httpd_read_user_content on

PHP-FPM can't write logs:

# Set correct context on PHP-FPM log directories
sudo chcon -R -t httpd_log_t /var/opt/remi/php*/log/

Check SELinux denials:

# View recent SELinux denials
sudo ausearch -m avc -ts recent | grep -E "nginx|php-fpm"

git clone https://github.com/qoliber/magebox.git
cd magebox
go mod tidy
go build -o magebox ./cmd/magebox

go test ./... -v

magebox/
├── cmd/magebox/           # CLI entry point (~2800 lines)
├── internal/
│   ├── cli/               # Colors, logging, UI helpers
│   ├── config/            # .magebox parsing, global config
│   ├── platform/          # OS detection, paths
│   ├── php/               # PHP detection, FPM pools
│   ├── nginx/             # Vhost generation
│   ├── ssl/               # mkcert integration
│   ├── docker/            # Docker Compose generation
│   ├── dns/               # /etc/hosts, dnsmasq
│   ├── varnish/           # Varnish VCL generation
│   ├── project/           # Lifecycle management
│   ├── teamserver/        # Team server (users, projects, environments, audit)
│   └── updater/           # Self-update functionality
└── .github/workflows/     # CI/CD pipelines

See the full CHANGELOG.md for detailed version history.

Recent highlights:

• v0.19.1 - Server-side SSH key generation, magebox ssh command, environment sync
• v0.19.0 - Team Server with project-based access control, SSH key distribution, MFA, audit logging, ISO 27001 compliance
• v0.16.0 - Configurable TLD support
• v0.14.0 - Testing & code quality commands (PHPUnit, PHPStan, PHPCS, PHPMD)
• v0.13.0 - Multi-project management (start --all, stop --all, restart), uninstall command
• v0.12.x - Blackfire/Tideways profilers, CLI wrappers, multi-domain store codes
• v0.10.x - Varnish integration, log viewer, error reports, database management

MIT License - see LICENSE file.

Contributions are welcome! Please open an issue or submit a PR.

Built by Qoliber for the Magento community.