server: add ServerLauncher — one fat-jar entry, pick mode via --open-ai-compat

Tiny dispatcher as the fat jar's Main-Class: with --open-ai-compat it runs
OpenAiCompatServer (Java-transport OpenAI API), without it the default
NativeServer (full native llama.cpp server + WebUI). The --open-ai-compat marker
is stripped (it is not a llama.cpp flag); all other args are forwarded verbatim
to the chosen server. Both underlying mains stay runnable directly by class name
via java -cp.

Note: the two servers accept different flag sets — NativeServer forwards every
llama-server flag, OpenAiCompatServer's CLI accepts a curated subset and rejects
unknown flags — so native-only flags can't be combined with --open-ai-compat.

Dispatch logic split into pure static helpers (selectsOpenAiCompat / withoutFlag)
with 7 unit tests. Verified at runtime: `ServerLauncher --open-ai-compat -m model
--port 8973` starts the Java server (/ -> invalid_request_error, its handler),
and without the flag starts NativeServer (/ -> native File Not Found); both shut
down cleanly on SIGTERM. pom Main-Class NativeServer -> ServerLauncher; README +
CLAUDE.md updated. spotless + javadoc clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HL7d4uQ3cKR5HwYFPvZvv7

Author: claude

CLAUDE.md

@@ -851,10 +851,10 @@ If the local check passes (`BUILD SUCCESS`), the `mvn package` job in
 
 ### Two server modes (`OpenAiCompatServer` vs `NativeServer`)
 
-The library exposes **two** ways to serve a model over HTTP, on two different transports:
+The library exposes **two** ways to serve a model over HTTP, on two different transports. The fat jar's `Main-Class` is `server.ServerLauncher`, a tiny dispatcher: it runs `OpenAiCompatServer` when `--open-ai-compat` is present (that marker is stripped, the rest forwarded) and the default `NativeServer` otherwise. Both mains are also runnable directly by class name via `java -cp`. The two modes:
 
 1. **`server.OpenAiCompatServer` (Java transport).** OpenAI/Ollama/Anthropic-compatible JSON API on the JDK's `com.sun.net.httpserver`, driving the compiled server *core* over JNI. Embeddable, no extra dependency, and it can share/reuse a `LlamaModel`. It serves **no** static assets — its `/` route is a 404, so **no WebUI**. It has its own `main` (run via `java -cp <jar> net.ladenthin.llama.server.OpenAiCompatServer …`); its CLI (`OpenAiServerCli`) maps a curated flag subset (`-m/-c/-b/-ub/-ngl/-t/-tb/-ctk/-ctv/--jinja/--chat-template-kwargs/--host/--port/--parallel/--mmproj/--api-key/--embedding/--reranking`).
-2. **`server.NativeServer` (native transport) — the fat-jar default `Main-Class`.** Runs the **full upstream `llama_server`** (via `patches/0006` + `native_server.cpp`) inside `libjllama`, forwarding the raw llama-server argv verbatim — so **every** llama-server flag works and the **embedded WebUI is served** (when the assets are compiled in; CI's released jars have them, local `cmake` builds use the empty-asset stub). It is an **independent lifecycle** (loads its own model from the argv, like `llama-server.exe`; owns the process's llama backend + stderr logging while running), **single-instance per process** (upstream keeps shutdown state in file-scope globals), and **not available on Android** (the `subprocess.h` guard). Reusing an already-loaded `LlamaModel`'s context is a documented TODO. `libjllama` loading anywhere a JVM runs is what makes this "no separate `llama-server.exe`" possible.
+2. **`server.NativeServer` (native transport) — the default fat-jar server (when `--open-ai-compat` is absent).** Runs the **full upstream `llama_server`** (via `patches/0006` + `native_server.cpp`) inside `libjllama`, forwarding the raw llama-server argv verbatim — so **every** llama-server flag works and the **embedded WebUI is served** (when the assets are compiled in; CI's released jars have them, local `cmake` builds use the empty-asset stub). It is an **independent lifecycle** (loads its own model from the argv, like `llama-server.exe`; owns the process's llama backend + stderr logging while running), **single-instance per process** (upstream keeps shutdown state in file-scope globals), and **not available on Android** (the `subprocess.h` guard). Reusing an already-loaded `LlamaModel`'s context is a documented TODO. `libjllama` loading anywhere a JVM runs is what makes this "no separate `llama-server.exe`" possible.
 
 ### Native Helper Architecture
 

