If you're running Home Assistant in a VirtualBox VM on an older Mac, you've probably already hit the first question: how do I make it start automatically when the Mac boots up?

This guide walks through the exact steps to launch a Home Assistant VM in headless mode (no GUI window) every time macOS starts — including surviving power outages without any manual intervention. It was tested on a Mac mini (Late 2012) running macOS 10.15.7 Catalina with VirtualBox 6.1, but the process works on any macOS version that supports VirtualBox and LaunchAgents.

Why This Matters for a Home Energy Monitor Setup

I bought two Refoss EM16P whole-home energy monitors to track power usage across multiple breaker boxes. Home Assistant is the hub that collects and visualizes all that data. The problem is obvious: if the Mac reboots after a power outage and the VM doesn't come back up automatically, I lose monitoring until I physically walk over and start it. That defeats the entire purpose of a "set it and forget it" home lab.

The solution is a macOS LaunchAgent — a built-in mechanism that runs a command when your user session starts — combined with a couple of system settings for power failure recovery.

Prerequisites

Before you start, make sure you have:

  • macOS 10.15.7 (Catalina) or a similar version. If you're on macOS 11 or newer, VirtualBox 7 works. For Catalina and older, you need VirtualBox 6.1.
  • VirtualBox installed with a working Home Assistant VM. Follow the official Home Assistant macOS installation guide if you haven't set this up yet.
  • Full Disk Access granted to Terminal. Go to System Preferences > Security & Privacy > Privacy > Full Disk Access and add Terminal.

Note on VirtualBox versions: VirtualBox 7 dropped support for anything below macOS 11 (Big Sur). If you're running Catalina (10.15) like I am, VirtualBox 6.1 is the latest compatible version. It runs Home Assistant's VM image without issues.

Step 1: Find Your VM's UUID

Every VirtualBox VM has a unique identifier (UUID). Using the UUID instead of the VM name in automation scripts is more reliable — it won't break if you rename the VM later.

Open Terminal and run:

VBoxManage list vms

You'll see output like this:

"Home Assistant" {68f2c834-9b77-4016-9e1a-27101030acfd}

Copy the long string inside the curly braces. That's your UUID — you'll need it in the next step.

Step 2: Create the LaunchAgent Plist

A LaunchAgent is macOS's built-in way to run tasks automatically when a user logs in. You're going to create a small configuration file that tells macOS to start your Home Assistant VM in headless mode every time your session begins.

In Terminal, open the file in a text editor:

nano ~/Library/LaunchAgents/org.homeassistant.vbox.plist

Paste the following, replacing YOUR_UUID_HERE with the UUID from Step 1:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.homeassistant.vbox</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/VBoxManage</string>
        <string>startvm</string>
        <string>YOUR_UUID_HERE</string>
        <string>--type</string>
        <string>headless</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>

Save and exit: press Ctrl+O, then Enter, then Ctrl+X.

What each key does

  • Label — A unique identifier for this background task.
  • ProgramArguments — The command to run. VBoxManage startvm <UUID> --type headless starts the VM without opening a GUI window.
  • RunAtLoad — Tells macOS to execute this command as soon as the LaunchAgent loads (at login).
  • ProcessType: Background — Marks this as a low-priority background process so it doesn't interfere with your login experience.

Step 3: Load the LaunchAgent

Tell macOS to register and activate the LaunchAgent:

launchctl load -w ~/Library/LaunchAgents/org.homeassistant.vbox.plist

Do not use sudo here. The VM is registered under your user account, not the system root. If you load the agent with sudo, macOS will run it as root — and root can't see your user's VMs. This is one of the most common mistakes.

To confirm the agent loaded successfully:

launchctl list | grep org.homeassistant.vbox

You should see a line with org.homeassistant.vbox. If the middle column shows 0, it loaded and ran successfully. If it shows 78, see the troubleshooting section below.

Step 4: Set Up Power Failure Recovery

The LaunchAgent handles starting the VM at login. But after a power outage, your Mac won't boot or log in by itself unless you configure two additional settings.

