Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(desktop): monorepo layout — build against in-repo server/client, build-your-own packaging

Tashfeen1dac1b7ace1b
diff --git a/README.md b/README.md
index 3df01f52..1b6c9750 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ Aggregate the free tiers from Google, Groq, Cerebras, SambaNova, NVIDIA, Mistral
- [Not yet supported](#not-yet-supported)
- [Quick start](#quick-start)
- [Docker](#docker)
+- [Desktop app](#desktop-app)
- [Using the API](#using-the-api)
- [Screenshots](#screenshots)
- [How it works](#how-it-works)
@@ -182,6 +183,22 @@ SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`. Kee
More Docker operations and examples live in [docker/README.md](./docker/README.md).
+## Desktop app
+
+A native menu-bar app for macOS (Windows config included, untested) lives in
+[`desktop/`](./desktop): the entire router + dashboard running locally from your
+tray, with a glass popover showing live request stats. No published binaries —
+it builds from this repo in a few minutes:
+
+```bash
+npm install
+npm run desktop:dist # macOS: desktop/dist-electron/FreeLLMAPI-…-arm64.dmg
+npm run desktop:dist:win # Windows installer (untested — PRs welcome)
+```
+
+Locally built apps launch without Gatekeeper/SmartScreen warnings — no code
+signing involved. Full instructions in [desktop/README.md](./desktop/README.md).
+
## Using the API
Any OpenAI-compatible client works. Examples:
diff --git a/desktop/README.md b/desktop/README.md
index e1e21845..0972c96c 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -5,51 +5,56 @@ runs the whole router locally on `127.0.0.1:31415`, with a dark-glass tray
popover (live 24h request chart, quick stats, copy URL/key) and the full
dashboard in a native-feeling window.
-## Layout requirement
+The app lives in the main repo (`desktop/`) and builds against the server and
+client sources in the same checkout — no extra setup, no published binaries:
+**you build it yourself** (a few minutes, commands below).
-This repo builds against a **sibling checkout** of the main repo:
+## Prerequisites
-```
-…/experiments/
- freeapi/ # the freellmapi repo (server + client sources)
- freeapi-desktop/ # this repo
-```
+- Node.js 20+
+- A native build toolchain for `better-sqlite3`:
+ - **macOS** — Xcode Command Line Tools (`xcode-select --install`)
+ - **Windows** — Visual Studio Build Tools ("Desktop development with C++")
-A different location can be set with `FREEAPI_REPO=/path/to/freeapi` (dev
-runtime); the esbuild import paths in `src/server-host.ts` and the
-`extraResources` entry in `electron-builder.yml` assume the sibling layout.
+## Build it yourself
-The sibling checkout must include the embedder hooks (`CLIENT_DIST` /
-`FREEAPI_ENV_PATH` env overrides in the server, desktop-mode navbar in the
-client) and a built `client/dist`:
+From the **repo root** (one-time client build + package):
```bash
-cd ../freeapi
npm install
-npm run build -w client
+npm run desktop:dist # macOS → desktop/dist-electron/FreeLLMAPI-…-arm64.dmg
+npm run desktop:dist:win # Windows → desktop/dist-electron/FreeLLMAPI-…-x64 installer
```
+> Locally built apps don't carry the macOS quarantine attribute or Windows
+> Mark-of-the-Web, so they launch without Gatekeeper/SmartScreen warnings —
+> no code signing needed.
+>
+> The Windows build is config-complete but largely untested — issues and PRs
+> welcome.
+
## Develop
```bash
+cd desktop
npm install
npm run rebuild:native # better-sqlite3 against Electron's ABI (dev loop only)
npm run dev # bundle + launch
```
+The dev run serves the repo's own `client/dist` — build it first
+(`npm run build -w client` from the root) or use `npm run desktop:dev` from
+the root, which does both. `FREEAPI_REPO=/path/to/checkout` overrides the
+client/server source location if you ever need a different one.
+
UI iteration helpers (dev only): `FREEAPI_SHOT=1 npx electron .` captures the
popover + dashboard to /tmp and quits; `FREEAPI_SHOT=hold` pins the popover
open for real-screen captures.
-## Package
-
-```bash
-npm run dist # electron-builder → dist-electron/FreeLLMAPI-…-arm64.dmg
-```
-
## Notes
-- DB + config live in `~/Library/Application Support/FreeLLMAPI/`.
+- DB + config live in `~/Library/Application Support/FreeLLMAPI/` (macOS) /
+ `%APPDATA%/FreeLLMAPI/` (Windows).
- The server binds loopback only; default port 31415, scan-up on conflict,
resolved port persisted.
- Do not run plain `npm rebuild` here — it rebuilds better-sqlite3 for the
diff --git a/desktop/electron-builder.yml b/desktop/electron-builder.yml
index b08d5a98..1d302c4e 100644
--- a/desktop/electron-builder.yml
+++ b/desktop/electron-builder.yml
@@ -12,7 +12,7 @@ asarUnpack:
- "**/node_modules/better-sqlite3/**/*.node"
- "**/node_modules/better-sqlite3/build/Release/**"
extraResources:
- - from: ../freeapi/client/dist
+ - from: ../client/dist
to: client-dist
mac:
category: public.app-category.developer-tools
@@ -28,7 +28,8 @@ win:
- target: nsis
arch:
- x64
- icon: assets/icon.ico
+ # electron-builder converts a >=256px PNG to .ico at build time.
+ icon: assets/appicon_1024.png
nsis:
oneClick: true
deleteAppDataOnUninstall: false
diff --git a/desktop/package.json b/desktop/package.json
index 53d8e28e..a3ea3ee6 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -12,7 +12,8 @@
"build:all": "npm run bundle:server && npm run build:main && npm run build:preload",
"rebuild:native": "electron-rebuild -f -w better-sqlite3",
"dev": "npm run build:all && electron .",
- "dist": "npm run build:all && electron-builder --mac --arm64"
+ "dist": "npm run build:all && electron-builder --mac --arm64",
+ "dist:win": "npm run build:all && electron-builder --win --x64"
},
"dependencies": {
"better-sqlite3": "^12.4.1"
diff --git a/desktop/src/main.ts b/desktop/src/main.ts
index aaaec6fc..34d8c046 100644
--- a/desktop/src/main.ts
+++ b/desktop/src/main.ts
@@ -74,9 +74,9 @@ if (!app.requestSingleInstanceLock()) {
const cfg = loadConfig();
const dbPath = path.join(app.getPath('userData'), 'freeapi.db');
// Packaged: client/dist ships in extraResources (Resources/client-dist).
- // Dev: use the sibling freellmapi checkout's client/dist (FREEAPI_REPO
- // overrides the default ../freeapi location).
- const repoRoot = process.env.FREEAPI_REPO ?? path.resolve(__dirname, '../../freeapi');
+ // Dev: use this repo's own client/dist (desktop/ lives in the monorepo;
+ // FREEAPI_REPO can still point at a different checkout if ever needed).
+ const repoRoot = process.env.FREEAPI_REPO ?? path.resolve(__dirname, '../..');
const clientDist = app.isPackaged
? path.join(process.resourcesPath, 'client-dist')
: path.join(repoRoot, 'client/dist');
diff --git a/desktop/src/server-host.ts b/desktop/src/server-host.ts
index 7d288f90..af3322ed 100644
--- a/desktop/src/server-host.ts
+++ b/desktop/src/server-host.ts
@@ -4,16 +4,15 @@
// (auth bootstrap, getDb) must be exported from here rather than imported
// from server/src by the main bundle (which would get a second, empty copy).
//
-// The server sources come from the sibling freellmapi checkout
-// (../freeapi — see README). Keep these relative imports in sync with the
-// FREEAPI_REPO default in main.ts and scripts/bundle-server.mjs.
-import '../../freeapi/server/src/env.js';
+// The server sources live in this same repo (../../server). Keep these
+// relative imports in sync with the repo-root default in main.ts.
+import '../../server/src/env.js';
import crypto from 'node:crypto';
import type { Server } from 'node:http';
-import { createApp } from '../../freeapi/server/src/app.js';
-import { initDb, getDb, getUnifiedApiKey } from '../../freeapi/server/src/db/index.js';
-import { startHealthChecker } from '../../freeapi/server/src/services/health.js';
-import { userCount, createUser, createSession } from '../../freeapi/server/src/services/auth.js';
+import { createApp } from '../../server/src/app.js';
+import { initDb, getDb, getUnifiedApiKey } from '../../server/src/db/index.js';
+import { startHealthChecker } from '../../server/src/services/health.js';
+import { userCount, createUser, createSession } from '../../server/src/services/auth.js';
export { getDb, getUnifiedApiKey };
diff --git a/package.json b/package.json
index aa0a8d8e..bcd71117 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,10 @@
"dev": "concurrently --kill-others-on-fail --names server,client \"npm run dev -w server\" \"npm run dev -w client\"",
"test": "npm run test -w server && npm run test -w client --if-present",
"build": "npm run build -w server && npm run build -w client",
- "build:server": "npm run build -w server"
+ "build:server": "npm run build -w server",
+ "desktop:dev": "npm run build -w client && npm --prefix desktop run dev",
+ "desktop:dist": "npm run build -w client && npm --prefix desktop run dist",
+ "desktop:dist:win": "npm run build -w client && npm --prefix desktop run dist:win"
},
"devDependencies": {
"concurrently": "^9.1.2"