Skip to content

Run frontier MoE models on hardware you already own β€” pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

fix(windows): give a release archive something to launch

JustVugg8d830c8cef7e
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0c1579ed..5b39d2fe 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -136,6 +136,11 @@ jobs:
mkdir -p dist/tools
cp c/tools/k3_tokenizer.py dist/tools/
cp c/coli dist/
+ # Windows has nothing to click otherwise: `coli` is an extensionless
+ # Python script, and the .exe files are engines that exit at once
+ # without a model (#1241). coli.cmd is both the double-click entry
+ # point and what `coli chat ...` resolves to in cmd/PowerShell.
+ if [ "${{ matrix.ext }}" = ".exe" ]; then cp c/coli.cmd dist/; fi
cp c/version.py dist/
cp c/openai_server.py dist/
cp c/v4_dsml.py dist/ # openai_server imports v4_dsml (vendored DeepSeek V4 DSML primitives); without it the packaged server won't import
diff --git a/README.md b/README.md
index b4effc89..8eff0a01 100644
--- a/README.md
+++ b/README.md
@@ -457,7 +457,11 @@ COLI_MODEL=/nvme/glm52_i4 ./coli tune # measure and save this machine's fast
./coli serve --model /nvme/glm52_i4 # API + dashboard, no browser (headless)
```
-On Windows the same commands work with `python coli chat --model D:\glm52_i4`.
+On Windows a release archive ships `coli.cmd`: double-click it for the quick
+start, or run `coli.cmd chat --model D:\glm52_i4` from cmd or PowerShell.
+From a source checkout the same commands work with `python coli chat --model
+D:\glm52_i4`. The `.exe` files are the engines, not the launcher: started on
+their own they have no model to load and exit immediately.
The engine at runtime is pure C β€” python is only used by the one-time converter
and the optional API gateway.
diff --git a/c/coli.cmd b/c/coli.cmd
new file mode 100644
index 00000000..ed0b7459
--- /dev/null
+++ b/c/coli.cmd
@@ -0,0 +1,60 @@
+@echo off
+rem Windows entry point for a release archive (#1241).
+rem
+rem The archive ships the engines as .exe files and the launcher as `coli`, a
+rem Python script with no extension: on Windows that leaves nothing to click,
+rem and double-clicking an engine opens a console that closes immediately
+rem because the engine has no model. This file is the thing to click, and the
+rem thing to type: `coli chat --model D:\models\glm52_i4` works from cmd and
+rem PowerShell exactly as `./coli chat` does elsewhere.
+setlocal enabledelayedexpansion
+set "COLI_HERE=%~dp0"
+
+rem Find a Python 3. The py launcher ships with python.org installers and is
+rem the only one that stays correct when several versions are installed.
+set "COLI_PY="
+py -3 -c "import sys" >nul 2>&1 && set "COLI_PY=py -3"
+if not defined COLI_PY python -c "import sys; sys.exit(0 if sys.version_info[0]==3 else 1)" >nul 2>&1 && set "COLI_PY=python"
+if not defined COLI_PY python3 -c "import sys" >nul 2>&1 && set "COLI_PY=python3"
+
+if not defined COLI_PY (
+ echo colibri: Python 3 was not found on this machine.
+ echo.
+ echo The engines are pure C and need nothing, but the launcher, the API
+ echo gateway and the model tools are Python. Install Python 3 from
+ echo https://www.python.org/downloads/
+ echo and tick "Add python.exe to PATH" in the installer, then run this again.
+ call :hold
+ exit /b 1
+)
+
+if "%~1"=="" (
+ echo colibri β€” run frontier models from your own storage.
+ echo.
+ echo You are one argument away: this launcher needs a model directory.
+ echo.
+ echo coli.cmd chat --model D:\models\glm52_i4 interactive chat
+ echo coli.cmd serve --model D:\models\glm52_i4 OpenAI-compatible API
+ echo coli.cmd web --model D:\models\glm52_i4 API plus dashboard
+ echo coli.cmd doctor --model D:\models\glm52_i4 check a model is usable
+ echo coli.cmd info what this build supports
+ echo.
+ echo The .exe files next to this script are the ENGINES. They are not meant
+ echo to be started directly: without a model they exit at once, which is why
+ echo double-clicking one only flashes a window.
+ echo.
+ echo Getting a model, step by step:
+ echo https://github.com/JustVugg/colibri/blob/main/docs/quickstart.md
+ call :hold
+ exit /b 0
+)
+
+%COLI_PY% "%COLI_HERE%coli" %*
+exit /b %ERRORLEVEL%
+
+rem Keep the window readable when this script was double-clicked from Explorer.
+rem cmd.exe leaves CMDCMDLINE containing /c when it was started to run us and
+rem will close on exit; a shell the user already had open does not.
+:hold
+echo %CMDCMDLINE% | find /i "/c" >nul && pause
+exit /b 0
diff --git a/c/colibri.c b/c/colibri.c
index 01b89eb5..af563043 100644
--- a/c/colibri.c
+++ b/c/colibri.c
@@ -10610,7 +10610,8 @@ int main(int argc, char **argv){
puts("AVX512 i3 selftest: ok"); return 0;
}
#endif
- const char *snap=getenv("SNAP"); if(!snap){fprintf(stderr,"SNAP=<dir>\n");return 1;}
+ const char *snap=getenv("SNAP");
+ if(!snap){ coli_print_launcher_help("GLM-5.2"); return 1; }
g_nopack = getenv("NOPACK")?1:0;
g_drop = getenv("DROP")?1:0;
g_prefetch = getenv("PREFETCH")?atoi(getenv("PREFETCH")):0;
diff --git a/c/compat.h b/c/compat.h
index 21407cc5..688b560b 100644
--- a/c/compat.h
+++ b/c/compat.h
@@ -537,4 +537,67 @@ static inline void coli_serve_binary_mode(void)
#endif
}
+/* A release archive ships the ENGINES next to the launcher, so on Windows the
+ * first thing a new user does is double-click `colibri.exe` from Explorer. The
+ * engine has no model to load, prints one line and exits -- the console window
+ * appears and vanishes, which reads as "the program does not start" (#1241).
+ *
+ * GetConsoleProcessList reports how many processes share this console: a run
+ * started from a shell has at least the shell too, while a double-click leaves
+ * the engine alone on a console Windows destroys the moment it exits. That is
+ * the only case where holding the window is right, and it is exactly the case
+ * where the message would otherwise be unreadable.
+ *
+ * No-op on Linux/macOS, and no-op on Windows whenever a shell, a script, the
+ * `coli` launcher or CI is on the other end.
+ *
+ * This is the belt, not the braces: an engine that re-execs itself for OpenMP
+ * tuning can still be sharing the console with the exiting parent at the moment
+ * we look, and then the message prints without the pause. `coli.cmd` -- shipped
+ * in the Windows archive and always correct -- is the supported entry point. */
+static inline int coli_console_is_own(void)
+{
+#ifdef _WIN32
+ DWORD owners[2];
+ return GetConsoleProcessList(owners, 2) == 1;
+#else
+ return 0;
+#endif
+}
+
+static inline void coli_hold_console(void)
+{
+ if (!coli_console_is_own()) return;
+ fprintf(stderr, "\nPress Enter to close this window. ");
+ fflush(stderr);
+ int c;
+ while ((c = getchar()) != '\n' && c != EOF) { }
+}
+
+/* One wording for every engine: what this binary is, and the command that does
+ * what the user was trying to do. Called on the "no model" exit path, which is
+ * where a bare launch lands. `engine` is the family name for the message. */
+static inline void coli_print_launcher_help(const char *engine)
+{
+#ifdef _WIN32
+ const char *run = "coli.cmd";
+#else
+ const char *run = "./coli";
+#endif
+ fprintf(stderr,
+ "colibri: this is the %s engine, and it was started without a model.\n"
+ "The engine is not the program you run directly -- the launcher is:\n"
+ "\n"
+ " %s chat --model <model directory> interactive chat\n"
+ " %s serve --model <model directory> OpenAI-compatible API\n"
+ " %s web --model <model directory> API plus the dashboard\n"
+ " %s doctor --model <model directory> check a model is usable\n"
+ "\n"
+ "The launcher needs Python 3 and picks the right engine for the model.\n"
+ "Getting a model, step by step: https://github.com/JustVugg/colibri"
+ "/blob/main/docs/quickstart.md\n",
+ engine, run, run, run, run);
+ coli_hold_console();
+}
+
#endif /* COMPAT_H */
diff --git a/c/deepseek_v4.c b/c/deepseek_v4.c
index aab39182..d352950e 100644
--- a/c/deepseek_v4.c
+++ b/c/deepseek_v4.c
@@ -13977,6 +13977,7 @@ int main(int argc, char **argv) {
double process_started = spec_now();
int result = 1;
V4CliOptions cli;
+ if (argc < 2) { coli_print_launcher_help("DeepSeek V4"); return 1; }
if (v4_cli_parse(argc, argv, &cli)) {
v4_cli_usage(stderr, argc ? argv[0] : "deepseek-v4");
return 2;
diff --git a/c/inkling.c b/c/inkling.c
index d584f244..ebe9210b 100644
--- a/c/inkling.c
+++ b/c/inkling.c
@@ -2353,7 +2353,7 @@ int main(int argc, char **argv) {
#endif /* !COLI_CUDA && !__APPLE__ */
coli_omp_tune_threads("inkling");
const char *snap = getenv("SNAP");
- if (!snap) { fprintf(stderr, "set SNAP=<snapshot directory>\n"); return 1; }
+ if (!snap) { coli_print_launcher_help("Inkling"); return 1; }
g_topp = getenv("TOPP") ? (float)atof(getenv("TOPP")) : 0.f;
if (g_topp > 0.f && g_topp < 1.f)
fprintf(stderr, "[TOPP] %.2f: routed experts kept to cumulative weight β€” "
diff --git a/c/kimi_k3.c b/c/kimi_k3.c
index d327c335..d20ca7ac 100644
--- a/c/kimi_k3.c
+++ b/c/kimi_k3.c
@@ -2958,6 +2958,7 @@ int main(int argc, char **argv){
* below, so an error says what to do instead of only what went wrong. */
if(!serving && (argc<2 || !strcmp(argv[1],"--help") || !strcmp(argv[1],"-h")
|| !strcmp(argv[1],"help"))){
+ if(argc<2){ coli_print_launcher_help("Kimi K3"); return 1; }
k3_usage(argv[0]);
return argc<2 ? 1 : 0; /* asking for help is not a failure */
}
diff --git a/c/olmoe.c b/c/olmoe.c
index 085cac8a..124542ca 100644
--- a/c/olmoe.c
+++ b/c/olmoe.c
@@ -1420,7 +1420,7 @@ static int *read_int_array(jval *o, const char *key, int *n_out) {
int main(int argc, char **argv) {
coli_omp_tune_threads("olmoe"); /* squadra sui core fisici, niente spin-wait: vedi omp_tune.h */
const char *snap = getenv("SNAP");
- if (!snap) { fprintf(stderr, "set SNAP=<snapshot directory>\n"); return 1; }
+ if (!snap) { coli_print_launcher_help("OLMoE"); return 1; }
g_pilot = getenv("PILOT") ? atoi(getenv("PILOT")) : 0;
g_wide = getenv("WIDE") ? atoi(getenv("WIDE")) : 1;
g_pilot_evict_guard = getenv("PILOT_EVICT_GUARD") ? atoi(getenv("PILOT_EVICT_GUARD")) : 1;
diff --git a/c/qwen36.c b/c/qwen36.c
index f7271117..352d3e49 100644
--- a/c/qwen36.c
+++ b/c/qwen36.c
@@ -2502,7 +2502,7 @@ static void serve_loop(Model *m){
int main(int argc, char **argv) {
const char *snap = getenv("SNAP");
- if (!snap) { fprintf(stderr, "set SNAP=<snapshot directory>\n"); return 1; }
+ if (!snap) { coli_print_launcher_help("Qwen3.6"); return 1; }
g_pilot = getenv("PILOT") ? atoi(getenv("PILOT")) : 0;
g_wide = getenv("WIDE") ? atoi(getenv("WIDE")) : 1;
if (g_wide < 1) g_wide = 1; if (g_wide > 4) g_wide = 4;
diff --git a/docs/windows.md b/docs/windows.md
index 3543e2be..e92cbfe5 100644
--- a/docs/windows.md
+++ b/docs/windows.md
@@ -2,6 +2,28 @@
A start-to-finish, reproducible path from a fresh Windows 11 machine to GLM-5.2 generating tokens, with the GPU tier. Every step and every failure mode below was hit and verified on real hardware: Core Ultra 9 285K (AVX-VNNI) / RTX 5080 (sm_120) / 128 GB RAM / Windows 11 24H2 (issue #306). Steps are ordered so the long downloads run while you build.
+---
+
+## If you downloaded a release archive, start here
+
+The archive contains **`coli.cmd`**: that is the program to run. Double-click it
+for the quick start, or from cmd/PowerShell:
+
+```
+coli.cmd chat --model D:\models\glm52_i4
+coli.cmd serve --model D:\models\glm52_i4
+coli.cmd doctor --model D:\models\glm52_i4
+```
+
+`colibri.exe`, `kimi_k3.exe` and the other `.exe` files are the **engines**.
+They are selected by the launcher from the model's `config.json`; started on
+their own they have no model to load, print how to launch and exit, which from
+Explorer looks like a window that flashes and disappears (#1241). The launcher
+needs Python 3 from https://www.python.org/downloads/ with "Add python.exe to
+PATH" ticked; the engines themselves need nothing.
+
+The rest of this page is for building from source.
+
---
> **2026-08-11: Additional validation with detailed steps for laptop setup** \
Lenovo Thinkpad P16v (Intel Core i7 ultra (155H 1.4GHz), 64GB RAM, 2Tb NVME drive, Nvidia RTX 2000 Ada generation 8GB (AD107, 2023)).