Developing software in the Real World

Run the UniFi Controller headless on Mac

I’m running a UniFi network here with wireless access points, the Security Gateway and a PoE switch. It seems to be a robust system and is almost certainly overkill, but reliability is high on my lists after bad experiences with a NetGear WiFi router.

The UniFi system software is called the Controller and runs on a various operating systems. As I have a Mac mini here, I decided to run it on there. Weirdly, however it runs as a GUI application which means that I have to be logged in. There’s no need for that though as by scouring the Internet I discovered that we can run it headless via launchd.

Firstly we create /Library/LaunchDaemons/com.unifi.controller.service.plist. This file has to be owned by root with group of wheel:

This is a fairly standard launchd plist file file. However, the controller software is written in Java, but as Ubiquiti no longer bundle a copy of Java, we need to install our own copy of Java 8:

(You may need change the path to where your Java 8 is installed.)

This means that when Ubiquiti updates the bundled Java, our service continues to work. We also need to set the working directory to the Resources directory of the app bundle as it doesn’t work otherwise…

Update: Since this post was written, Ubiquiti no longer bundle Java, I have updated appropriately based on the comment from Wade Gibson.

Secondly, we install the service:

Now, the Controller is always running and we can access it on https://localhost:8443 and manage our UniFi network to our heart’s content!

24 thoughts on “Run the UniFi Controller headless on Mac

  1. Hi Rob….

    What an amazing article….. I have read pages and pages worth of complex solutions and articles on Unifi forum but your methos got me up and running less than 2min.

    Thanks million for this post

  2. Forgive a silly question:
    First install and get the controller working, as gui, no?
    Does it matter the controller version?

    Thank You!

  3. Hello all,
    it indeed worked.
    Just to add, maybe it will help somebody –
    to create plist owned by root and with group wheel you have to manually create plist file with that name (lets say on desktop), copy it to LaunchDaemons and use terminal:

    and then start service

    Thanks rob for quick help.

  4. Hi all, I have rolled the above including Raul’s comments. Only difference is using folder LaunchAgents.

    Does not load on reboot, but wors when I sign in, I don’t have to launch app.

    I would like it to run on reboot, without logging in. please help

  5. It took a little digging around, but changing this line in the plist with the new Java path seems to work. You have to put quotes around it since the path has a space.

    1. You are a life saver! Every time the controller is updated, I've literally been copying and pasting the bundled version of Java from an older versions of the Controller into the new package. I knew there had to be a way to point to the manually installed version of Java.

      Still really frustrating the Ubiquiti unbundled Java (though it appears to be due to Oracle's terrible licensing), and even worse that the Controller is still written in Java…

  6. Rob- I've been looking, for weeks now, for a fix to my not launching on my mac. I tried everything on the Ubiquity community pages and zilch. This did the trick – along with additional feedback from Raul and Wade. Thank you all!

  7. To run UniFi controller as a faceless app with version 5.12.66 simply did the change in Info.plist file
    change "ui" to "start"


    Then run:

    After that you can do whatever you want, e.g. use launchd





    Unifi Manager

    1. That last bit, enabling it from launchd – a few questions:
      Do you remove the LaunchDaemon plist file that we created based on this post?
      You have the settings, but I'm using old school editor (vi) so it would help see all the xml tags, can you put your contents of com.ubiquiti.unifi.plist in this thread?

      Thank You

  8. Pingback: Making Game: How do I run Ubiquiti's UniFi Network Controller on macOS? - TECHPRPR
  9. Pingback: Linux HowTo: How do I run Ubiquiti's UniFi Network Controller on macOS? - TECHPRPR
  10. Hello!

    I did the steps and also chowned the plist to root.
    Unfortunately i am also running openHab on this machine and if i try to acces localhost:8443 i am forwarded to my openhab isntance (normally port 8080).
    Is there anything i can do?

    Thank you!

  11. Hello!

    I have a problem accessing the UI. I also have OpenHab installed and when i acces localhost:8443 it forwards me to the openhab instance … 9000 is grafana. any thoughts?
    If i try to open the app manually it says java is not installed – but it was successfully installed via brew (following your guide).

    Thank you!

  12. Hi Rob, thanks for the article. My setup is the same and I will be ordering an EdgeRouter and the unifi 6 lite but do your instructions continue to be valid? I see that you last commented on Oct 6 2020 which is a few months after I write this note.

      1. Hi Rob,

        I have to read your article in detail and follow the steps carefully but are you running the latest controller?

        Just another analysis, folks appear to choose running the UniFi controller in a VM locally or on a cloud service, purchasing dedicated hardware from Ubiquity, or running it in docker etc, … your approach appears to be very cost effective as RAM and CPU are kept to a bare minimum as the native app runs headless in the background.

        What is the CPU/RAM toll this has on your mini?

        I want to mimic your steps because I have a Core2Duo Mac mini which runs a small SFTP server so why not have it do one more task right?

        I found your article just in time! Thank you for sharing this with those stumbling by.

        1. To be honest, the easiest way is to just run the UniFi controller with the GUI visible. This means that the Mac has to be logged in at all times though. The next easiest is to get a CloudKey 2 as it's built for it. I'm cheap as I already have the Mac. It doesn't use a noticeable amount of CPU/RAM.

Thoughts? Leave a reply

Your email address will not be published. Required fields are marked *