README.md

@@ -107,7 +107,7 @@ Inference of Meta's LLaMA model (and others) in pure C/C++.
 - **Infilling** (fill-in-the-middle) for code models.
 - **Tokenize / detokenize** and **JSON-schema → grammar** conversion.
 - **Raw JSON endpoint handlers** mirroring the upstream llama.cpp HTTP server (`/completions`, `/v1/completions`, `/embeddings`, `/infill`, `/tokenize`, `/detokenize`).
-- **Two runnable HTTP server modes.** The fat jar's default `Main-Class` is `NativeServer` — the full upstream llama.cpp server (embedded **WebUI**, every llama-server flag forwarded) hosted inside `libjllama` over JNI, no separate `llama-server.exe`: `java -jar …-jar-with-dependencies.jar -m model.gguf --port 8080`. The Java-transport, zero-extra-dependency **OpenAI-compatible** server (`OpenAiCompatServer`, streaming SSE) is also available: `java -cp …-jar-with-dependencies.jar net.ladenthin.llama.server.OpenAiCompatServer --model model.gguf --port 8080`.
+- **Two runnable HTTP server modes, one fat-jar entry.** The fat jar's `Main-Class` is `ServerLauncher`, which dispatches on the `--open-ai-compat` flag. Without it, `java -jar …-jar-with-dependencies.jar -m model.gguf --port 8080` runs the full upstream llama.cpp server (embedded **WebUI**, every llama-server flag forwarded) hosted inside `libjllama` over JNI — no separate `llama-server.exe`. With it, `java -jar … --open-ai-compat --model model.gguf --port 8080` runs the Java-transport, zero-extra-dependency **OpenAI-compatible** server (`OpenAiCompatServer`, streaming SSE) instead. Both are also runnable directly by class name via `java -cp … net.ladenthin.llama.server.{NativeServer,OpenAiCompatServer}`.
 - **Model metadata** access (`getModelMeta()`) and **server management** (metrics, slot save/restore, runtime thread reconfiguration).
 - Pre-built native binaries for Linux (x86-64, aarch64), macOS (x86-64, arm64), and Windows (x86-64, x86); CUDA, Metal, and Vulkan supported via local build.
 
@@ -648,17 +648,16 @@ try (LlamaModel model = new LlamaModel(modelParams);
 }
 ```
 
-…or run it standalone. It has its own `main`, launched by class name via `-cp` (the fat jar's
-default `java -jar` `Main-Class` is `NativeServer` — the native server below — so name
-`OpenAiCompatServer` explicitly to get this Java one):
+…or run it standalone. The fat jar's `Main-Class` is the `ServerLauncher` dispatcher, so add
+`--open-ai-compat` to select this Java server (the launcher strips that flag and forwards the rest);
+or name the class explicitly via `-cp`:
 
 ```bash
-# fat jar (bundles the native lib + Java deps) — name the class explicitly
-java -cp target/llama-<version>-jar-with-dependencies.jar \
-    net.ladenthin.llama.server.OpenAiCompatServer \
+# fat jar (bundles the native lib + Java deps) — select the Java server with --open-ai-compat
+java -jar target/llama-<version>-jar-with-dependencies.jar --open-ai-compat \
     --model models/Qwen3-0.6B-Q4_K_M.gguf --host 0.0.0.0 --port 8080 --n-gpu-layers 99
 
