• The app already calls a cloud AI service over HTTP (OpenAI Chat Completions, Anthropic Messages, or Ollama).
• The user wants that AI to run on the end-user's PC, with the AI engine bundled into the app, not as a separate user install.
• The target platform is Windows x64 or Linux x64 (macOS embeddable is in beta).

https://lemonade-server.ai/install_options.html

http://localhost:13305/api/v1

[ ] 1. Survey the app's current AI integration
[ ] 2. Pick a model + backend profile
[ ] 3. Place Embeddable Lemonade in the app's tree (full package, not just the binary)
[ ] 4. Add a `lemond` launcher (subprocess + API key + port + per-stage logging)
[ ] 5. Re-point the existing client at lemond (base_url, api_key, 120s timeout — all three required)
[ ] 6. Wait for /api/v1/health, install backend, then PULL the model before first use
[ ] 7. Wire shutdown and error recovery

Log every stage. A local integration has many silent failure points — spawn, health, backend install, model download, first inference. Without a log line at each transition, "nothing happened" is indistinguishable from "broke at stage 3." Emit one clear line per stage as you build (see Step 4); the most common dead-end in this integration — a blank result with no error — is invisible without them.

• openai

  ,

  OpenAI(

  ,

  chat.completions

  ,

  responses.create

• anthropic

  ,

  Anthropic(

  ,

  messages.create

• api.openai.com

  ,

  api.anthropic.com

  ,

  localhost:11434

  (Ollama)

• OPENAI_API_KEY

  ,

  ANTHROPIC_API_KEY

1. Client library and language (e.g.,

   openai-python

   ,

   openai-node

   ,

   @anthropic-ai/sdk

   ,

   go-openai

   , raw

   fetch

   ).
2. Modalities used: text chat, tool calling, embeddings, image gen, transcription, TTS. This drives the model + backend choice in Step 2.
3. One single place where the base URL and API key are constructed. If there isn't one, refactor to one before going further. Local-mode toggling must flip exactly one config object.
4. Any API-key gating that blocks the app before a key is entered (onboarding walls, validators that reject empty keys, startup checks that disable AI until a key exists). Note each one — Step 5 bypasses them in local mode.

Qwen3-4B-GGUF

llamacpp

Qwen2.5-Coder-7B-Instruct-GGUF

llamacpp

Gemma-4-E2B-it-GGUF

llamacpp

Llama-3.2-3B-Instruct-Hybrid

ryzenai-llm

Whisper-Large-v3-Turbo

whispercpp

whisper-v3-turbo-FLM

flm

whispercpp

kokoro-v1

kokoro

SDXL-Turbo

sd-cpp

llamacpp

lemond

rocm

vulkan

cpu

llamacpp_backend

vulkan

vulkan

Note: having an NPU does not mean every recipe supports NPU. Confirm the recipe/backend pair is

installed

or

installable

via

GET /api/v1/system-info

before committing to it. See reference.md for per-recipe decision rules.

https://github.com/lemonade-sdk/lemonade/releases/latest

• Windows:

  lemonade-embeddable-{VERSION}-windows-x64.zip

• Linux:

  lemonade-embeddable-{VERSION}-ubuntu-x64.tar.gz

Don't hand-build the download URL from the tag. The git tag carries a leading

v

(e.g.

v10.8.0

) but the asset filename strips it (

lemonade-embeddable-10.8.0-...

), so using the tag verbatim 404s. Ask the GitHub API for the asset by its stable name pattern and use the URL it returns, as below — this stays correct across version and naming changes.

undefined

On Linux (bash):

```bash
URL=$(curl -s https://api.github.com/repos/lemonade-sdk/lemonade/releases/latest \
  | grep browser_download_url | grep ubuntu-x64.tar.gz | cut -d'"' -f4)
curl -L "$URL" | tar -xz --strip-components=1 -C vendor/lemonade

Copy the full package, not just the binary. The archive contains

lemond[.exe]

,

lemonade[.exe]

,

LICENSE

, and

resources/

. The

resources/

directory is required — without it lemond starts and passes the health check but fails on every model and backend request. Copying only the binary produces a server that looks healthy but cannot function.

lemond

vs

lemonade

CLI:

lemond

is the embedded server binary that ships with the app. The

lemonade

CLI is a separate packaging tool used only during development/build time to install backends. The same embeddable archive unpacked above already contains a matching

lemonade[.exe]

next to

lemond[.exe]

, so its version aligns with the bundled

lemond

. Do not

pip install lemonade-sdk

to get it: the PyPI package is a separate, older release line whose ports, model names, and install API do not match the

lemond

bundled here, and mixing the two is a known source of silent version mismatches. Keep the

lemonade

CLI,

lemond

, and the backends all from the one release downloaded in this step so their versions stay aligned.

lemond[.exe]

lemonade[.exe]

LICENSE

resources/

vendor/lemonade/
  lemond[.exe]                     # the only binary the app ships
  LICENSE
  config.json                      # generated on first run; commit a seed copy
  resources/
    server_models.json             # do not edit; use GET /api/v1/models at runtime
    backend_versions.json
  bin/                             # backends bundled at packaging time
    llamacpp/vulkan/llama-server[.exe]
  models/                          # pre-bundled model weights (optional)
    models--unsloth--Qwen3-4B-GGUF/

server_models.json

: Do not edit or rely on this file. It can be stale. The only authoritative model list is

GET /api/v1/models

on a running

lemond

instance with the backend already installed.

• Backends: Bundle

  llamacpp:vulkan

  at packaging time (works on every GPU). Install

  llamacpp:rocm

  at first run on supported AMD systems via

  POST /api/v1/install

  after probing

  GET /api/v1/system-info

  . Never ship every backend, or the artifact balloons.
• Models: Either bundle the default model under

  models/

  (offline install, larger installer) or pull on first run with

  POST /api/v1/pull

  (smaller installer, needs network). Pick one and document it.

• models_dir

  : Set to

  ./models

  in

  config.json

  to keep weights private to the app. Leave as

  auto

  only if the user explicitly wants to share weights with other apps.

Packaging time (developer machine, before bundling). Use the lemonade CLI that shipped inside

vendor/lemonade/

so it matches the bundled

lemond

version (prefix with

./

or the full path):

vendor/lemonade/lemonade backends install llamacpp:vulkan
vendor/lemonade/lemonade backends install flm:npu    # Windows NPU path only

This bakes the backend binaries into

vendor/lemonade/bin/

before the app ships.

lemond

does not need to be running. Use a modern

lemonade

CLI whose version matches the bundled

lemond

(the copy in the archive you unpacked works); do not

pip install lemonade-sdk

for it.

First-run / runtime (user's machine, after

lemond

is running):

http

POST /api/v1/install
{"recipe": "llamacpp", "backend": "rocm"}

Use this for hardware-specific backends (e.g.

llamacpp:rocm

) that cannot be bundled universally.

lemond

must already be running (Step 4 complete).

lemond_launcher.py

lemond_launcher.<ext>

1. Generate a fresh random API key:

   key = secrets.token_urlsafe(32)

2. Pick a free localhost port: bind a

   socket

   to port 0, read back the assigned port, close it.
3. Spawn lemond as a

   subprocess

   :

   subprocess.Popen([LEMOND_BIN, LEMOND_DIR, "--port", str(port)], env={**os.environ, "LEMONADE_API_KEY": key})

4. Poll

   GET /api/v1/health

   with

   Authorization: Bearer {key}

   in a loop until HTTP 200 — this is the only correct readiness check.
5. Expose the chosen

   port

   and

   key

   to the rest of the app.

Log one line per lifecycle stage. Build the logging in from the start — not as an afterthought when something breaks. Each silent transition needs a visible marker so a failure points at the exact stage. Aim for:

[lemond] Starting on port <port>
[lemond] Healthy on port <port>
[lemond] <recipe>:<backend> installed        (or: already installed / install failed)
[lemond] Pulling model <name>...             then: Model <name> ready  (or: pull returned <status>)
[local]  <modality> result: <value>          (first inference output — empty string here = unpulled model)

Logging the first inference result verbatim is what turns the silent-empty failure (Step 6) from a multi-hour mystery into a one-line diagnosis. Route these through the app's normal logging so they can be quieted for release.

Dev-mode file watchers: If the app runs with a file watcher (Tauri, Electron, Next.js, Vite, etc.) that watches the source tree, ensure

vendor/lemonade/

is excluded from the watched paths. Lemond writes config and cache files at runtime; a watcher that picks these up will restart the app, kill the lemond subprocess, and spawn a new one on a new port — silently breaking any in-flight transcription. Add

vendor/

(or the equivalent) to the watcher's ignore list before testing.

LEMOND_DIR

secrets

socket

subprocess

GET http://127.0.0.1:<port>/api/v1/health

lemond

/api/v1/health

1. Set

   base_url

   to

   http://127.0.0.1:{port}/api/v1

2. Set

   api_key

   to the launcher key
3. Set the HTTP timeout to 120 seconds — this is mandatory, not optional

import httpx
from openai import OpenAI

proc, key, port = start_lemond()
client = OpenAI(
    base_url=f"http://127.0.0.1:{port}/api/v1",
    api_key=key,
    http_client=httpx.Client(timeout=120),  # required: 120s for first-run model load
)

base_url

openai-python

http://127.0.0.1:{port}/api/v1

api_key=key

httpx.Client(timeout=120)

openai-node

http://127.0.0.1:{port}/api/v1

apiKey: key

timeout: 120000

@anthropic-ai/sdk

http://127.0.0.1:{port}/api/v1

apiKey: key

timeout: 120000

fetch

requests

Authorization: Bearer {key}

http://127.0.0.1:{port}/api/v0

Qwen3-4B-GGUF

• Skip or auto-satisfy the key-entry screen in local mode.
• Treat local mode as already-authorized in every validation path — an empty-key check must short-circuit to "valid" when the active mode is local, never throw "API key not configured".
• Re-enable the gate only for cloud mode.

lemond

"local"

POST /api/v1/pull
{"model": "Whisper-Large-v3-Turbo"}

• Default model (the one you chose in Step 2): pull it by name as above.
• Custom / user-overridden model: do not assume it exists. Confirm it is a real Lemonade model first via

  GET /api/v1/models

  (the only trusted catalog — see reference.md), then pull it the same way. A model appearing in the catalog is not proof its weights are downloaded; a successful pull is.

Silent-empty is almost always an unpulled model. If inference returns an empty string / blank output with no HTTP error, the model was not downloaded. Check your pull step before debugging anything else — this is the failure mode that wastes the most time. Log the pull result and the first inference result (see Step 4) so this is diagnosable from the console, not by guesswork.

• vendor/lemonade/

  contains the full package:

  lemond[.exe]

  ,

  lemonade[.exe]

  ,

  LICENSE

  , and

  resources/

  — not just the binary.

• lemond

  starts as a subprocess with a fresh API key per launch.

• GET /api/v1/health

  returns 200 within the timeout.
• The default model is pulled (or bundled) before the first inference; a custom/overridden model is confirmed via

  GET /api/v1/models

  and then pulled. A blank result with no error means this step was skipped.
• Each lifecycle stage logs a clear line (spawn, health, backend install, model pull, first result) so a failure is diagnosable from the console.
• The existing client's chat / image / speech call returns a valid response with the base URL and key swapped, with no other code changed.
• First-run latency is surfaced: the interface shows a loading state from the moment the first inference request is sent until the response arrives.
• The HTTP client timeout is set to 120 seconds.
• In local mode the app requires no cloud API key: no onboarding wall, validator, or startup check blocks the user, and no code path throws "API key not configured" when the active mode is local.
• If the app uses a dev-mode file watcher,

  vendor/lemonade/

  is excluded from the watched paths so runtime writes by lemond do not trigger restarts.
• Killing the parent process leaves no

  lemond

  subprocess behind.
• On a fresh machine without the optimal backend, the app still works via the Vulkan fallback bundled in

  bin/

  .