Install details (technical)
Not needed for normal use. Read on if you want install locations, how the background service runs, or where data is stored.
Shared background service with the CLI install
The desktop app and the command-line install share one auto-start node service (macOS launchd com.zqagent.node, Linux systemd zqagent, Windows logon task). A machine therefore only ever has one node: if the node was installed with install.sh, the desktop app reuses it instead of starting a second one.
What the first launch does
The first launch installs the bundled engine as an auto-start node service and connects to it — no address or key to enter by hand. If a node was already installed via install.sh, the desktop app reuses that service.
Closing and quitting
- Closing the window = hiding to the tray; tasks keep running. Use "Open ZQAgent" in the tray menu to restore it.
- Quit: "Quit" in the tray menu only closes the desktop shell. The node service keeps running in the background (kept alive by launchd / systemd / the logon task).
- Single instance: launching the app again only raises the existing window; a second node is never started.
Where data lives
Node data (tenants, sessions, model configuration, admin.json) is stored in the system service data directory:
| Platform | Data directory |
|---|---|
| macOS | ~/Library/Application Support/zqagent/ |
| Linux | ~/.zqagent_data/ (owned by the running user; /var/lib/zqagent/ in early versions) |
| Windows | %APPDATA%\zqagent\ |
Shared with nodes installed by install.sh, so the two install methods can be switched freely and sessions restored at any time.
Desktop preferences (workspace, keep-awake) are stored separately in ~/.config/zqagent-desktop/desktop.json.
Changing the model
Open Settings, fill in the model name, Base URL and API Key, then save. The change applies to new sessions.
System requirements
- Windows 10 / 11 (64-bit; Windows 7, 8 and 8.1 are not supported)
- macOS 11 or later (Apple silicon and Intel share one package)
- Linux: deb for Ubuntu / Debian, rpm for CentOS / Fedora
Troubleshooting
- macOS says the app cannot be opened? Right-click → Open, or allow it under System Settings → Privacy & Security.
- Blocked by Windows SmartScreen? "More info" → "Run anyway".
- Want the command-line version? See Advanced usage.
- Other install or connection issues? See Technical questions.