Enable Automatic Login

Go to System Preferences > Users & Groups > Login Options and set Automatic Login to your username. This ensures macOS logs into your account without waiting for a password, which triggers the LaunchAgent.

Enable Auto-Start After Power Failure

Go to System Preferences > Energy Saver and check "Start up automatically after a power failure."

With both settings enabled, the recovery chain works like this:

  1. Power goes out
  2. Power comes back
  3. Mac boots automatically (Energy Saver setting)
  4. macOS logs into your account automatically (Automatic Login)
  5. LaunchAgent fires and starts the Home Assistant VM in headless mode
  6. Home Assistant comes online — no manual intervention needed

How to Verify the VM Is Running

Since headless mode means there's no window, you need to check from Terminal:

VBoxManage list runningvms

If your VM's UUID appears in the output, Home Assistant is running in the background. You can then access the Home Assistant dashboard at http://<your-mac-ip>:8123 from any device on your network.

Troubleshooting

The "Error 78" Problem

This is the most common issue. If you run launchctl list | grep org.homeassistant.vbox and see 78 in the status column, macOS is blocking the background process due to insufficient permissions.

The fix: Go to System Preferences > Security & Privacy > Privacy > Full Disk Access. Click the lock to make changes, then click + and add both of these paths:

  • /usr/local/bin/VBoxManage
  • /bin/bash

Use Cmd+Shift+G in the file picker to type these paths directly. After adding them, unload and reload the agent:

launchctl unload ~/Library/LaunchAgents/org.homeassistant.vbox.plist
launchctl load -w ~/Library/LaunchAgents/org.homeassistant.vbox.plist

Permissions and Ownership Issues

If you accidentally used sudo to load the agent or create log files, the system (root) owns the process. Since the VM is registered under your user account, root won't be able to find it and the start command will fail silently.

The fix: Always run launchctl commands as your standard user — no sudo. If files were created as root, remove them:

sudo rm /tmp/vbox_ha.*

Then unload (with sudo, since root loaded it) and reload without sudo:

sudo launchctl unload ~/Library/LaunchAgents/org.homeassistant.vbox.plist
launchctl load -w ~/Library/LaunchAgents/org.homeassistant.vbox.plist

VM Starts But Home Assistant Dashboard Is Unreachable

If VBoxManage list runningvms shows the VM is running but you can't access the dashboard:

  • Wait 2-3 minutes. Home Assistant takes time to fully boot inside the VM.
  • Check the VM's network adapter is set to Bridged mode in VirtualBox settings so it gets its own IP on your local network.
  • Verify the IP by checking your router's connected devices list or running VBoxManage guestproperty get <UUID> "/VirtualBox/GuestInfo/Net/0/V4/IP".

Frequently Asked Questions

Does the VM survive a macOS restart (not just boot)?

Yes. The LaunchAgent runs every time your user session starts — whether that's a fresh boot, a restart, or logging back in after logging out.

Can I stop the VM without removing the LaunchAgent?

Yes. Use VBoxManage controlvm <UUID> acpipowerbutton for a graceful shutdown or VBoxManage controlvm <UUID> poweroff for an immediate stop. The LaunchAgent only triggers at login, so it won't restart the VM until your next login.

Will this work with VirtualBox 7 on newer macOS?

Yes. The LaunchAgent configuration and VBoxManage commands are the same across VirtualBox 6 and 7. The only difference is which VirtualBox version your macOS supports.

What if I have multiple VMs to auto-start?

Create a separate plist file for each VM with a unique Label (e.g., org.homeassistant.vbox2) and the corresponding UUID. Load each one with launchctl load -w.

Is there a security risk with Automatic Login?

Yes — anyone with physical access to the Mac can access your account. For a dedicated home lab machine like a Mac mini sitting in a closet, this is usually an acceptable trade-off. If you're concerned, consider using macOS's built-in firewall and ensuring the Mac isn't accessible from outside your local network.