Dev Notes

open-webui setup on macOS

Here’s how to set up Open WebUI as a launchd service on macOS.

Prerequisites

First, install Open WebUI via uv if you haven’t already:

uv tool install open-webui

1. Create the plist file

cat > ~/Library/LaunchAgents/com.user.openwebui.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.user.openwebui</string>
  <key>ProgramArguments</key><array>
    <string>$HOME/.local/share/uv/tools/open-webui/bin/open-webui</string>
    <string>serve</string>
    <string>--port</string>
    <string>8081</string>
  </array>
  <key>WorkingDirectory</key><string>$HOME</string>
  <key>EnvironmentVariables</key><dict>
    <key>HOME</key><string>$HOME</string>
    <key>WEBUI_SECRET_KEY_FILE</key><string>$HOME/.webui_secret_key</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>$HOME/Library/Logs/openwebui.log</string>
  <key>StandardErrorPath</key><string>$HOME/Library/Logs/openwebui.err</string>
</dict></plist>
EOF

Save the plist to ~/Library/LaunchAgents/com.user.openwebui.plist. Before doing so, verify the binary path matches your actual installation:

which open-webui
# or
ls ~/.local/share/uv/tools/open-webui/bin/open-webui

If the path differs, update the ProgramArguments string in the plist accordingly.

2. Set the secret key (optional but recommended)

The plist references a secret key file. Create it:

openssl rand -hex 32 > ~/.webui_secret_key
chmod 600 ~/.webui_secret_key

If you don’t want to use a secret key file, remove the WEBUI_SECRET_KEY_FILE entry from EnvironmentVariables in the plist.

3. Load the service

launchctl load ~/Library/LaunchAgents/com.user.openwebui.plist

This registers the service and starts it immediately (because RunAtLoad is true). It will also restart automatically on crash (KeepAlive is true) and run on every login.

4. Verify it's running

# Check the process is up
launchctl list | grep openwebui

# Tail the logs
tail -f ~/Library/Logs/openwebui.log
tail -f ~/Library/Logs/openwebui.err

Then visit http://localhost:8081 in your browser.

5. Common management commands

Action	Command
Stop the service	`launchctl unload ~/Library/LaunchAgents/com.user.openwebui.plist`
Start it again	`launchctl load ~/Library/LaunchAgents/com.user.openwebui.plist`
Restart	unload, then load
Disable autostart	unload + delete the plist file

6. After editing the plist

If you ever modify the plist, you must reload it for changes to take effect:

launchctl unload ~/Library/LaunchAgents/com.user.openwebui.plist
launchctl load ~/Library/LaunchAgents/com.user.openwebui.plist

That’s it — after step 3, Open WebUI will start automatically on every login without any further action needed.

7. Web-app

Open your browser and navigate to http://localhost:8081/.
Firefox and Chromium-based browsers (like Chrome or Edge) support Progressive Web Apps. Click the Install icon in the address bar to run Open WebUI as a standalone application.

Originally published as GitHub Gist #916b8911e29ba9e5ee9b14916834d031

social