lemonade

Integrating with Lemonade Server

This guide provides instructions on how to integrate Lemonade Server into your application.

There are two main ways in which Lemonade Server might integrate into apps:

User-Managed Server: User is responsible for installing and managing Lemonade Server.
App-Managed Server: App is responsible for installing and managing Lemonade Server on behalf of the user.

The first part of this guide contains instructions that are common for both integration approaches. The second part provides advanced instructions only needed for app-managed server integrations.

General Instructions

Identifying Existing Installation

To identify if Lemonade Server is installed on a system, you can use the lemonade CLI, which is added to PATH when using our installer. This is a reliable method to:

Verify if the server is installed.
Check which version is currently available by running the command below.

lemonade --version

Note: The lemonade CLI is added to PATH when using the Windows Installer (lemonade-server-minimal.msi), Debian Installer (lemonade-server__amd64.deb), or macOS Installer (Lemonade--Darwin.pkg).

Checking Server Status

To identify whether or not the server is running anywhere on the system you may use the status command:

lemonade status

This command will return either Server is not running or Server is running on port <PORT>.

Identifying Compatible Devices

AMD Ryzen™ AI Hybrid and NPU models are available on Windows 11 on all AMD Ryzen™ AI 300 Series, 400 Series, and Z2 Series Processors. To programmatically identify supported devices, we recommend using a regular expression that checks if the CPU name converted to lowercase contains “ryzen ai” and either a 3-digit number starting with 3 or 4, or “z2” as shown below.

ryzen ai.*((\b[34]\d{2}\b)|(\bz2\b))

Explanation:

ryzen ai: Matches the literal phrase “Ryzen AI”.
.*: Allows any characters (including spaces) to appear after “Ryzen AI”.
((\b[34]\d{2}\b)|(\bz2\b)): Matches either a three-digit number starting with 3 or 4 (for 300/400 series), or “z2” (for Z2 series like Z2 Extreme), ensuring it’s a standalone word.

There are several ways to check the CPU name on a Windows computer. A reliable way of doing so is through cmd’s reg query command as shown below.

reg query "HKEY_LOCAL_MACHINE\HARDWARE\DESCRIPTION\System\CentralProcessor\0" /v ProcessorNameString

Once you capture the CPU name, make sure to convert it to lowercase before using the regular expression.

Downloading Server Installer

The recommended way of directing users to the installer is pointing users to https://lemonade-server.ai/install_options.html

Installing Additional Models

If you want to install models on behalf of your users, the following tools are available:

LLMs that are already available in lemonade:
- Run lemonade list.
- Use the models endpoint.
- A human-readable list of supported models. Do not modify this file in an existing install (see user_models.json below).
- A JSON file that defines the list of built-in models.
- lemonade pull MODEL on the command line interface.
Adding new LLMs:
- The user_models.json file is similar to server_models.json (see above), but contains a user-specific registry that persists across lemonade updates. For a full template and field reference, see the Custom Model Configuration Guide.
- The pull endpoint in the server automates the process of registering models into user_models.json and downloading them.
- The lemonade pull CLI command can also register and download new models, see Options for pull.

Stand-Alone Server Integration

Some apps might prefer to be responsible for installing and managing Lemonade Server on behalf of the user. This part of the guide includes steps for installing and running Lemonade Server so that your users don’t have to install Lemonade Server separately.

Definitions:

“Silent installation” refers to an automatic command for installing Lemonade Server without running any GUI or prompting the user for any questions. It does assume that the end-user fully accepts the license terms, so be sure that your own application makes this clear to the user.

Server Lifecycle

Lemonade Server auto-starts with the OS after installation. To verify the server is running:

lemonade status

Or use the HTTP health endpoint: GET /api/v1/health.

For custom configuration (host, port, etc.), see Server Configuration.

On Linux, service control is available via systemd:

sudo systemctl restart lemonade-server
sudo systemctl status lemonade-server

Windows Installation

Available Installers:

