Skip to content

Run the AI server as a background service

When one machine hosts the AI server for a team — or you just want AI available without keeping Understand open — run ullama under your operating system's service manager so it starts at boot and restarts on failure.

Understand ships the ullama binary but not a turnkey service installer, so you register it yourself with a small service definition that points at the installed binary. The examples below do exactly that.

Before you start

  • Find the binary. Note the full path to ullama in your install — e.g. …/bin/linux64/ullama, …/bin/pc-win64/ullama.exe, or inside the macOS app bundle. Keep the other files that ship beside it (ullama-server, ullama-models.conf, and templates/) in place: the launcher reads them from its own directory. See Run the Understand AI server.
  • Pick a model. A background server does not auto-detect the GUI's model, so pass a GGUF file with -m. The model that ships with Understand lives under <install>/conf/understand/models/ — point at that file, or at one of your own.
  • Decide the binding. Pass --host 127.0.0.1 for this machine only, or --host 0.0.0.0 if remote machines must reach it — see Share one AI server across your team.
  • Size the context. -c is the total context shared across --parallel slots. -c 32000 --parallel 1 matches what Understand runs locally; a shared host wants more of both.

Linux (systemd)

Create /etc/systemd/system/ullama.service:

[Unit]
Description=Understand AI server (ullama)
After=network.target

[Service]
Type=simple
ExecStart=/opt/scitools/bin/linux64/ullama -m /opt/models/model.gguf --host 127.0.0.1 --port 56767 -c 32000 --parallel 1
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Adjust the ExecStart paths, then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now ullama

Manage it with systemctl status|stop|restart ullama; follow the server's log with journalctl -u ullama -f. Options can also be given as LLAMA_ARG_* environment variables (LLAMA_ARG_MODEL, LLAMA_ARG_PORT, LLAMA_ARG_CTX_SIZE, …) through Environment= or EnvironmentFile= lines, which is often tidier than a long ExecStart.

macOS (launchd)

Create /Library/LaunchDaemons/com.example.ullama.plist (use your own reverse-DNS label), then load it with sudo launchctl load /Library/LaunchDaemons/com.example.ullama.plist:

<?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.example.ullama</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/Understand.app/Contents/MacOS/ullama</string>
    <string>-m</string><string>/opt/models/model.gguf</string>
    <string>--host</string><string>127.0.0.1</string>
    <string>--port</string><string>56767</string>
    <string>-c</string><string>32000</string>
    <string>--parallel</string><string>1</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/var/log/ullama.log</string>
  <key>StandardErrorPath</key><string>/var/log/ullama.log</string>
</dict>
</plist>

Unload with sudo launchctl unload …; the server's log goes to /var/log/ullama.log.

Windows

ullama.exe is a console program, not a native Windows service, so run it with a service wrapper or a startup task:

  • Service wrapper (recommended) — use a tool such as NSSM to register ullama.exe as a service:
nssm install Ullama "C:\Program Files\SciTools\bin\pc-win64\ullama.exe" -m C:\models\model.gguf --host 127.0.0.1 --port 56767 -c 32000 --parallel 1
Start-Service Ullama
  • Scheduled task — create a Task Scheduler task that runs the command line above At startup as a service account.

NSSM and Task Scheduler are Windows tools, not part of Understand.

Stopping the service on Windows

On Windows ullama.exe stays running as the parent of ullama-server.exe. Stop the service through the wrapper (Stop-Service Ullama) rather than killing ullama.exe directly, so the server process is shut down with it and the port is released.

Point Understand at it

Once the server is running on port 56767, set each Understand client's AI provider to Understand Remote at 127.0.0.1:56767 (or the host's address for remote clients) so it uses your service instead of launching its own copy. See Share one AI server across your team.

This service handles chat, not AI code search

AI Code Search uses a separate embedding model, and Understand always runs that one locally on each client — on 127.0.0.1:56768, started and stopped for you. It is small and CPU-friendly, so a service host only needs to serve the chat model.

Trusted networks only

If the service listens on the network (--host 0.0.0.0), remember it has no TLS, and no authentication unless you pass --api-key — keep it behind your firewall on a network you control.