Boot Runner 3 supports physical startup volumes as well as virtual machines, making it easy to offer selections of any combination of macOS, Windows, Linux, and other systems installed natively or in a virtual machine. Boot Runner 3 also includes customization options to make the startup selection screen easier for end users to both find and start the OS environment that they need.

Startup control with Boot Runner can be fully integrated with existing client management consoles using Configuration Profiles. The easiest way create a configuration profile is to use the Boot Runner 3 Profile web service. This Admin Guide includes details all available settings that can be controlled through profiles.

Create Profile

Installing Boot Runner Software and License

Find your download links in an email from us and download your software and license:

  • When you purchase Boot Runner, your download links will be in an email from orders@twocanoes.com.  If those links have expired or you can’t find that email, please redownload your software.
  • If you requested a trial version, you will find your download links in an email from info@twocanoes.com.  If your links or your trial license has expired, please contact us if you need an extension.


Install Software

Double-click BootRunner3.dmg to mount the disk image. Double-click Boot Runner.pkg and follow the installation instructions.

The installer places files in three locations:

  1. /Library/PrivilegedHelperTools/Boot Runner.app: This is the main Boot Runner app that runs over the Login Window
  2. /Library/LaunchAgents/com.twocanoes.bootrunner.plist: This LaunchAgent starts Boot Runner over the Login Window.
  3. /Library/LaunchAgents/com.twocanoes.bootlauncher.plist: This LaunchAgent starts a process to log out the current user whenever a file is created at /Users/Shared/.com.twocanoes.bootrunnerlogout. It is used for automatically logging out when a VM is closed.

Install License

Click the Boot Runner license file.

Type your admin password to allow the license installation.

License Location

The location of the Boot Runner 3 license is:

/Library/Application Support/Twocanoes/Licenses/

The license file can be copied to this location and Boot Runner will discover and use the license key. If there are multiple license keys for Boot Runner in this location, Boot Runner will use the first valid license key based on alphabetical order.


The Boot Runner selection screen appears at startup or following logout from macOS. Bootable volumes are presented as selectable disk icons. The user interface can be customized to reflect how your organization uses Boot Runner and your brand. The Boot Runner interface elements are:

  1. Countdown Timer – When a volume is selected automatically via settings, the Countdown Timer is shown to alert the user that a restart is pending. The amount of time is customizable.
  2. Popover – The popover appears above each volume and gives more information about the operating system or applications on the volume. The text is customizable and when popover can be customized.
  3. Disk Icon –  The Disk Icon is the icon that represents the disk. The Disk Icon can be customized with an image specified in settings.
  4. OS Badge –  The OS Badge is a badge that identifies the operating system for the volume. It appears in the lower right corner of the Disk Icon.
  5. Disk Label – The Disk Label is a line of text that identifies the name of the volume. By default, it is the name of the volume filesystem, but can be customized via settings.
  6. Marquee Text – The Marquee text is a line of text that provides up-to-date information to the user. It can be customized and animated in settings. The font family name, size, and color can also be customized.
  7. Shutdown and Restart Buttons – The Shutdown and Restart buttons provide an easy way for users and administrators to shutdown and restart the computer. Both buttons can be shown or hidden independently in settings.
  8. Status Box – The Status Box shows the version and build of Boot Runner, the version of macOS, and the current time. It can be shown or hidden based on settings.
  9. Background Image – The Background Image is a full screen image that appears under all the Boot Runner controls. It can be specified in settings.

Initial Setup

The Boot Runner Selection Screen runs on top of the macOS login screen.  In order for Boot Runner to display the Selection Screen containing the available start up disks, Automatic Login must be disabled on the client system. Go to System Preferences-> Users and Groups-> Login Options and Set “Automatic Login” to Off.

When using virtual machine volumes, the Login window must be set to “Name and password.” Go to System Preferences-> Users and Groups-> Login Option and set “Display Login window” to “Name and password.”

SIP and Secure Boot

System Integrity Protection (SIP) is a feature of macOS that prevents modifications of system related files. It also protects the area where the startup disk is changed (NVRAM).  In order for Boot Runner to change the startup disk and boot into a different OS, SIP must be configured to allow for Boot Runner to set the startup disk:

    1. Boot into the recovery partition by holding Command-R while restarting the Mac.
    2. From the Utilities Menu, select Terminal.  On the Terminal command line, enter:

csrutil enable --without nvram

Restart back into the Mac volume.

See this article for more information.

