{"id":13844628,"url":"https://github.com/bacongravy/macinbox","last_synced_at":"2025-04-08T09:11:14.743Z","repository":{"id":45003994,"uuid":"119144345","full_name":"bacongravy/macinbox","owner":"bacongravy","description":"Puts macOS in a Vagrant box","archived":false,"fork":false,"pushed_at":"2020-12-03T14:06:30.000Z","size":14347,"stargazers_count":663,"open_issues_count":17,"forks_count":44,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-01T08:37:18.268Z","etag":null,"topics":["catalina","macos","macos-catalina","parallels-desktop","vagrant","vagrant-boxes","virtualbox","vmware-fusion"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bacongravy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-27T07:48:08.000Z","updated_at":"2025-03-27T08:51:04.000Z","dependencies_parsed_at":"2022-08-30T07:30:19.487Z","dependency_job_id":null,"html_url":"https://github.com/bacongravy/macinbox","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bacongravy%2Fmacinbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bacongravy%2Fmacinbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bacongravy%2Fmacinbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bacongravy%2Fmacinbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bacongravy","download_url":"https://codeload.github.com/bacongravy/macinbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809964,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["catalina","macos","macos-catalina","parallels-desktop","vagrant","vagrant-boxes","virtualbox","vmware-fusion"],"created_at":"2024-08-04T17:02:49.180Z","updated_at":"2025-04-08T09:11:14.711Z","avatar_url":"https://github.com/bacongravy.png","language":"Ruby","funding_links":[],"categories":["Ruby (88)","Ruby"],"sub_categories":[],"readme":"# macinbox\n\nPuts macOS Catalina in a Vagrant box.\n\n\u003cp align=center\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/bacongravy/macinbox/demo/demo.gif\"\u003e\n  \u003ci\u003eSome sequences shortened. Original run time 14.5 minutes.\u003c/i\u003e\n\u003c/p\u003e\n\nSupports creating boxes in either the 'vmware_fusion', 'vmware_desktop', 'parallels', or 'virtualbox' formats.\n\n## System Requirements\n\n* macOS 10.15 Catalina host operating system\n* At least 8 GB RAM (16 GB recommended)\n* At least 2 cores (4 recommended)\n* At least 100 GB of available disk space\n\n## Additional Dependencies\n\nThe following software is required. Versions other than those mentioned may work, but these are the latest versions tested.\n\n### Vagrant\n\nTo boot a box created by `macinbox` you will need Vagrant:\n\n* [Vagrant 2.2.7](https://www.vagrantup.com/)\n\n### macOS Installer\n\nTo create a box you will need a macOS installer application. If you are using a Catalina host you must use a Catalina installer:\n\n* [macOS Catalina installer application](https://apps.apple.com/us/app/macos-catalina/id1466841314?ls=1\u0026mt=12) Tested with 10.15, 10.15.1, 10.15.3, 10.15.4\n\nCatalina hosts cannot use earlier (e.g. macOS 10.14 Mojave) installers, and Mojave hosts cannot use Catalina installers.\n\nIf you are using a Mojave host you should use a Mojave installer:\n\n* [macOS Mojave installer application](https://apps.apple.com/us/app/macos-mojave/id1398502828?ls=1\u0026mt=12) Tested with 10.14.3, 10.14.4, 10.14.5, 10.14.6\n\nIt is recommended that you use the same version for the host and the installer, but previous versions of the macOS installer (e.g. macOS 10.13 High Sierra) may also work with Mojave hosts, and vice-versa.\n\n**NOTE:** If you have questions about the permissibility of virtualizing macOS you may want to review the documentation for the virtualization software you are using and the [software license agreement](https://www.apple.com/legal/sla/) for macOS.\n\n### Virtualization Software\n\nOne of the following virtualization applications is required:\n\n#### VMware Fusion\n\nTo create and boot a box in the 'vmware_fusion' or 'vmware_desktop' formats you will need:\n\n* [VMware Fusion Pro 11.5.3](http://www.vmware.com/products/fusion.html)\n* [Vagrant VMware Desktop Provider 2.0.3](https://www.vagrantup.com/vmware/)\n\n#### Parallels Desktop\n\nTo create and boot a box in the 'parallels' format you will need:\n\n* [Parallels Desktop 15 for Mac Pro Edition 15.1.4](https://www.parallels.com/products/desktop/)\n* [Vagrant Parallels Provider 2.0.1](https://parallels.github.io/vagrant-parallels/)\n\n#### VirtualBox\n\nTo create and boot a box in the 'virtualbox' format you will need:\n\n* [VirtualBox 6.1.6 with the extension pack](https://www.virtualbox.org)\n\n## Installation\n\nInstall the gem:\n\n    $ sudo gem install macinbox\n\n## Basic Usage\n\nRun with `sudo` and no arguments, the `macinbox` tool will create and add a Vagrant VMware box named 'macinbox' which boots fullscreen to the desktop of the 'vagrant' user:\n\n    $ sudo macinbox\n\nPlease be patient, as this may take a while. (On a 2.5 GHz MacBookPro11,5 it takes about 11 minutes, 30 seconds.) After the tool completes you can create a new Vagrant environment with the box and start it:\n\n    $ vagrant init macinbox \u0026\u0026 vagrant up\n\nA few moments after running this command you will see your virtual machine's display appear fullscreen. (Press Command-Control-F to exit fullscreen mode.) After the virtual machine completes booting (approximately 1-2 minutes) you will see the desktop of the 'vagrant' user and can begin using the virtual machine.\n\nTo create a Parallels Desktop box, pass the `--box-format` option:\n\n    $ sudo macinbox --box-format parallels\n\n## Advanced Usage\n\nTo see the advanced options, pass the `--help` option:\n\n```\nUsage: macinbox [options]\n\n        --box-format FORMAT          Format of the box (default: vmware_desktop)\n\n    -n, --name NAME                  Name of the box         (default: macinbox)\n    -d, --disk SIZE                  Size (GB) of the disk   (default: 64)\n    -t, --fstype TYPE                Type for disk format    (default: APFS)\n    -m, --memory SIZE                Size (MB) of the memory (default: 2048)\n    -c, --cpu COUNT                  Number of virtual cores (default: 2)\n    -s, --short NAME                 Short name of the user  (default: vagrant)\n    -f, --full NAME                  Full name of the user   (default: Vagrant)\n    -p, --password PASSWORD          Password of the user    (default: vagrant)\n\n        --installer PATH             Path to the macOS installer app\n        --installer-dmg PATH         Path to a macOS installer app disk image\n        --vmware PATH                Path to the VMware Fusion app\n        --parallels PATH             Path to the Parallels Desktop app\n        --user-script PATH           Path to user script\n\n        --no-auto-login              Disable auto login\n        --no-skip-mini-buddy         Show the mini buddy on first login\n        --no-hidpi                   Disable HiDPI resolutions\n        --no-fullscreen              Display the virtual machine GUI in a window\n        --no-gui                     Disable the GUI\n\n        --use-qemu                   Use qemu-img (vmware_desktop only)\n\n        --verbose                    Enable verbose mode\n        --debug                      Enable debug mode\n\n    -v, --version\n    -h, --help\n```\n\nEnabling debug mode causes the intermediate files (disk image, VMDK, and box) to be preserved after the tool exits rather than being cleaned up. WARNING!!! These intermediate files are very large and you can run out of disk space very quickly when using this option.\n\nThis advanced example creates and adds a box named 'macinbox-large-nogui' with 4 cores, 8 GB or RAM, and a 128 GB disk; turns off auto login; and prevents the VMware GUI from being shown when the VM is started:\n\n    $ sudo macinbox -n macinbox-large-nogui -c 4 -m 8192 -d 128 --no-auto-login --no-gui\n\nIf you have the VAGRANT_HOME environment variable set and want the created box to be added to the 'boxes' directory in that location you will need to tell sudo to pass it through to macinbox, e.g.:\n\n    $ sudo \"VAGRANT_HOME=${VAGRANT_HOME}\" macinbox\n\n## Retina Display and HiDPI Support\n\nBy default `macinbox` will configure the guest OS to have HiDPI resolutions enabled, and configure the virtual machine to use the native display resolution. You can disable this behavior using the `--no-hidpi` option.\n\n## Box Format Support\n\nBy default `macinbox` will create a Vagrant box in the 'vmware_desktop' format with the VMware Tools pre-installed.\n\nWhen the box format is set to 'parallels' using the `--box-format` option then the Parallels Tools are pre-installed instead.\n\nWhen the box format is set to 'virtualbox' no guest extensions are installed. Note that some features behave differently with VirtualBox. The screen resolution is set to 1280x800 and HiDPI resolutions are not supported. The GUI scale factor is set to 2.0 (so that the VM displays properly on a host with a retina display) unless the `--no-hidpi` option is used. Lastly, ssh port-forwarding is enabled by default so that the host can connect to the guest.\n\n## User scripts\n\nIf additional box customization is required a user script may be specified using the `--user-script` option. The script is run after the OS has been installed and will be provided with the path to the install location as its first and only argument. The script must be executable and exit with code zero or the box creation will be aborted.\n\n## Installer Disk Image Support\n\nThe `--installer-dmg` option allows you to indicate the path to a disk image containing a macOS installer, and overrides the `--installer` option. The specified disk image should not already be mounted; `macinbox` will mount and unmount it as needed. This feature allows you to use the installer disk images created by [installinstallmacos.py](https://github.com/munki/macadmin-scripts/blob/master/installinstallmacos.py) as part of the `macinbox` workflow.\n\n## Implementation Details\n\nThis tool performs the following actions:\n\n1. Wraps the installer app in a disk image\n1. Creates a new blank disk image\n1. Installs macOS\n1. Installs the VMware or Parallels tools\n1. (VMware only) Updates the SystemPolicyConfiguration KextPolicy to allow the VMware tools kernel extension to load automatically\n1. Adds an .InstallerConfiguration file to automate the Setup Assistant app and create a user account on first boot\n1. Enables password-less sudo\n1. Enables sshd\n1. Adds an rc.installer_cleanup script which waits for the user account to be created on first boot and then installs the default insecure Vagrant SSH key in the user's home directory\n1. Enables HiDPI resolutions\n1. Converts the image into a virtual hard disk\n1. Creates a Vagrant box using the virtual hard disk\n1. Adds the box to Vagrant\n\n\nThe box created by this tool includes a built-in Vagrantfile which disables the following default Vagrant behaviors:\n\n1. Checking Vagrant Cloud for new versions of the box\n1. Forwarding from port 2222 on the host to port 22 (ssh) on the guest (VMware Fusion and Parallels Desktop only)\n1. Sharing the root folder of the Vagrant environment as '/vagrant' on the guest\n\nTo re-enable the default ssh port forwarding you can add the following line to your environment's Vagrantfile:\n\n    config.vm.network :forwarded_port, guest: 22, host: 2222, id: \"ssh\"\n\nTo re-enable the default synced folder you can add the following line to your environment's Vagrantfile:\n\n    config.vm.synced_folder \".\", \"/vagrant\"\n\n## Design Philosophy\n\nThis tool is intended to do everything that needs to be done to a fresh install of macOS before the first boot to turn it into a Vagrant box that boots macOS with a seamless user experience. However, this tool is also intended to the do the least amount of configuration possible. Nothing is done that could instead be deferred to a provisioning step in a Vagrantfile or packer template.\n\n## Acknowledgements\n\nThis project was inspired by the great work of others:\n\n* http://grahamgilbert.com/blog/2013/08/23/creating-an-os-x-base-box-for-vagrant-with-packer/\n* http://heavyindustries.io/blog/2015/07/05/create_osx_vagrant_vmware_box.html\n* https://spin.atomicobject.com/2015/11/17/vagrant-osx/\n* https://github.com/timsutton/osx-vm-templates\n* https://github.com/boxcutter/macos\n* https://github.com/chilcote/vfuse\n* http://www.modtitan.com/2017/10/lazy-vm-building-hacks-with-autodmg-and.html\n* https://github.com/AlexanderWillner/runMacOSinVirtualBox\n\n## Why?\n\nThis project draws inspiration from an episode of Mr. Robot. In the episode, Elliot is shown quickly booting what appeared to be a virtual machine running a fresh Linux desktop environment, in order to examine the contents of an untrusted CD-ROM. As I watched I thought, \"I want to be able to do that kind of thing with macOS!\". Surely I'm not the only person who has downloaded untrusted software from the internet, and wished that there was an easy way to evaluate it without putting my primary working environment at risk?\n\nThis project is a direct successor to my [vagrant-box-macos](https://github.com/bacongravy/vagrant-box-macos) project, which itself was heavily inspired by Tim Sutton's [osx-vm-templates](https://github.com/timsutton/osx-vm-templates) project.\n\nWith the release of macOS 10.12.4 the prevailing techniques for customizing macOS installs were hampered by a new installer requirement that all packages be signed by Apple. After attempting various techniques to allow `vagrant-box-macos` to support macOS 10.13 High Sierra, I decided a different approach to box creation was needed, and `macinbox` was born.\n\n## Development\n\nStart by running `sudo gem install bundler` and `bundle install`.\n\nTo run `macinbox` directly from the root of the git workspace without installing the gem, run `sudo bundle exec macinbox`.\n\nTo install this gem onto your local machine, run `sudo bundle exec rake install`.\n\nYou can also run `bin/console` for an interactive prompt that will allow you to experiment. For example:\n\n```\nopts = Macinbox::CLI::DEFAULT_OPTION_VALUES\nopts[:collector] = Macinbox::Collector.new\nopts[:full_name] = \"Vagrant\"\nopts[:password] = \"vagrant\"\nopts[:image_path] = \"macinbox.sparseimage\"\nopts[:boxes_dir] = File.expand_path \"~/.vagrant.d/boxes\"\n$debug = $verbose = true\n\ninclude Macinbox::Actions\n\nopts[:macos_version] = CheckMacosVersions.new(opts).run\n\nCreateImageFromInstaller.new(opts).run\n\nopts[:vmdk_path] = \"macinbox.vmdk\"\nCreateVMDKFromImage.new(opts).run\n\nopts[:box_format] = \"vmware_desktop\"\nopts[:box_path] = \"vmware_desktop.box\"\nCreateBoxFromVMDK.new(opts).run\nInstallBox.new(opts).run\n\nopts[:hdd_path] = \"macinbox.hdd\"\nCreateHDDFromImage.new(opts).run\n\nopts[:box_format] = \"parallels\"\nopts[:box_path] = \"parallels.box\"\nCreateBoxFromHDD.new(opts).run\nInstallBox.new(opts).run\n\nopts[:vdi_path] = \"macinbox.vdi\"\nCreateVDIFromImage.new(opts).run\n\nopts[:box_format] = \"virtualbox\"\nopts[:box_path] = \"virtualbox.box\"\nCreateBoxFromVDI.new(opts).run\nInstallBox.new(opts).run\n\nopts[:collector].cleanup!\n```\n\nTo release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/bacongravy/macinbox.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbacongravy%2Fmacinbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbacongravy%2Fmacinbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbacongravy%2Fmacinbox/lists"}