Ubiquiti released UniFi OS Server so you can host the UniFi controller on your own Linux computer. You does not need to buy expensive hardware like Cloud Key, Dream Machine, or UNVR anymore. This software bundles UniFi Network, identity, and the UniFi shell inside a single podman container. It also uses systemd to make sure it always run. I tested this on Ubuntu 24.04.4 LTS in May 2026 using UniFi OS Server version 5.0.8, container image 0.0.56, and podman version 4.9.3. If you have Ubuntu 22.04 LTS, it also works because Ubiquiti supports it. This guide show you how to install everything from start to finish without any complex steps.
You must to make sure your Linux box meets the requirements before you start. You need a computer with x86_64 CPU. The installer is a Linux binary file so it will not work on other CPU easily. For hardware, you need at least 2 vCPU, 4 GB of RAM, and 25 GB of free storage space. But if you want it to run nicer, you should use 4 vCPU, 8 GB of RAM, and 60 GB of disk space. The installer check your free space before it installs anything. If your disk is too full, the installer just stops and says error. You also need root power or a user that can use sudo commands. You need a free Ubiquiti account if you want to download the file and manage your server from the internet. If you want only local login, that also works. Your server also needs a static IP address on your local network because UniFi devices cannot find the controller easily if the IP keeps changing.
Step 1: Set reusable shell variables
First, we should to set some variables in our terminal session. This make copying and pasting commands much more easier because you only change the values once at the top. If you open a new SSH window later, you will need to set them again.
export UOS_HOST_IP="192.168.1.117" # change this to your server IP
export UOS_INSTALLER="/root/unifi-os-server.bin"
export UOS_WEBUI_PORT="11443" # this is the default web port
After you run that, you should check if the variables are correct. Run this command to see the output:
echo "Host IP: ${UOS_HOST_IP}"
echo "Installer: ${UOS_INSTALLER}"
echo "Web UI: https://${UOS_HOST_IP}:${UOS_WEBUI_PORT}/"
If you want these variables to stay even when you close the SSH, you can put the export lines at the end of your /root/.bashrc file.
Step 2: Update Ubuntu and install podman
The UniFi OS Server runs inside a podman container under a new system user called uosserver. If you does not have podman on your Ubuntu, the installer will fail very fast. So we must update the system and install podman first. Run these commands to update your package list and upgrade your packages:
sudo apt-get update
sudo apt-get -y upgrade
Now we install podman and uidmap. We need uidmap because podman uses it to map user IDs for security inside the container. We can install them together from the official Ubuntu repository:
sudo apt-get install -y podman uidmap
When the install is finished, check the version to make sure it is there. The installer will look for podman at /usr/bin/podman.
podman --version
which podman
You should see podman version 4.9.3 or something newer. The path must be /usr/bin/podman. If you do not see this, the installer will get angry and stop.
Step 3: Download the UniFi OS Server installer
The installer is a big binary file that has a size of around 818 MB. This file has the container image and all the systemd configuration files inside it. Ubiquiti hosts this file on their CDN network. You must go to ui.com/download/software/unifi-os-server with your web browser. Copy the download link for Linux x64. Then use curl on your server to download the installer file:
curl -fL --progress-bar \
-o "${UOS_INSTALLER}" \
"https://fw-download.ubnt.com/data/unifi-os-server/<your-signed-installer-url>"
You must change the URL with the real link you copied from the website because the link has special security keys that expire after some time. After downloading, check if the file is good and has the right size:
ls -lh "${UOS_INSTALLER}"
file "${UOS_INSTALLER}"
It should say it is an ELF 64-bit executable file and the size is about 818 MB. Now we must make it executable so we can run it:
chmod +x "${UOS_INSTALLER}"
Step 4: Run the installer
Now we run the installer file. This installer is interactive, so it asks you questions and shows what it is doing. It checks your hard drive space, checks if the ports are free, creates a user called uosserver, configures systemd, and starts the container. Run this command:
sudo "${UOS_INSTALLER}"
The installer asks you: “You are about to install UOS Server version X.Y.Z. Proceed? (y/N):”. You type y and press enter. You will see lines like this on your screen:
INFO Checking disk space for required directories...
INFO All disk space requirements met.
INFO Checking ports...
INFO Adding uosserver user and group...
INFO Setting up /usr/local/bin/uosserver binary...
INFO Initializing podman conf...
INFO Creating systemd services...
INFO Loading container image...
INFO Starting container...
INFO Container 'uosserver' is running. (elapsed: 0.0s)
INFO Waiting for UOS Server to start...
!!! INSTALLATION COMPLETE !!!
UOS Server is running at: https://192.168.1.117:11443/
This installation creates two systemd services. One is uosserver.service which keeps the container running. The other is uosserver-updater.service which updates the software in the background. Check if they are both running:
systemctl is-active uosserver
systemctl is-active uosserver-updater
Both commands should say “active”. You can also use the special command uosserver status to see more details:
sudo uosserver status
This command shows you if the podman container is healthy and if the systemd service is running fine.
Step 5: Open the firewall for UniFi traffic
The UniFi OS Server needs many network ports open so it can talk to your access points, switches, and the web browser. If you use UFW firewall on Ubuntu, you must allow these ports. If you do not open them, your UniFi devices will not show up in the controller. Run these commands to open the ports:
sudo ufw allow OpenSSH
sudo ufw allow 11443/tcp comment 'UniFi OS Server Web UI (HTTPS)'
sudo ufw allow 8080/tcp comment 'UniFi device inform'
sudo ufw allow 8443/tcp comment 'UniFi legacy controller'
sudo ufw allow 8880/tcp comment 'UniFi guest portal HTTP'
sudo ufw allow 8843/tcp comment 'UniFi guest portal HTTPS'
sudo ufw allow 3478/udp comment 'UniFi STUN'
sudo ufw allow 10001/udp comment 'UniFi device discovery'
sudo ufw allow 1900/udp comment 'UPnP/UniFi discovery'
We allowed OpenSSH first so we do not lose our connection. Now we can enable the firewall safely:
sudo ufw --force enable
sudo ufw status numbered
Now your firewall is active and only the correct ports can get through.
Step 6: Complete the first-run wizard
Now you open your web browser and go to https://<your-server-IP>:11443/. Because the server uses a self-signed security certificate, your browser will show a red warning. This is normal. You can click “Advanced” and then “Proceed” to open the page. Later, you can change the certificate in settings.
The first page will ask you to write a name for your UniFi OS Server. You should write a good name so you can identify it easily in the Ubiquiti cloud portal later. Click Next.
On the next screen, you must choose your login style. You can sign in with your UI account to get remote management from anywhere. If you don’t want cloud, you can choose to make a local account. This is good for people who do not want their data on the internet, but you will not get remote access from the mobile app easily.
Choose your option and click Next. The server will start setting up the Network application. This takes about one or two minutes. Behind the scenes, the server is starting MongoDB database, setting up RabbitMQ, and preparing your default site config. When it is finished, you will see a success screen. Click through and you will see the main dashboard with two tabs: UOS Server and Network.
Step 7: Adopt devices already managed by another console
If you had a different UniFi controller before, your devices like APs and switches will show up in the new controller but they will say “Managed by Another Console”. This happens because they still belong to your old setup. You have two ways to fix this.
Path 1: If you want to keep your settings, you must go to your old controller, go to Settings, then System, then Backups. Download the .unf backup file. Then go to your new UniFi OS Server, go to Settings, System, Backups, and upload that file. Your devices will connect to the new server automatically and keep all your Wi-Fi names and passwords.
Path 2: If you want a fresh start, you must log into your old controller, click on each device, and select “Forget”. This resets the devices to factory defaults. After a few seconds, they will show up on your new UniFi OS Server as “Pending Adoption”. You just click “Adopt” and they will join.
If your devices are on a different network subnet, they cannot find the server with UDP discovery. You must tell them where the server is. You can use DHCP option 43 on your router, or you can use SSH to log into the device. If you use SSH, connect to the IP of the access point with username ubnt and password ubnt. Then run this command:
set-inform http://192.168.1.117:8080/inform
Change the IP to your server’s IP. The device will show up in your controller web interface immediately, and you can click Adopt.
Step 8: Manage the service with uosserver
The installer gives you a tool called uosserver to manage the container easily. You can run it to see what commands you can use:
sudo uosserver help
It shows you these commands: start, stop, status, shell, support, and version. If you want to see what is happening inside the container, you can run sudo uosserver shell. This opens a terminal inside the container box. If you have a problem and need help from Ubiquiti, you can run sudo uosserver support to make a support file.
If you don’t want to type sudo every time you use this tool, you can add your user account to the uosserver group:
sudo usermod -aG uosserver "${USER}"
You must log out and log in again for this to work.
Step 9: Upgrade and uninstall
The server updates itself automatically because the uosserver-updater.service checks for new versions. If you do not want this and prefer to update manually, you can stop this auto-updater:
sudo systemctl disable --now uosserver-updater
If you want to update manually later, you just download the new installer file from Ubiquiti and run it again. It will automatically stop the container, update the files, and start it again without deleting your settings.
If you decide you don’t want this software anymore, you can delete everything. The installer has a purge command that deletes the container, the database, the configuration, and the users:
sudo uosserver-purge
It will ask you twice if you are sure. Once you say yes, all your data is gone forever, so make sure you have a backup file saved on your personal computer first.