Secure Boot is currently only available on the 2017 iMac Pro and prevents unknown operating systems from being selected. Boot Runner is able to select macOS and Windows 10 with Secure Boot enabled and does not require any special configuration. For Operating Systems that Secure Boot does not recognize, it can be disabled from the Recovery Partition.

Customizing Boot Runner Settings

Boot Runner settings are customized via configuration profiles created by a online service provided by Twocanoes. A free account can be created and multiple configuration profiles can be created, modified, and exported. To get started, visit:


Basic Settings

When first creating a configuration, give the profile a name and fill out the Basic Settings:

  1. Name – The name of the configuration profile. This will be the filename of the configuration profile when exporting.
  2. Custom background path – Desktop pictures or any standard format image may be used (formats include .jpg, .tif, .png, .pdf). Enter the path to the desktop image. The image must be a local path and be available on each Mac. The image will be scaled to the full screen, but should be as close to the screen resolution of the Macs as possible.
  3. Automatically select volumeUse the device name or identifier to select a default boot volume.
  4. Between Times – You can specify the time period when this default will be in effect and Boot Runner will automatically reboot and boot into the specified volume.  
  5. Limit days – You can specify the days that restarting will take place.
  6. Timeout – The amount of time that the user is given before the Mac is restarted.
  7. Hide volumes – Enter the name or device of any bootable volumes that you do not want displayed in the Boot Runner Selection Screen.
  8. Initially selected volume – When Boot Runner is shown, the default behavior is to select the startup Mac volume.  You can specify the name of another volume if you would like that volume to be selected at start.
  9. Show unmounted volumes – Enter the name or device of any bootable volumes that you do not want displayed in the Boot Runner Selection Screen. By default, Boot Runner will show all volumes that are mounted at startup. If you wish to enter more than one volume in these fields, separate the values with a comma.
  10. Click Apply to save the configuration.

Boot Runner Volume VM Config

The Boot Runner Volume VM Config section is where each volume and associated descriptions are located. Add a volume to the volume descriptions list in order to customize information for the Selection Screen.

  1. OS is a Virtual Machine – If the Boot Runner volume is an virtual machine (VMWare Fusion, Parallels, or VirtualBox), select this checkbox. When this option is selected, the Name or Identifier text field will be disabled and you can only specify a Volume Label.
  2. Name or Identifier – The volume name or device ID used when mounted in macOS. The volume name is the name shown on the mounted volume in this Finder window and mounted on the desktop. 
  3. Volume Label – Enter a name that users will see below the volume on the Boot Runner Selection Screen. 
  4. Operating SystemClick to select the appropriate operating system or choose “Auto Detect.” Note: Auto Detect will not work with unmounted volumes. The selection of operating system will determine the icon that shows up next to each disk and the icon in the popover description.
  5. Custom Disk Icon Path – A local path to a 512 x 512 pixel png image for the Disk Image. The image must be available locally on each Mac.
  6. Popover text – Enter text to describe the volume. This text will be displayed in a popover above the volume on the main selection screen. The text may be formatted as needed.
  7. Path to RTF File – Enter the path location to an RTF format text document containing descriptive information about the volume. The document must be in Rich Text Format (RTF, TextEdit can create RTF formatted documents) which allows basic text formatting without images. The RTF file must be available locally on each Mac.

VM Config

Virtual machines have some additional options. Virtual machines are automatically launched by Boot Runner by logging into a standard macOS account and launching the virtual machine. In order to do this, Boot Runner must know the username and password of a macOS user account and the VM to launch. Specify the options as shown below:

  1. OS X username – The username (shortname) of the macOS account to log into.
  2. OS X password – The password in macOS for the user account.
  3. Run Command – After the user selects the virtual machine, Boot Runner will log into the user account and launch the command specified here.  It is usually the command “open -F” that will automatically launch the specified virtual machine document. The virtual machine must be installed in the user account and set to enter full screen.

Boot Runner also has a feature where when a file at /Users/Shared/.com.twocanoes.bootrunnerlogout is created, the current user session will log out. Share this folder to the VM and create a script in the virtual machine to automatically create this file when the user is logs out from the host OS. This will force the VM to save the session after the user logs out and then logs out from the macOS session, returning to the Boot Runner selection screen.

Boot Runner Marquee Options

