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 undaiserver under your operating system's service manager so it starts at boot and restarts on failure.

Understand ships the undaiserver 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 undaiserver in your install — e.g. …/bin/linux64/undaiserver, …/bin/pc-win64/undaiserver.exe, or inside the macOS app bundle. See Run the Understand AI server.
  • Pick a model. A background server does not auto-detect the GUI's model, so set UNDAI_LLAMA_MODEL_PATH to a GGUF file. 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. It listens on 127.0.0.1:56767 by default; add --network (or UNDAI_SERVER_HOST=0.0.0.0) only if remote machines must reach it — see Share one AI server across your team.

Linux (systemd)

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

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

[Service]
Type=simple
ExecStart=/opt/scitools/bin/linux64/undaiserver --tcp 56767
Environment=UNDAI_LLAMA_MODEL_PATH=/opt/models/model.gguf
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Adjust the ExecStart path and model path, then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now undaiserver

Manage it with systemctl status|stop|restart undaiserver; follow its output with journalctl -u undaiserver -f. For many variables, use EnvironmentFile=/etc/undaiserver/env instead of inline Environment= lines.

macOS (launchd)

Create /Library/LaunchDaemons/com.example.undaiserver.plist (use your own reverse-DNS label), then load it with sudo launchctl load /Library/LaunchDaemons/com.example.undaiserver.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.undaiserver</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/Understand.app/Contents/MacOS/undaiserver</string>
    <string>--tcp</string><string>56767</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>UNDAI_LLAMA_MODEL_PATH</key><string>/opt/models/model.gguf</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/var/log/undaiserver.log</string>
  <key>StandardErrorPath</key><string>/var/log/undaiserver.log</string>
</dict>
</plist>

Unload with sudo launchctl unload …; output goes to /var/log/undaiserver.log.

Windows

undaiserver.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 undaiserver.exe as a service:
nssm install UndaiServer "C:\Program Files\SciTools\bin\pc-win64\undaiserver.exe" --tcp 56767
nssm set UndaiServer AppEnvironmentExtra UNDAI_LLAMA_MODEL_PATH=C:\models\model.gguf
Start-Service UndaiServer
  • Scheduled task — create a Task Scheduler task that runs the command line above At startup as a service account, with the UNDAI_* values set in that account's environment.

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

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.

Trusted networks only

If the service listens on the network (--network / UNDAI_SERVER_HOST=0.0.0.0), remember it has no authentication or TLS — keep it behind your firewall on a network you control.