LM-Studio-Tray-Manager Documentation

Introduction

This documentation covers the LM Studio automation setup and scripts. The project provides:

setup.sh - One-time setup script to create Python virtual environment (see README.md)
lmstudio_autostart.sh - Bash script for automated daemon startup and model loading
lmstudio_tray.py - Python script for system tray monitoring
build.sh - Build script for a standalone tray binary (PyInstaller); now checks for a C compiler and zlib development library, offering to install missing build tools automatically

The lmstudio_autostart.sh script ensures the LM Studio daemon is running, waits for the API, optionally loads a model, and starts the tray monitor. When dist/lmstudio-tray-manager exists, the autostart script prefers the binary and forwards flags. The lmstudio_tray.py script provides a system tray icon for real-time monitoring and quick actions.

All log files are written to the .logs/ directory for easy access and cleanup.

Setup Guide

The setup process automatically detects your installation type and handles all prerequisite checks, including GTK3/GObject libraries required for the system tray.

Quick Start

./setup.sh

The setup script will:

✓ Check for LM Studio daemon and desktop app
✓ Detect binary vs. Python release
✓ Verify GTK3/GObject typelibs and install if missing
✓ Create Python venv (if needed)
✓ Detect a Python interpreter with working gi
✓ Log all operations to .logs/setup.log
✓ Home directory paths are masked in logs for privacy

After setup, run:

# Binary release
./lmstudio-tray-manager --auto-start-daemon

# Python package release
./lmstudio_autostart.sh

For complete setup instructions, advanced options, troubleshooting, and detailed configuration: See SETUP.md

For building your own binary: See BUILD.md

Configuration

Tray Monitor API Configuration

The tray monitor stores its configuration in ~/.config/lmstudio_tray.json:

{
  "api_host": "localhost",
  "api_port": 1234
}

Edit via Left-click → Options → Configuration in the tray menu.

Environment Variables

VENV_DIR: Custom venv location (default: ./venv)
LM_AUTOSTART_DEBUG=1: Enable debug logging
LM_AUTOSTART_SELECT_TIMEOUT=60: Model selection timeout (seconds)

For detailed configuration options, environment setup, and troubleshooting: See SETUP.md

Usage

Common Commands

# Start daemon with tray monitor
./lmstudio_autostart.sh

# Start GUI (stops daemon first)
./lmstudio_autostart.sh --gui

# Interactive model selection
./lmstudio_autostart.sh --list-models

# Debug mode
./lmstudio_autostart.sh --debug

# Binary release
./lmstudio-tray-manager --auto-start-daemon

Monitor Logs

tail -f .logs/lmstudio_tray.log

For complete usage guide, all CLI options, system tray interface, model management, and application troubleshooting: See USE.md

Logging & Troubleshooting

All logs are written to the .logs/ directory:

GLib schema error: if the binary aborts with a "Settings schema... does not contain a key named 'antialiasing'" message, install gsettings-desktop-schemas or launch with GSETTINGS_SCHEMA_DIR=/usr/share/glib-2.0/schemas. The tray attempts to set this variable automatically on startup.

.logs/setup.log - Setup script log
.logs/lmstudio_autostart.log - Daemon startup log
.logs/lmstudio_tray.log - Tray monitor log

Note: setup.log replaces `$HOME` with `~` to avoid exposing your home directory.

View Logs