lemonade-server-minimal.msi - Server only (~3 MB)
lemonade.msi - Full installer with Electron desktop app (~105 MB)

GUI Installation:

Double-click the MSI file, or run:

msiexec /i lemonade.msi

MSI Properties:

Properties can be passed on the command line to customize the installation:

INSTALLDIR - Custom installation directory (default: %LOCALAPPDATA%\lemonade_server)
ADDDESKTOPSHORTCUT - Create desktop shortcut (0=no, 1=yes, default: 1)
ALLUSERS - Install for all users (1=yes, requires elevation; default: per-user)

Examples:

# Custom install directory
msiexec /i lemonade.msi INSTALLDIR="C:\Custom\Path"

# Without desktop shortcut
msiexec /i lemonade.msi ADDDESKTOPSHORTCUT=0

# Combined parameters
msiexec /i lemonade.msi INSTALLDIR="C:\Custom\Path" ADDDESKTOPSHORTCUT=0

Silent Installation

Add /qn to run without a GUI, automatically accepting all prompts:

msiexec /i lemonade.msi /qn

This can be combined with any MSI properties:

msiexec /i lemonade.msi /qn INSTALLDIR="C:\Custom\Path" ADDDESKTOPSHORTCUT=0

All Users Installation

To install for all users (Program Files + system PATH), you must run from an Administrator command prompt.

Open Command Prompt as Administrator (right-click → “Run as administrator”)
Run the install command:

msiexec /i lemonade.msi ALLUSERS=1 INSTALLDIR="C:\Program Files (x86)\Lemonade Server"

For silent all-users installation, add /qn:

msiexec /i lemonade.msi /qn ALLUSERS=1 INSTALLDIR="C:\Program Files (x86)\Lemonade Server"

Troubleshooting:

If installation fails silently, check that you’re running as Administrator
Add /L*V install.log to generate a debug log file

Linux Installation

Debian/Ubuntu Package

The Debian package installer handles all system configuration automatically, including setting up a systemd service for managing the Lemonade Server.

On Linux, the package also recommends ffmpeg so whisper.cpp can resample and/or transcode audio inputs when needed.

If you would prefer to manage the lifecycle of the server process manually, the service can be disabled and manually run as well.

Systemd Service Management

When Lemonade Server is installed via the Debian package, it registers a systemd service called lemonade-server that allows you to manage the server process using standard systemd commands.

Service Features:

Automatic restart: The service automatically restarts if the server crashes
User isolation: Runs under the unprivileged lemonade user for security
GPU access: The service is configured with proper group membership to access GPU/NPU hardware via the render group
Security hardening: Includes systemd security options like ProtectSystem=full, ProtectHome=yes, and NoNewPrivileges=yes
Boot integration: Starts automatically on system boot (if enabled)

Common Commands:

# Start the service
sudo systemctl start lemonade-server

# Stop the service
sudo systemctl stop lemonade-server

# Restart the service
sudo systemctl restart lemonade-server

# Check service status
sudo systemctl status lemonade-server

# Enable automatic startup on boot
sudo systemctl enable lemonade-server

# Disable automatic startup on boot
sudo systemctl disable lemonade-server

# View service logs
sudo journalctl -u lemonade-server

# View recent logs (follow mode)
sudo journalctl -u lemonade-server -f

Configuration:

See Server Configuration.

macOS Installation (Beta)

Available Installer:

Lemonade-<VERSION>-Darwin.pkg - Signed and notarized macOS installer package

GUI Installation:

Double-click the .pkg file to launch the installer, or run:

sudo installer -pkg Lemonade-<VERSION>-Darwin.pkg -target /

Silent Installation:

sudo installer -pkg Lemonade-<VERSION>-Darwin.pkg -target /

The macOS installer places binaries in /usr/local/bin, so lemonade is available in PATH immediately after installation.

Note: macOS support is currently in beta. The llama.cpp backend with Metal acceleration is supported on Apple Silicon Macs.

This site is open source. Improve this page.