The Marquee displays stationary or animated text on the Boot Runner Selection Screen.

  1. Marquee text – Enter text that will scroll across the Boot Runner Selection Screen.
  2. Marquee text position – Choose the position (top or bottom of the screen) for text.
  3. Marquee text position vertical – Vertical position of marquee text in pixels from 0 (bottom of screen) to the top (dependent on resolution).
  4. Marquee on screen Time –  The amount of time, in seconds, that the marquee pauses on screen during an animation.
  5. Marquee text color – The color of the text can be customized here.
  6. Marquee font name – The font family name for the Marquee.
  7. Marquee font size – The size of the Marquee font.
  8. Scroll marquee – Marquee text slides in to the middle, pauses, then slides out.
  9. Scale marquee – Marquee text zooms in, pauses, then disappears.
  10. Marque off screen timeWhen the marquee text is animated, it can stay off screen for the amount of time specified here.

Configuring Boot Runner: Additional Options

The bottom of the Boot Runner Config window contains settings for the Boot Runner Selection screen, the Boot Runner Menu Item, and display options for restart and shutdown buttons.

  1. If a single Mac volume, bypass Boot Runner – Check this box to bypass running Boot Runner on single volume OS X Macs. For mass deployments where some Macs only host one bootable volume, the Boot Runner Selection Screen will not appear unless additional boot volumes are added. 
  2. Show shutdown button – Display a shutdown button on selection screen
  3. Show popover – Show or Hide popovers above volumes
  4. Hide status bar – This option allows you to hide or show this status box at the bottom of the screen.
  5. Timeout – When a user selects the macOS volume but does not log in, the Boot Runner selection screen will be shown after the specified timeout.
  6. Force boot type – Normally, Boot Runner 3 will detect the style of booting for selected volumes. However, if you want to override this settings, specify a boot type.
  7. Show restart button – Display a Restart button on selection screen
  8. Hide return button – After a user selects the startup volume, a Return to Boot Runner button will be shown.  Use this setting to hide this button.
  9. Show popover on start – By default, when the selection screen is first shown, the popover information is shown automatically. Use this setting to hide the initial popover from showing.
  10. Select no volumes on start – The Mac startup disk is selected by default. Use this option to turn off initial selection.
  11. Disk label font size – The size of the disk label text shown under the Volume icon.

Privacy Controls

macOS 10.14 Mojave has new privacy controls for protecting user data. Once of these controls must be configured for full functionality of Boot Runner.

When the Boot Runner screen is activate, it appears over the macOS Login Window but does not have focus; anything typed on the keyboard is not sent to Boot Runner. Users can still select volumes with the pointer, but in order to select volumes with the keyboard, Boot Runner must have the ability to control the mouse. To enable this feature:

  1. In macOS, open System Preferences and select Security & Privacy.
  2. Select the Privacy tab.
  3. Unlock System Preferences by clicking the lock in the lower left corner.
  4. Select Accessibility and under Allow the apps below to control your computer, click +.
  5. Select Boot Runner.app in /Library/PrivilegedHelperTools.
  6. Quick System Preferences

If your Macs are managed by an MDM server, you can set the Accessibility configuration key. See Configuration Profile Reference for more information.

Installing Configuration Profiles

After creating a configuration profile via the web service, export the configuration profile and apply it to all the Macs that will have Boot Runner installed. To install a configuration profile for Boot Runner manually, double click on the configuration profile or use the profiles command to install it. To install a configuration profile via the command line, use the profiles command in the Terminal application. More information on the profiles command can be found in the manual by opening Terminal and typing man profiles.

For example:

sudo profiles -I -F ~/Desktop/com.twocanoes.bootrunner.mobileconfig

The configuration profiles can be deployed using MDM.

Configuration Profile Keys

CustomBackgroundPath – (string) location of local image file for selection screen background (TIFF, PNG, JPG, or PDF)

HiddenVolumeNames – (string) name or identifier of existing volume that should not appear in selection screen, separate multiple volume names with commas

AutomaticallySelectVolume – (string) name or identifier of existing volume to be selected and booted automatically

AutoSelectTimeout – (integer) delay in seconds between when selection screen appears and when auto selection and booting begins

LimitTimeFrom – (integer) start of period when specified volume should automatically be selected and booted, range from 0-23

LimitTimeTo – (integer) end of period when specified volume should automatically be selected and booted, range from 0-23

LimitTimes – (boolean) yes/no to activate LimitTimeFrom and LimitTimeTo

ShowUnmountedVolumes – (string) name or identifier of volume (usually external drive) that may not always be mounted but will appear in the selection screen.

ForceBootType – (integer)  an integer that determines the how the selected volume boots. 1: EFI, 2: Legacy, 3: Volume EFI. If this key is not specified, the boot type will be autodetected based on the OS installed and Mac hardware.

