# 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](../lemonade-cli.md), 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_<VERSION>_amd64.deb), or macOS Installer (Lemonade-<VERSION>-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](./server_spec.md#get-apiv1models).
  - [A human-readable list of supported models](https://lemonade-server.ai/models.html). 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](https://github.com/lemonade-sdk/lemonade/blob/main/src/cpp/resources/server_models.json).
  - `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](./custom-models.md).
  - [The `pull` endpoint in the server](./server_spec.md#post-apiv1pull) 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](../lemonade-cli.md#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:

```bash
lemonade status
```

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

For custom configuration (host, port, etc.), see [Server Configuration](./configuration.md).

On Linux, service control is available via systemd:

```bash
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:

```bash
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:**

```bash
# 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:

```bash
msiexec /i lemonade.msi /qn
```

This can be combined with any MSI properties:

```bash
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.

1. Open Command Prompt as Administrator (right-click → "Run as administrator")
2. Run the install command:

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

For silent all-users installation, add `/qn`:

```bash
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:**

```bash
# 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](./configuration.md).


## 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:

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

**Silent Installation:**

```bash
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 file was originally licensed under Apache 2.0. It has been modified.
Modifications Copyright (c) 2025 AMD-->