-# or the plain library jar
+# or name the class explicitly (fat jar or plain library jar)
 java -cp target/llama-<version>.jar net.ladenthin.llama.server.OpenAiCompatServer \
   --model models/model.gguf --port 8080 --model-id local-model
 ```
@@ -719,9 +718,9 @@ tool calling depends on the model's own tool-calling quality. Pass `--api-key` (
 the **full upstream llama.cpp server, including its bundled Svelte WebUI**, use
 `net.ladenthin.llama.server.NativeServer`. It runs the real `llama_server` inside `libjllama` over
 JNI — no separate `llama-server.exe` — and **forwards the raw llama-server arguments verbatim**, so
-every flag works exactly as it does for the standalone binary. It is the fat jar's default
-`Main-Class`, so `java -jar` just forwards its args to the native server (pass `--help` for the full
-llama-server option list):
+every flag works exactly as it does for the standalone binary. The fat jar runs it **by default**
+(when `--open-ai-compat` is absent), forwarding its args to the native server (pass `--help` for the
+full llama-server option list):
 
 ```bash
 java -jar target/llama-<version>-jar-with-dependencies.jar \

llama/pom.xml

@@ -1296,10 +1296,10 @@ SPDX-License-Identifier: MIT
 			<!--
 				Builds the fat jar-with-dependencies uber JAR: the library classes, the
 				default-platform native libs from src/main/resources, and all runtime Java
-				dependencies in one drop-on-classpath JAR, with NativeServer as the fat-jar
-				Main-Class (set below) to start the full native llama.cpp server (embedded WebUI,
-					every llama-server flag forwarded); OpenAiCompatServer stays runnable via
-					`java -cp <jar> net.ladenthin.llama.server.OpenAiCompatServer`. Off by
+				dependencies in one drop-on-classpath JAR, with ServerLauncher as the fat-jar
+				Main-Class (set below), which dispatches on an `open-ai-compat` selector flag: with it, runs
+					OpenAiCompatServer (Java OpenAI API); without it, the default NativeServer (native
+					server, embedded WebUI, all flags forwarded). Both mains stay runnable by class name via `java -cp <jar> …`. Off by
 				default; the CI `package` job activates it so the uber JAR rides along in the
 				`llama-jars` upload-artifact bundle. Documented in CLAUDE.md "Build Commands"
 				as `mvn -P assembly package`.
@@ -1316,7 +1316,7 @@ SPDX-License-Identifier: MIT
 							</descriptorRefs>
 							<archive>
 								<manifest>
-									<mainClass>net.ladenthin.llama.server.NativeServer</mainClass>
+									<mainClass>net.ladenthin.llama.server.ServerLauncher</mainClass>
 								</manifest>
 							</archive>
 						</configuration>

