vbox-windows-app-launcher

A tool for launching Windows applications in a VirtualBox environment.

Description

vbox-windows-app-launcher is a utility designed to seamlessly launch Windows applications within a VirtualBox virtual machine. This tool is particularly useful for users who need to run Windows applications in an isolated environment or on systems where native installation is not possible or desired.

This adds a feature that I was missing since I moved over from Parallel Desktop on macOS to VirtualBox on Linux. Similar to the "Open in VM" feature in Parallel Desktop, this script allows you to open various documents in a VirtualBox VM directly from the host system's file manager.

Attribution

This project was inspired by andpy73, sbnwl, 3Pilif, and TVG and is based on this forum thread: https://forums.virtualbox.org/viewtopic.php?t=91799&sid=fe97378eec124475e838cf6ea5ea79e3&start=15

Features

• Easy launch of Windows applications in a VirtualBox VM
• Seamless integration with host system
• Configurable VM settings
• Automatic VM startup and user login detection
• Optional automatic window focus and desktop notifications
• Desktop integration for easy file opening

Installation

From AUR (Arch Linux)

yay -S vbox-windows-app-launcher-git
# or
paru -S vbox-windows-app-launcher-git

Then create your config (see Configuration below). If you already have a user account, copy the sample and set permissions (config path follows XDG; default is ~/.config/):

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}"
cp /etc/skel/.config/vbox-windows-app-launcher/vbox-windows-app-launcher.conf.sample "${XDG_CONFIG_HOME:-$HOME/.config}/vbox_windows_app_launcher.conf"
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/vbox_windows_app_launcher.conf"
# Edit and add your VM name, user, password, and paths

Manual installation

1. Clone this repository or download the script files.
2. Make sure you have VirtualBox installed on your system.
3. Install the optional dependencies if you want auto-focus or desktop notifications. For example on Arch Linux:

   sudo pacman -S dunst wmctrl

   • dunst: notification daemon used for desktop notifications
   • wmctrl: window manager control used for automatic window focus
4. Copy the sample config and restrict permissions (the config contains your VM password; the script will refuse to run if the file is readable by others). Config path uses $XDG_CONFIG_HOME (default ~/.config/):

   mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}"
   cp vbox_windows_app_launcher.conf.sample "${XDG_CONFIG_HOME:-$HOME/.config}/vbox_windows_app_launcher.conf"
   chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/vbox_windows_app_launcher.conf"

   Then edit the config file with your settings.
5. Make the script executable:

   chmod +x vbox_windows_app_launcher.sh

6. Edit the open-windows-app-in-vm.desktop file:
   • Update the Exec= line with the correct path to your vbox_windows_app_launcher.sh script:

     Exec=/path/to/your/script/vbox_windows_app_launcher.sh %f
     

7. Install the desktop file for easy file opening:
   • For local installation (current user only):

     mkdir -p ~/.local/share/applications
     cp open-windows-app-in-vm.desktop ~/.local/share/applications/

   • For global installation (all users, requires sudo):

     sudo cp open-windows-app-in-vm.desktop /usr/share/applications/

8. Update the desktop database (for local installation):

   update-desktop-database ~/.local/share/applications

Usage

1. Configure your settings in $XDG_CONFIG_HOME/vbox_windows_app_launcher.conf (default ~/.config/...; permissions must be 600). Path mapping is optional: if you set no VM_SHARE_PATH / VM_DRIVE_LETTER, the script discovers drive letters from the guest (runs net use in the VM and parses the output). If you set VM_SHARE_PATH and VM_DRIVE_LETTER (or _2, …), only those paths are used and no autodiscovery is done.

2. Double-click on any file or folder to open it in the VM, or run the script directly:

   • If installed via AUR: vbox-windows-app-launcher /path/to/file_or_folder
   • If run from repo: ./vbox_windows_app_launcher.sh /path/to/file_or_folder

The script will automatically use the appropriate application in the VM to open the file or folder.

Configuration

Edit $XDG_CONFIG_HOME/vbox_windows_app_launcher.conf (default ~/.config/vbox_windows_app_launcher.conf) with your specific settings:

• VM_NAME: Name of your VirtualBox VM
• VM_USER: Username in the VM
• VM_PASSWORD: Password for the VM user
• Path mapping (optional): if not set, the script discovers drive letters from the guest (net use in the VM). If set (VM_SHARE_PATH + VM_DRIVE_LETTER, and optional VM_SHARE_PATH_2 + VM_DRIVE_LETTER_2, …), only those paths are used and no autodiscovery is done.
• AUTO_FOCUS: Set to true/false to enable/disable automatic window focus
• SCRIPT_TIMEOUT: Timeout for the script in seconds
• NOTIFICATION_TIMEOUT: Timeout for notifications in milliseconds

Optional (see sample config for defaults): VM_START_TIMEOUT, VM_START_POLL_INTERVAL, ERROR_NOTIFICATION_TIMEOUT, VM_POWERSHELL_EXE.

Config file permissions: The file contains your VM password. It must not be readable by others (e.g. chmod 600 on the config file). The script checks this on launch and shows a desktop notification and exits if permissions are too loose.

See vbox_windows_app_launcher.conf.sample for the full list of options.

Requirements

• VirtualBox
• Windows applications installed in a VirtualBox VM
• Bash shell

Optional dependencies

• dunst (for notifications)
• wmctrl (for window management)

Troubleshooting

Config file permissions

If the script shows a notification like "Config file has insecure permissions (readable by others)", fix it with:

chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/vbox_windows_app_launcher.conf"

Guest login restricted

If you encounter the following error:

VBoxManage: error: Waiting for guest process failed: The specified user account on the guest is restricted and can't be used to logon
VBoxManage: error: Details: code VBOX_E_IPRT_ERROR (0x80bb0005), component GuestSessionWrap, interface IGuestSession, callee nsISupports
VBoxManage: error: Context: "WaitForArray(ComSafeArrayAsInParam(aSessionWaitFlags), 30 * 1000, &enmWaitResult)" at line 770 of file VBoxManageGuestCtrl.cpp

That can potentially mean that your password expired and that you need to reset it in the VM. You can do that while being logged in and in an administrator command prompt:

net user WindowsAccountName *

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. This project was initially developed with contributions from andpy73, sbnwl, 3Pilif, and TVG.

License

This project is open-source. This has no specific license.

Support

For support, please open an issue in the GitHub repository or contact the maintainers.

Desktop Integration

The open-windows-app-in-vm.desktop file provides desktop integration for easy file opening. It associates common file types (Office, PDF, AutoCAD/DXF, Adobe PSD/AI/INDD/EPS) with the launcher. The script accepts both plain paths and file:// URLs from the file manager.