tail -f .logs/lmstudio_tray.log
grep -i "error" .logs/*.log

Enable Debug Mode

./lmstudio_autostart.sh --debug

For detailed troubleshooting, setup issues, runtime problems, and comprehensive error guidance: See SETUP.md and USE.md

LM Studio Autostart Script (`lmstudio_autostart.sh`)

This Bash script automates the startup process of LM Studio. It performs the following main tasks:

Checks and installs required dependencies (curl, notify-send, python3)
Default mode starts llmster daemon and tray monitor
Optionally starts the LM Studio GUI (stops daemon first)
Waits for the LM Studio API to be available
Optionally loads a specified model using lms-CLI
Starts the tray monitor script
Prefers the standalone tray binary when available

Command Line Options

Usage: ./lmstudio_autostart.sh [OPTIONS]

            Options:
                -d, --debug       Enable debug output and Bash trace
                -h, --help        Show help and exit
                -L, --list-models List local models (interactive selection in TTY, then load selected model)
                -g, --gui          Start the LM Studio GUI (stops daemon first)

            Environment variables:
                LM_AUTOSTART_DEBUG=1            Force debug mode
                LM_AUTOSTART_SELECT_TIMEOUT=30  Timeout for interactive selection
                LM_AUTOSTART_GUI_CMD="..."      Explicit GUI start command

When dist/lmstudio-tray-manager exists, the script launches the binary instead of the Python script and forwards the same flags. With --gui, it forwards --gui; otherwise it forwards --auto-start-daemon. When debug is enabled, it forwards --debug to the tray monitor.

System Autostart Integration

To automatically start LM Studio daemon and tray monitor on login, create a desktop entry in ~/.config/autostart/:

mkdir -p ~/.config/autostart/
cat > ~/.config/autostart/lmstudio-daemon.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=LM Studio Daemon
Exec=/path/to/LM-Studio/lmstudio_autostart.sh
X-GNOME-Autostart-enabled=true
Hidden=false
EOF

Recommended Setup: Run ./lmstudio_autostart.sh without --gui flag in autostart. The daemon and tray monitor will start automatically. Users can then launch the desktop GUI on-demand via the tray monitor's "Start Desktop App" menu option.

Tray Monitor Script (`lmstudio_tray.py`)

This Python script creates a system tray icon for LM Studio runtime monitoring and mode switching. It provides:

Runtime/model monitoring with four-state icon schema (❌⚠️ℹ️✅)
Live status display for daemon and desktop app in menu
Desktop app launcher (supports .deb and AppImage detection)
Tray icon with status indicators (active/warning/error)
Left-click menu for actions
Notifications for status changes
Automatic update checks with manual "Check for updates" action under Options
Configurable LM Studio API host/port (Options > Configuration)
About dialog shows update status and AUTHORS contributors
Automatic termination of duplicate instances

Status Indicators (in Menu)

When you left-click the tray icon, the menu shows live status for each option:

🟢 (Green Circle) - Component is currently running/active
🟡 (Yellow Circle) - Component is installed but not running
🔴 (Red Circle) - Component is not found/not installed

Tray Icon Schema

❌ - Daemon and desktop app are not installed
⚠️ - Neither daemon nor desktop app is running
ℹ️ - Daemon or desktop app is running, but no model is loaded
✅ - A model is loaded

Tray Menu Options

🟢/🟡/🔴 Start Desktop App: Launch LM Studio GUI
- 🟢 App is currently running
- 🟡 App is installed but not running (will start on click)
- 🔴 App not found (.deb or AppImage) - disabled
- AppImage launches automatically include --no-sandbox to avoid SUID sandbox errors.
🟢/🟡/🔴 Start LM Studio Daemon: Ensure daemon is running
- 🟢 Daemon is currently active
- 🟡 Daemon is installed but stopped (will start on click)
- 🔴 Daemon not found - install from lmstudio.ai
Stop Desktop App: Stops LM Studio desktop process
Stop Daemon: Stops llmster daemon process
Show Status: Displays current LM Studio status via lms ps output. If daemon is not running, falls back to querying the LM Studio API directly and displays loaded models. Shows "No models loaded or error." if neither succeeds.
Options > Configuration: Configure LM Studio API host/port endpoint. Default: localhost:1234. Configuration is persisted at ~/.config/lmstudio_tray.json
Options > Check for updates: Manual GitHub release check
About: Shows version, update status, and authors
Quit Tray: Terminates the tray monitor

Model Detection & API Fallback

The tray monitor uses a two-tier approach for model detection to handle all runtime configurations:

Primary (lms ps): When daemon is running, queries lms ps CLI command to get model status. This is the most reliable method.
Fallback (API): When lms command fails (e.g., desktop app running independently) or returns no output, queries the LM Studio API directly at the configured endpoint. This enables model detection when only the desktop app is running.

This approach ensures accurate model status display across all daemon modes:

Daemon Mode: Uses lms ps primarily, optional API fallback
Desktop-App Mode: Automatically falls back to API when lms is not available
Hybrid Mode (daemon + desktop app): Uses lms ps (preferred) or API fallback

API Configuration & Security

The API endpoint is configurable via Options > Configuration. Configuration is stored securely at ~/.config/lmstudio_tray.json with the following settings:

api_host: LM Studio API host (default: localhost)
api_port: LM Studio API port (default: 1234)

Security Note: All API connections use HTTP/HTTPS schemes only. Other schemes (file://, ftp://, etc.) are rejected by the tray monitor to prevent URL scheme injection attacks. The configuration also validates that host and port values are properly formatted.

Binary Release (`lmstudio-tray-manager`)

The binary release contains a standalone tray monitor built with PyInstaller. It lets you run the tray without a local Python setup. The binary is included in the release archive and works with the same flags as the Python script.

Install and Run

# example (replace X.Y.Z with version)
VERSION=vX.Y.Z

# binary package

tar -xzf lmstudio-tray-manager-${VERSION}-linux-x86_64-binary.tar.gz
cd lmstudio-tray-manager-${VERSION}-linux-x86_64-binary

./setup.sh
./lmstudio-tray-manager --auto-start-daemon

Available Flags

-a, --auto-start-daemon: Start llmster daemon on launch
-g, --gui: Start LM Studio GUI on launch (stops daemon first)
-d, --debug: Enable debug logging
-v, --version: Print version and exit
-h, --help: Show help and exit

Logs

The binary writes logs to .logs/lmstudio_tray.log in the release folder.

Flow Diagrams

Installation Paths Overview

Choose the installation method that best suits your needs:

System Architecture Overview

Key insight: AppImage is self-contained and runs directly. Binary releases also run directly. Only source packages require setup.sh to prepare the Python environment.

setup.sh - Optional Verification Script

Note: setup.sh is optional for AppImage and Binary releases. It automatically detects your installation type and helps verify dependencies.

graph TD A["setup.sh
START"] --> B["Check LM Studio Daemon"] B --> C["Check Desktop App"] C --> E{"Installation type?"} E -->|AppImage found| F["✓ AppImage Detected"] F --> Skip1["Skip GTK3 check
(bundled in AppImage)"] Skip1 --> H1["END (Success)
Ready to run:
./lmstudio-tray-manager-*.AppImage"] E -->|Binary found| G["✓ Binary Found"] G --> Skip2["Skip Python venv
Skip GTK3 check
(bundled in binary)"] Skip2 --> H2["END (Success)
Ready to run:
./lmstudio-tray-manager --auto-start-daemon"] E -->|Neither found| I["Python Source Release Detected"] I --> X["Check GTK3/GObject typelibs"] X --> D["Check Python + gi compatibility"] D --> J{"Compatible Python
with gi found?"} J -->|No| K["Install python3 + python3-gi
via apt"] J -->|Yes| L["Create venv
(./venv)"] K --> L L --> M["Enable system-site-packages
for GTK3/PyGObject"] M --> N["Upgrade pip & setuptools"] N --> O["Show Python Commands"] O --> O1["Ready to run:
./lmstudio_autostart.sh"] O1 --> P["END (Success)
Python environment ready"]

lmstudio_autostart.sh - Daemon Orchestration Script

The autostart flow always launches a tray monitor. A standalone binary is preferred when present.

graph TD A["lmstudio_autostart.sh
START"] --> B[Check system dependencies] B --> C{--gui flag?} C -->|Yes| D[Stop daemon] D --> E[Start LM Studio GUI] E --> S[Sanitize runtime environment
Remove Snap/GTK/Python vars] S --> L["Start tray monitor
(binary preferred; passes --gui)"] C -->|No| F[Start LM Studio daemon] F --> G[Wait for API
host:port
configurable] G --> H{Model specified?} H -->|Yes| J[Load model via lms CLI] H -->|No| K[Skip model loading] J --> S K --> S L --> I["END"]

lmstudio_tray.py - GTK3 System Tray Monitor

graph TD A["lmstudio_tray.py
START"] --> B[Kill existing instances] B --> C[Create GTK3 tray icon] C --> D[Set up left-click menu] D --> E[Start daemon/API monitoring] E --> F{Status check} F --> G{Model loaded?} G -->|Yes| H[Set OK icon ✅] G -->|No| I{Any runtime active?} I -->|Yes| J[Set INFO icon ℹ️] I -->|No| K{Installed?} K -->|Yes| W[Set WARN icon ⚠️] K -->|No| X[Set FAIL icon ❌] H --> L[Check for changes] J --> L W --> L X --> L L --> M{Status changed?} M -->|Yes| N[Send notification] M -->|No| O[Wait before
next check] N --> O O --> F F --> P{User action?} P -->|Start/Stop Daemon| Q[Switch to daemon mode] P -->|Start/Stop Desktop App| R[Switch to desktop app mode] P -->|Show Status| S[Show status dialog] P -->|Quit| T["END"] Q --> F R --> F S --> F

lmstudio-tray-manager - Standalone Binary

The standalone binary compiled from PyInstaller combines the tray monitor with command-line argument handling. No venv activation required.

graph TD A["lmstudio-tray-manager
START"] --> B["Parse command-line
arguments"] B --> C{Argument
provided?} C -->|--help| Help["Display help
and usage info"] Help --> EXIT1["END"] C -->|--version| Ver["Display version
info"] Ver --> EXIT2["END"] C -->|--debug| D["Enable debug mode
Verbose logging"] C -->|--auto-start-daemon| Auto["Auto-start daemon
and tray monitor"] C -->|--gui| Gui["Start LM Studio
GUI first"] C -->|No args| Default["Run as tray monitor
(default behavior)"] D --> RunStart["Kill existing
instances"] Auto --> RunStart Gui --> RunStart Default --> RunStart RunStart --> E["Create GTK3
tray icon"] E --> F["Set up left-click
menu"] F --> G["Start daemon/API
monitoring"] G --> H{Status
check} H --> I{Model
loaded?} I -->|Yes| J["Set OK icon ✅"] I -->|No| K{Any runtime
active?} K -->|Yes| L["Set INFO icon ℹ️"] K -->|No| M{Installed?} M -->|Yes| N["Set WARN icon ⚠️"] M -->|No| O["Set FAIL icon ❌"] J --> P["Check for
changes"] L --> P N --> P O --> P P --> Q{Status
changed?} Q -->|Yes| R["Send
notification"] Q -->|No| S["Wait before
next check"] R --> S S --> H H --> T{User
action?} T -->|Start/Stop
Daemon| U["Toggle
daemon"] T -->|Start/Stop
Desktop App| V["Toggle
desktop app"] T -->|Show Status| W["Display
status dialog"] T -->|Quit| X["END"] U --> H V --> H W --> H

Python Docstrings

The static docstrings documentation for lmstudio_tray.py is available as a dedicated page and uses the same visual design as this documentation.

Open Python Docstrings Reference

Official Resources

Learn more about LM Studio and stay updated with the latest developments:

Blog - Latest updates, news, and release announcements for LM Studio
Official Documentation - Comprehensive guide and API documentation for LM Studio
Download - Download the latest version of LM Studio for your platform