{"id":26301899,"url":"https://github.com/doineann/portable-vbox-vm","last_synced_at":"2026-04-07T19:31:41.969Z","repository":{"id":246058808,"uuid":"819927451","full_name":"Doineann/portable-vbox-vm","owner":"Doineann","description":"Run a VirtualBox VM from any removable drive in Windows.","archived":false,"fork":false,"pushed_at":"2024-07-06T16:54:30.000Z","size":16,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-07-07T00:38:22.268Z","etag":null,"topics":["batch-script","portable","removable-drives","scripts","virtualbox","virtualbox-vm"],"latest_commit_sha":null,"homepage":"","language":"Batchfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Doineann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-25T13:03:33.000Z","updated_at":"2024-07-06T16:33:33.000Z","dependencies_parsed_at":"2024-06-25T16:41:49.954Z","dependency_job_id":"939206d0-1915-4998-9fa9-55c4a965e9cb","html_url":"https://github.com/Doineann/portable-vbox-vm","commit_stats":null,"previous_names":["doineann/portable-vbox-vm"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doineann%2Fportable-vbox-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doineann%2Fportable-vbox-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doineann%2Fportable-vbox-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doineann%2Fportable-vbox-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Doineann","download_url":"https://codeload.github.com/Doineann/portable-vbox-vm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243695552,"owners_count":20332629,"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":["batch-script","portable","removable-drives","scripts","virtualbox","virtualbox-vm"],"created_at":"2025-03-15T07:17:21.780Z","updated_at":"2025-12-29T19:40:24.137Z","avatar_url":"https://github.com/Doineann.png","language":"Batchfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Portable-VBox-VM\n\n**Run a _VirtualBox_ VM from a removable drive in Windows.**\n\nThis bundle of `.cmd` scripts will let you run a _VirtualBox_ VM from any removable drive, or really any location with a driveletter mapped to it, such as usb-drives, external harddisks, network shares, etc...\n\n## Requirements\n\nWindows with a pre-installed version of VirtualBox (version 7.x.x) and a prepared VM.\n\n## Prepare and configure your VM\n\nFirst, a quick overview and description of the files and folders that come with this repository:\n\n- `📁 Scripts` -\u003e supporting script files\n- `📁 Shared` -\u003e shared folder\n- `📁 VM` -\u003e folder to contain the VM files\n- `📟 Compact.cmd` -\u003e command to compact the VM harddisk\n- `📝 Config.ini` -\u003e configuration file\n- `📄 README.md` -\u003e this readme\n- `📟 Run.cmd` -\u003e runs the VM in immutable mode\n- `📟 RunMutable.cmd` -\u003e runs the VM in mutable mode\n\nTo prepare your VM for transfer to the removable medium:\n\n1. Copy **ALL** the files and folders of this repository to any location on a removable drive.\n2. Make sure the VM has **no snapshots!** or that they have been merged. \n   \u003e [!WARNING] Any remaining snapshots will end up being removed!!\n3. Make sure the VM has only has **1 harddisk** attached to **SATA port 0**.\n4. Modify the `📝 Config.ini` and enter the right information for your VM:\n\n```bash\nVM_NAME=VirtualMachine\n\nVM_VBOX_UUID=0d5ecb7b-e2df-4110-8899-fa02fa5ce780\nVM_VBOX_FILE=VirtualMachine.vbox\n\nVM_HDD_UUID=94b2fd99-d68c-4428-bca7-c0f999c1a431\nVM_HDD_FILE=VirtualMachine.vdi\n\nVM_SHARE_NAME=vboxshare\nVM_SHARE_RELATIVE_PATH=Shared\n```\n\u003e [!NOTE]\n\u003e   - Find the `VM_HDD_UUID` for the harddisk in **VirtualBox**, by finding it via `File\u003eTools\u003eVirtual Media Manager`, selecting the disk -\u003e right-click -\u003e `Properties` , then the Information tab. \n\u003e   - Determine the name and `VM_VBOX_UUID` by opening the VM's `.vbox` file in an editor. \u003cbr\u003e(**OPTIONAL:** you can change the name of the VM and it's files or even it UUID if so desired)\n\u003e   - Choose a name for `VM_SHARE_NAME` and modify, relocate or rename the `📁 Shared` folder as you wish, and configure its relative path with `VM_SHARE_RELATIVE_PATH`.\n\n5. Detach the VM from VirtualBox, if it still is.\n6. Detach any remaining media/harddisks related to the VM in `File\u003eTools\u003eVirtual Media Manager`.\n7. Put all your VM files (`.vbox\\.vdi\\.vmdk` etc...) in the `📁 VM` folder. \n8. Run the VM with `📟 Run.cmd` or `📟 RunMutable.cmd`!\n\n## How it works\n\nEffectively this tool just automates the following steps when temporary running a VM from a 'remote' location within an already installed version of VirtualBox on Windows:\n\n1. Registers the VM within VirtualBox\n2. Attach the configured shared folder to the VM\n3. Attach the virtual harddisk, either as mutable or immutable\n4. Runs the VM\n5. Waits for the VM to be stopped\n6. Detach the harddisk\n7. Detach the shared folder\n8. Removes the harddisk and it's snapshots from the VirtualBox (snapshots will be removed)\n9. Unregisters the VM\n\nThe shared folder can typically be used for read/write storage, while the VM itself can be run in an immutable state. Configuration is done via `📝 Config.ini`.\n\n## Some Tips\n\nUse `📟 RunMutable.cmd` **only** when you actually want to make changes to (or update) the guest OS in the VM. Use the Shared folder for storage of data that needs to be accessible and mutable from within both the guest and host OS.\n \t\nUse `📟 Compact.cmd` utility to reduce the size of the virtual harddisks of the guest OS. Before doing this, make sure to clean up the guest OS, and, ideally, also 'zero clear' it's partitions (i.e. overwriting all unused space with zeros), so the disk can be compacted as much as possible.\n\nEach of the script files under `📁 Scripts` can be run separately. See `Scripts\\StartScript.cmd` for an example of the order in which they are normally ran. This can be useful for (step-by-step) debugging or when something may have gone wrong, like, for example when a previous run got interrupted and the VM didn't get properly unregistered with VirtualBox.\n\n## Known Limitations/Issues\n\n- \u003e [!WARNING] Snapshots are not supported yet and will be removed!\n- Only 1 virtual disk is supported.\n- The virtual disk is assumed to be connected to SATA port 0.\n- Only 1 shared folder (with a relative path) can be configured with this tool.\n- The shared folder is not auto-mounted, so you'll need to mount it yourself in the Guest OS (see below!).\n- The shared folder is always mounted as read/write.\n- The guest OS mount point for the shared folder cannot be specified yet\n\n## TODOs / Potential Future Improvements \n\n- Make `--automount` and `--readonly` for the shared folder configurable in the config file.\n- Add the ability to specify the guest OS mount point in the config file.\n- Automatically determine the UUIDs for VM and disks.\n- Add ability to add a few virtual harddisks in either mutable or immutable mode.\n- Support for disks different than SATA (e.g. IDE, SCSI, nVME)\n- Find a way to support snapshots.\n\n## Extra: How to mount the shared folder under a Linux Guest-OS\n\nTo mount a shared folder named `vboxshare` under Linux:\n\n```bash \nmkdir /home/\u003cuser\u003e/shared\nsudo mount -t vboxsf -o uid=1000,gid=1000 vboxshare /home/\u003cuser\u003e/shared  \n```\n\nOr mount the share at boot by putting it in `/etc/fstab`:\n\n```\nvboxshare    (/mnt/shared)    vboxsf    defaults,uid=(1000),gid=(1000),umask=0022    0    0\n```\n\nNote that for this to work edit `/etc/module` to add `vboxsf` so that it is present at boot-time.\n\n**Also:** In case we enabled auto-mounting those shared folders will automatically be mounted in the guest OS with mount point `/media/sf_vboxshare`. To have access to these folders users in the guest need to be a member of the group `vboxsf`.\n\n```bash\nsudo usermod -aG vboxsf $USER\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoineann%2Fportable-vbox-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoineann%2Fportable-vbox-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoineann%2Fportable-vbox-vm/lists"}