Running headless LM-Studio on Linux

TL;DR: In this guide, I will explain how to run LM-Studio headless on Linux, and control it as a user

Recently, I had to provide a solution for GPU-based development and research, and one of the common tools used for this task is ‘LM-Studio‘, a tool to help researchers work with LLM models.

This tool required a graphic display on Linux, which makes it harder to use when you want to place a GPU-based station aside, and use it remotely. My guide will explain how to make LM-Studio function correctly on Linux Ubuntu 24.04 and Redhat variants (OEL/AlmaLinux/RockyLinux/RHEL) version 9, from scratch, without using any on-machine GUI.

Some security notes before we start:

• This is not a secure setup. Any user on the machine can setup her own LM-Studio instance, and they might collide on the same ports, or disrupt each other.
• The LM-Studio is configured to allow remote connections (description below) from anywhere, so make sure you are in a restricted/protected network. Do not put this machine accessible on the Internet.

The unit files and environment files shown below can be found in my github project.

Before we begin

To prepare a system for LM Studio, you would probably need a CUDA-ready system. You could find the required guidelines in this link.

For Ubuntu system – Tested on Ubuntu 24.04

To install LM-Studio appImage requirements, run the following command

sudo apt update ; sudp apt install -y appimage fuse libasound2t64

Install additional required components to allow for the DISPLAY and local-based services

sudo apt install xvfb xauth

For RHEL system (RedHat/OEL/Rocky/Alma)

My system is based on minimal server installation, so you will need install LM-Studio appImage requirements. Run the following commands as root or sudo

dnf install -y fuse atk at-spi2-atk cups-libs libdrm gtk3

Install additional required components to allow for the DISPLAY and local-based services as root or sudo

dnf install -y xorg-x11-xauth xorg-x11-server-Xvfb xorg-x11-utils

Download LM-Studio AppImage package to home directory

Download the LM-Studio package from the respective website to the user’s home directory. Download the AppImage file:

curl -o LM_Studio-0.3.5.AppImage https://releases.lmstudio.ai/linux/x86/0.3.5/2/LM_Studio-0.3.5.AppImage

Make sure that the AppImage file is executable

chmod +x LM_Studio-0.3.5.AppImage

Creating systemd unit files

As root (aka – sudo) create the following files in /etc/systemd/user/ :

xvfb-user.service :

[Unit]
Description=XVFB Env
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
EnvironmentFile=%h/lmstudio.env

# Cut out the preceding : from $DISPLAY
ExecStartPre=-/bin/rm -f /tmp/.X${DISPLAY#*:}-lock
ExecStartPre=-/bin/rm -f /tmp/.X11-unix/X${DISPLAY#*:}
ExecStart=/bin/bash -c '/usr/bin/Xvfb $DISPLAY -screen 0 1920x1080x24 -ac +extension GLX +render -noreset '

#ExecStop=-/usr/bin/pkill Xvfb

Restart=always
RestartSec=10
TimeoutStartSec=60

[Install]
WantedBy=default.target

lmstudio-user.service :

[Unit]
Description=LM Studio AI Service
After=xvfb-user.service
StartLimitIntervalSec=0

[Service]
Type=simple
EnvironmentFile=%h/lmstudio.env
WorkingDirectory=%h

ExecStartPre=-/usr/bin/pkill -f lm-studio

ExecStart=/bin/bash -c './${LM_STUDIO} --no-sandbox'

ExecStop=-/usr/bin/pkill -f lm-studio

#Restart=never
RestartSec=10
TimeoutStartSec=60

[Install]
WantedBy=default.target

Creating the user’s environment file

As the user running LM-Studio, create a file in the home directory with the name lmstudio.env, containing the following:

# DISPLAY variable needs to be unique for each user, if multiple users are to use this system
DISPLAY=:99
# The actual name of the software file
LM_STUDIO=LM_Studio-0.3.5.AppImage

Read the comments in the file and make sure that the DISPLAY is set to be unique (for multi-user system) and that the file name is correct and case sensitive.

Testing that the services start correctly

Run all the following commands as a user. Proceed to the next step only when the previous one has completed successfully

start the virtual display (xvfb) :

systemctl --user start xvfb-user

The service should start almost immediately. Check the status by running

systemctl --user status xvfb-user

Notice the ‘Active’ status at the top lines.

Start the LM-Studio service:

systemctl --user start lmstudio-user

Again, using the ‘status’ flag, verify that the service is starting. LM-Studio takes a while to start, so take a minute and check:

systemctl --user status lmstudio-user

Again, the ‘Active’ state should show ‘active’.

Register the lms tool into your shell:

.cache/lm-studio/bin/lms bootstrap

Starting at your next login, lms command will be included in your $PATH variable, and you would be able to start and stop the server, and would be able to load your models.

Start LM-Studio server the first time

Run the command to start the server (without a model) for the first time to verify that everything is functioning correctly. If you did not logout and login again, you would have to use the full path of the lms command. Otherwise, just using ‘lms’ command would suffice

.cache/lm-studio/bin/lms server start

Enable open listener for the LM-Studio (default port – 1234)

Stop the server using the systemd service

systemctl --user stop lmstudio-user

Edit the file .cache/lm-studio/.internal/http-server-config.json and modify the address 127.0.0.1 with 0.0.0.0. If you want to change the listen port, change 1234 port number to another value.

Start the service, and the lms server, and check if the computer is accessible remotely on the LM-Studio port (default: 1234)

systemctl --user start lmstudio-user
sleep 5
.cache/lm-studio/bin/lms server start

Setting the services to start on boot

As the root (or under ‘sudo’) run the command to allow the user $USER to register in systemd as automatic service login:

sudo loginctl enable-linger $USER

As the user, enable the services created above to start on boot:

systemctl --user enable xvfb-user
systemctl --user enable lmstudio-user

Reboot the machine and test that the services are up, and that the ‘lms’ command can start the server as shown above.

Summary

The user can now use ‘systemctl –user’ with the commands “start/stop/status” to control the lmstudio-user service, which brings up/down/checks-status of the LM-Studio framework, thus – obtaining user-managed service control, with no additional administrative intervene.

Now, if all went correctly, you should have a running LM-Studio headless on Linux

Future topics

• Encrypting connection to an LM-Studio machine, so that only selected users could use it, using stunnel – with Windows/Linux client examples
• Adding a model loading service for model automation, as part of a fully hands-free server handling
• Demonstrating a dynamic DNS, so that a cloud-based dynamic system could function as a remote LM-Studio API server

Reference

Finding info on how to run LM-Studio in headless mode was tough. I happened to find a description of the process, from which I inherited some of my guidelines, in this LinkedIn post. Thank you Angelo Artuso.