llama/src/main/java/net/ladenthin/llama/server/ServerLauncher.java

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama.server;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Fat-jar entry point that dispatches to one of the two server modes based on a single selector
+ * flag. With {@value #OPEN_AI_COMPAT_FLAG} present it runs {@link OpenAiCompatServer} (the
+ * Java-transport, OpenAI-compatible JSON API); without it, {@link NativeServer} (the full native
+ * llama.cpp server with embedded WebUI, the default).
+ *
+ * <p>Every other argument is forwarded verbatim to the chosen server; the {@value
+ * #OPEN_AI_COMPAT_FLAG} marker itself is stripped so it never reaches either parser (it is not a
+ * llama.cpp flag, and {@code llama_server} rejects unknown flags).</p>
+ *
+ * <p><strong>Flag sets differ.</strong> {@link NativeServer} forwards <em>every</em> llama-server
+ * flag to {@code llama_server}, whereas {@link OpenAiCompatServer}'s CLI ({@link OpenAiServerCli})
+ * accepts a curated subset and rejects unknown flags — so native-only flags (e.g. {@code --ui},
+ * {@code -fa}) cannot be combined with {@value #OPEN_AI_COMPAT_FLAG}.</p>
+ *
+ * <p>Both underlying mains remain directly runnable by class name via {@code java -cp}; this
+ * launcher is purely a convenience so a single {@code java -jar} covers both.</p>
+ */
+public final class ServerLauncher {
+
+    /** Selector flag: when present, run {@link OpenAiCompatServer} instead of the default {@link NativeServer}. */
+    public static final String OPEN_AI_COMPAT_FLAG = "--open-ai-compat";
+
+    private ServerLauncher() {}
+
+    /**
+     * Dispatches to {@link OpenAiCompatServer#main(String[])} when {@value #OPEN_AI_COMPAT_FLAG} is
+     * present (with that marker removed from the arguments), otherwise to
+     * {@link NativeServer#main(String[])} with all arguments forwarded unchanged.
+     *
+     * @param args the process arguments
+     * @throws Exception if the selected server's {@code main} throws (it blocks until shutdown)
+     */
+    public static void main(String[] args) throws Exception {
+        if (selectsOpenAiCompat(args)) {
+            OpenAiCompatServer.main(withoutFlag(args, OPEN_AI_COMPAT_FLAG));
+        } else {
+            NativeServer.main(args);
+        }
+    }
+
+    /**
+     * Whether the arguments request the OpenAI-compatible server via {@value #OPEN_AI_COMPAT_FLAG}.
+     *
+     * @param args the process arguments
+     * @return {@code true} if the selector flag is present
+     */
+    static boolean selectsOpenAiCompat(String[] args) {
+        for (final String arg : args) {
+            if (OPEN_AI_COMPAT_FLAG.equals(arg)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Returns a copy of {@code args} with every occurrence of {@code flag} removed, preserving the
+     * order of the remaining arguments.
+     *
+     * @param args the arguments
+     * @param flag the flag token to strip
+     * @return a new array without {@code flag}
+     */
+    static String[] withoutFlag(String[] args, String flag) {
+        final List<String> filtered = new ArrayList<>(args.length);
+        for (final String arg : args) {
+            if (!flag.equals(arg)) {
+                filtered.add(arg);
+            }
+        }
+        return filtered.toArray(new String[0]);
+    }
+}

llama/src/test/java/net/ladenthin/llama/server/ServerLauncherTest.java

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama.server;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.arrayContaining;
+import static org.hamcrest.Matchers.emptyArray;
+import static org.hamcrest.Matchers.is;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Pure-Java unit tests for {@link ServerLauncher}'s dispatch logic (selector detection + flag
+ * stripping). No server is started and no native library is required.
+ */
+public class ServerLauncherTest {
+
+    @Test
+    public void selectsNativeByDefault() {
+        assertThat(ServerLauncher.selectsOpenAiCompat(new String[] {"-m", "m.gguf", "--port", "8080"}), is(false));
+    }
+
+    @Test
+    public void selectsOpenAiCompatWhenFlagPresent() {
+        assertThat(ServerLauncher.selectsOpenAiCompat(new String[] {"--open-ai-compat", "-m", "m.gguf"}), is(true));
+    }
+
+    @Test
+    public void selectorFlagPositionDoesNotMatter() {
+        assertThat(ServerLauncher.selectsOpenAiCompat(new String[] {"-m", "m.gguf", "--open-ai-compat"}), is(true));
+    }
+
+    @Test
+    public void withoutFlagStripsTheSelectorAndPreservesTheRest() {
+        String[] out = ServerLauncher.withoutFlag(
+                new String[] {"--open-ai-compat", "-m", "m.gguf", "--port", "8080"},
+                ServerLauncher.OPEN_AI_COMPAT_FLAG);
+        assertThat(out, arrayContaining("-m", "m.gguf", "--port", "8080"));
+    }
+
+    @Test
+    public void withoutFlagRemovesEveryOccurrence() {
+        String[] out = ServerLauncher.withoutFlag(
+                new String[] {"--open-ai-compat", "-m", "m.gguf", "--open-ai-compat"},
+                ServerLauncher.OPEN_AI_COMPAT_FLAG);
+        assertThat(out, arrayContaining("-m", "m.gguf"));
+    }
+
+    @Test
+    public void withoutFlagIsNoOpWhenAbsent() {
+        String[] in = new String[] {"-m", "m.gguf"};
+        assertThat(ServerLauncher.withoutFlag(in, ServerLauncher.OPEN_AI_COMPAT_FLAG), arrayContaining("-m", "m.gguf"));
+    }
+
+    @Test
+    public void withoutFlagOnEmptyArgsIsEmpty() {
+        assertThat(ServerLauncher.withoutFlag(new String[] {}, ServerLauncher.OPEN_AI_COMPAT_FLAG), is(emptyArray()));
+    }
+}