VolumeDescriptions – (array) key-value clusters for each volume, not editable. Volume property sets assigned by Item number dictionaries (Item 0, Item 1, Item 2, etc)

  • VolumeName – (string) name or identifier, disabled for virtual machine volumes
  • VolumeLabel – (string) displayed under the volume graphic
  • VolumeType – (integer) Operating System icon. 0-auto-detect, 1-OS X, 2-Windows XP, 3-Windows 7, 4-Windows 8, 5-Windows 10, 6-Linux, 7-Other, 8-Custom
  • VolumeDescriptionRTF – (string) encoded raw text entered into the popover text window. VolumeDescriptionRTF takes precedence over Volume Descriptions if both keys are present
  • VolumeDescriptions – (string) path to a rich-text format, base64-encoded file containing the popover text (not to be confused with the array of the same name)
  • VMPath – (string) path, including open command to launch the virtual machine
  • VMUsername – (string) OS X login name to auto-login and launch virtual machine
  • VMPassword – (string) OS X password to auto-login and launch virtual machine
  • UseVM – (boolean) yes/no
  • LogoutFile – (string) name of touched file, defaults to /Users/Shared/.com.twocanoes.bootrunnerlogout
  • VMPostrunScript – (string) path to script file for actions post-vm logout/shutdown. Defaults to /Library/Application Support/Twocanoes/Boot Runner/logoutscript
  • CustomVolumeGraphic – (string) path to customized image used as icon overlay on volume and in popover, 256 x 256 works best
  • CustomDiskGraphic – (string) path to customized image used instead of default disk icon, 512 x 512 works best

TypingDelay – (integer) in nanoseconds to delay between keystrokes when auto-login VMUsername and VMPassword are enabled.  It should be a number value between 0 and 100,000,000 (100 Million is 1 second). Default is 0

MarqueeText – (string) contents of marquee text that appears on the selection screen

MarqueeTextPosition – (integer) integer value that defines where to place the marquee text. Zero (0) shows at top of screen, one (1) shows it at the bottom of the screen

MarqueeTextColor – (string) Hex Colors (example #0A0A0A)

MarqueeFontName – (string) A name for the font family for the Marquee

MarqueeFontSize – (string) The size of the marquee text in points

MarqueeYPosition – (integer) vertical position of marquee text in pixels. Default is 0. Positioning is dependent on display resolution, for example a 1920 x 1200 display has MarqueeYPosition range of 0 (bottom) to 1200 (top)

ScrollMarquee – (boolean) value for scrolling of marquee text across the screen

SelectSingleMacVolume – (boolean) for behavior to bypass Boot Runner whenever there is only a single Mac volume on the system

ShowRestartButton – (boolean) option to display a restart button at bottom of selection screen

ShowShutdownButton – (boolean) option to display a shutdown button at bottom of selection screen

Timeout – (integer) Time in seconds from when the OS X login screen is displayed without keyboard/mouse activity before returning to the Boot Runner selection screen

WindowLevel – (integer) BR default is screen saver window level (9).  Can specify 0 – 9. See window level constants: http://apple.co/1aRwMh1

Logging Options

Boot Runner logs messages via the Apple System Logger.  To view the logs, open Terminal and enter in the following command:

log show --style syslog --predicate 'process contains[cd] "Boot Runner"' --info --last 2d

You can adjust the “2d” for a longer or shorter time period.  You can specify a number and then m (minutes) h (hours) or d (days). For example: “–last 2m” or “–last 3h”.

To send the output to a file, redirect the output:

log show --style syslog --predicate 'process contains[cd] "Boot Runner"' --info --last 2d > ~/Desktop/bootrunner.log

This will save the last 2 days of Boot Runner output to a file on the current user’s desktop called “bootrunner.log”.

Additional Options

Boot Runner supports some additional options.

  1. If there is a file at the top of a volume named “.bootrunner.rtf” (note the period at the start of the name) and a volume description is defined via a policy, configuration profile, or preference, text contained in the RTF file will be shown as the description text in the Boot Runner Selection Screen.
  2. To set Windows to reboot on logout, create a script that contains the command shutdown -r -f -t 0. In gpedit.msc, go to User Configuration > Windows Settings > Scripts and add the script to the Logoff item.
  3. OS X will unmount any volumes contained on removable drives when the user logs out, and will also unmount them if the removable drives are plugged when the Login window appears. In order to see external drives at the Login window, run the following defaults command:

 sudo defaults write /Library/Preferences/SystemConfiguration/autodiskmount AutomountDisksWithoutUserLogin -bool true