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
Desktop log file plus a passwords, logs and uninstall FAQ (#1002)
Tashfeen90aaa5bc02c2
diff --git a/README.md b/README.mdindex 3c349c6c..977ca8d7 100644--- a/README.md+++ b/README.md@@ -49,6 +49,7 @@ Your router updates its own model catalog from a signed feed: new free models, q- [Using the API](#using-the-api)- [Screenshots](#screenshots)- [How it works](#how-it-works)+- [FAQ](#faq)- [Limitations](#limitations)- [Contributing](#contributing)- [Disclaimer](#disclaimer)@@ -325,6 +326,18 @@ Request volume, success rate, tokens in and out, average latency, and per-providOne request in, the best free model out: the router picks the highest-priority model with a healthy key that's under all its rate limits, decrypts the key in memory, and calls the provider — on a 429/5xx it cools that key down and retries the next model in your chain. The component walkthrough, routing internals, and operational details live in **[docs/architecture.md](docs/architecture.md)**.+## FAQ++**Do I need a password?** Not for the desktop app — the dashboard signs itself in with a hidden local account, so there is nothing to set up and nothing to forget. Open it from the tray icon → **Open Dashboard**. Server installs (Docker, one-liner, `npm run dev`) do have an email + password account.++**I forgot the password on a server install.** Click **Forgot password?** on the login page. There is no email to send a link to, so the one-time code is printed to the server log — read it with `docker compose logs -f freellmapi` (or in the terminal running the server, or in the desktop log file), then enter it on the reset form. The code lasts 15 minutes.++**Where are the logs?** In the container log for Docker, in the terminal for a source run, and in `<data dir>/logs/freeapi.log` for the desktop app — reachable from the tray menu's **Open Logs Folder**.++**How do I uninstall?** Remove the app (Trash on macOS, *Settings → Apps* on Windows, `docker compose down -v` for Docker), then delete the data directory: `%APPDATA%\FreeLLMAPI\`, `~/Library/Application Support/FreeLLMAPI/`, or `~/.config/FreeLLMAPI/`. Uninstalling never touches that folder on its own.++Longer answers, per install method: **[docs/install.md#faq-passwords-logs-uninstall](docs/install.md#faq-passwords-logs-uninstall)**.+## LimitationsStacking free tiers has real trade-offs: no frontier models, variable latency, no SLA — and the effective intelligence of the endpoint dips late in the day as top models hit their daily caps, then resets at UTC midnight. Read the honest list in **[docs/architecture.md#limitations](docs/architecture.md#limitations)** before building anything real on this.diff --git a/desktop/src/__tests__/logger.test.ts b/desktop/src/__tests__/logger.test.tsnew file mode 100644index 00000000..67a158d6--- /dev/null+++ b/desktop/src/__tests__/logger.test.ts@@ -0,0 +1,104 @@+import { describe, it, expect, afterAll, beforeEach, afterEach, vi } from 'vitest';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';++// #824: a user could not find the password-reset code because the desktop app+// prints it to a stdout nobody is attached to. The fix is a file log, so the+// thing worth asserting is that the reset code actually reaches the file.++const userData = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-logger-'));++vi.mock('electron', () => ({+ app: { getPath: () => userData },+ shell: { openPath: vi.fn() },+}));++const { createFileSink, installFileLogger, logFilePath, logsDir } = await import('../logger.js');+const { generateResetCode } = await import('../../../server/src/lib/reset-code.js');++afterAll(() => {+ // The tee keeps its file handle open until process exit, and Windows refuses+ // to unlink an open file — cleanup is a courtesy, not an assertion.+ try {+ fs.rmSync(userData, { recursive: true, force: true });+ } catch {+ // leave it to the OS temp sweeper+ }+});++describe('desktop file sink', () => {+ let dir: string;++ beforeEach(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-sink-'));+ });++ afterEach(() => {+ fs.rmSync(dir, { recursive: true, force: true });+ });++ it('appends lines to freeapi.log, creating the directory', () => {+ const nested = path.join(dir, 'logs');+ const sink = createFileSink(nested);+ sink.write('first');+ sink.write('second');+ sink.close();+ expect(fs.readFileSync(path.join(nested, 'freeapi.log'), 'utf8')).toBe('first\nsecond\n');+ });++ it('keeps appending across sink instances rather than truncating', () => {+ const first = createFileSink(dir);+ first.write('one');+ first.close();+ const second = createFileSink(dir);+ second.write('two');+ second.close();+ expect(fs.readFileSync(path.join(dir, 'freeapi.log'), 'utf8')).toBe('one\ntwo\n');+ });++ it('rotates to freeapi.log.1 at the size limit and keeps only two files', () => {+ const sink = createFileSink(dir, 40);+ sink.write('a'.repeat(30)); // 31 bytes+ sink.write('b'.repeat(30)); // would cross 40 → rotate first+ sink.write('c'.repeat(30)); // crosses again → rotate again, dropping the a's+ sink.close();+ expect(fs.readFileSync(path.join(dir, 'freeapi.log'), 'utf8')).toBe(`${'c'.repeat(30)}\n`);+ expect(fs.readFileSync(path.join(dir, 'freeapi.log.1'), 'utf8')).toBe(`${'b'.repeat(30)}\n`);+ expect(fs.readdirSync(dir).sort()).toEqual(['freeapi.log', 'freeapi.log.1']);+ });++ it('swallows filesystem errors instead of throwing at the caller', () => {+ const file = path.join(dir, 'blocked');+ fs.writeFileSync(file, '');+ // A file where the log directory should be: every fs call fails.+ const sink = createFileSink(file);+ expect(() => sink.write('nope')).not.toThrow();+ expect(() => sink.close()).not.toThrow();+ });+});++describe('console tee', () => {+ // Spy first, install second: the tee captures whatever console.log is at+ // install time, so the spy stands in for the original console it must keep+ // calling.+ const passthrough = vi.spyOn(console, 'log');+ installFileLogger();++ it('writes the password-reset code to the log file the user can open', () => {+ expect(logsDir()).toBe(path.join(userData, 'logs'));++ const code = generateResetCode();+ const written = fs.readFileSync(logFilePath(), 'utf8');++ expect(written).toContain(`Password-reset code: ${code}`);+ expect(written).toContain('Enter this code on the reset form');+ });++ it('still prints to the real console so a terminal run is unchanged', () => {+ passthrough.mockClear();+ console.log('hello from the tee');+ expect(passthrough).toHaveBeenCalledWith('hello from the tee');+ expect(fs.readFileSync(logFilePath(), 'utf8')).toContain('hello from the tee');+ });+});diff --git a/desktop/src/i18n.ts b/desktop/src/i18n.tsindex 14a6f372..fd21a808 100644--- a/desktop/src/i18n.ts+++ b/desktop/src/i18n.ts@@ -29,6 +29,7 @@ const STRINGS: Record<NativeLocale, Strings> = {runningOn: 'Running on {addr}',openDashboard: 'Open Dashboard',lanAccess: 'Allow LAN access (0.0.0.0)',+ openLogs: 'Open Logs Folder',quitApp: 'Quit FreeLLMAPI',running: 'running',requestsToday: 'Requests today',@@ -49,6 +50,7 @@ const STRINGS: Record<NativeLocale, Strings> = {runningOn: '运行于 {addr}',openDashboard: '打开仪表板',lanAccess: '允许局域网访问 (0.0.0.0)',+ openLogs: '打开日志文件夹',quitApp: '退出 FreeLLMAPI',running: '运行中',requestsToday: '今日请求',@@ -69,6 +71,7 @@ const STRINGS: Record<NativeLocale, Strings> = {runningOn: 'En cours sur {addr}',openDashboard: 'Ouvrir le tableau de bord',lanAccess: 'Autoriser l\'accès LAN (0.0.0.0)',+ openLogs: 'Ouvrir le dossier des journaux',quitApp: 'Quitter FreeLLMAPI',running: 'en cours',requestsToday: "Requêtes aujourd'hui",@@ -89,6 +92,7 @@ const STRINGS: Record<NativeLocale, Strings> = {runningOn: 'En ejecución en {addr}',openDashboard: 'Abrir el panel',lanAccess: 'Permitir acceso LAN (0.0.0.0)',+ openLogs: 'Abrir la carpeta de registros',quitApp: 'Salir de FreeLLMAPI',running: 'en ejecución',requestsToday: 'Solicitudes hoy',@@ -109,6 +113,7 @@ const STRINGS: Record<NativeLocale, Strings> = {runningOn: 'Em execução em {addr}',openDashboard: 'Abrir o painel',lanAccess: 'Permitir acesso LAN (0.0.0.0)',+ openLogs: 'Abrir a pasta de logs',quitApp: 'Sair do FreeLLMAPI',running: 'em execução',requestsToday: 'Solicitações hoje',@@ -129,6 +134,7 @@ const STRINGS: Record<NativeLocale, Strings> = {runningOn: 'In esecuzione su {addr}',openDashboard: 'Apri il pannello',lanAccess: 'Consenti accesso LAN (0.0.0.0)',+ openLogs: 'Apri la cartella dei log',quitApp: 'Esci da FreeLLMAPI',running: 'in esecuzione',requestsToday: 'Richieste oggi',diff --git a/desktop/src/logger.ts b/desktop/src/logger.tsnew file mode 100644index 00000000..665fdf53--- /dev/null+++ b/desktop/src/logger.ts@@ -0,0 +1,125 @@+// A file log for the desktop app (#824).+//+// The embedded server writes operational output to the console — including the+// one-time password-reset code, which POST /api/auth/forgot-password prints and+// nothing else ever shows. A server operator reads it from `docker logs` or the+// terminal; a Finder/Explorer-launched Electron app has no attached stdout, so+// that code was unreadable and the reset flow could never be completed.+//+// So tee console output into <userData>/logs/freeapi.log. Writes are synchronous+// (a code printed a moment before the app quits must already be on disk) and+// every filesystem call is wrapped: logging must never be the reason the app+// fails to start.+import fs from 'node:fs';+import path from 'node:path';+import util from 'node:util';+import { app, shell } from 'electron';++const LOG_NAME = 'freeapi.log';+// Two files, 1 MB each: enough history to cover a reset or a bad boot, small+// enough that nobody's disk notices.+const MAX_LOG_BYTES = 1024 * 1024;+const PREVIOUS_NAME = `${LOG_NAME}.1`;++export function logsDir(): string {+ return path.join(app.getPath('userData'), 'logs');+}++export function logFilePath(): string {+ return path.join(logsDir(), LOG_NAME);+}++export interface FileSink {+ write(line: string): void;+ close(): void;+}++// The sink itself, free of electron so it can be exercised in tests: appends to+// <dir>/freeapi.log and rotates it to freeapi.log.1 once it passes maxBytes.+export function createFileSink(dir: string, maxBytes: number = MAX_LOG_BYTES): FileSink {+ const current = path.join(dir, LOG_NAME);+ const previous = path.join(dir, PREVIOUS_NAME);+ let fd: number | null = null;+ let size = 0;++ function open(): void {+ fs.mkdirSync(dir, { recursive: true });+ fd = fs.openSync(current, 'a');+ size = fs.fstatSync(fd).size;+ }++ function rotate(): void {+ if (fd !== null) {+ fs.closeSync(fd);+ fd = null;+ }+ fs.rmSync(previous, { force: true });+ fs.renameSync(current, previous);+ open();+ }++ return {+ write(line: string): void {+ try {+ if (fd === null) open();+ const buf = Buffer.from(line.endsWith('\n') ? line : `${line}\n`, 'utf8');+ // Rotate before the write that would cross the limit, never on an empty+ // file — a single line longer than maxBytes must not loop.+ if (size > 0 && size + buf.length > maxBytes) rotate();+ fs.writeSync(fd as number, buf);+ size += buf.length;+ } catch {+ // A read-only or full disk is not worth crashing over; drop the line.+ }+ },+ close(): void {+ try {+ if (fd !== null) fs.closeSync(fd);+ } catch {+ // already gone+ }+ fd = null;+ },+ };+}++let installed = false;++// Wrap console.log/info/warn/error so everything the app and the embedded+// server print also lands in the log file. The original console is still+// called, so `npm run dev` output is unchanged.+export function installFileLogger(dir: string = logsDir()): void {+ if (installed) return;+ installed = true;+ let sink: FileSink;+ try {+ sink = createFileSink(dir);+ } catch {+ return;+ }+ for (const level of ['log', 'info', 'warn', 'error'] as const) {+ const original = console[level].bind(console);+ console[level] = (...args: unknown[]): void => {+ original(...args);+ try {+ sink.write(`${new Date().toISOString()} [${level}] ${util.format(...args)}`);+ } catch {+ // never let logging break the caller+ }+ };+ }+ process.on('exit', () => sink.close());+ console.log(`[desktop] writing logs to ${path.join(dir, LOG_NAME)}`);+}++// Tray → "Open Logs Folder". Create the directory first so the reveal works+// even before anything has been written.+export function openLogsFolder(): void {+ try {+ const dir = logsDir();+ fs.mkdirSync(dir, { recursive: true });+ void shell.openPath(dir);+ } catch (err) {+ console.warn('[desktop] could not open the logs folder:', err);+ }+}diff --git a/desktop/src/main.ts b/desktop/src/main.tsindex e1b3fca8..eb6a750d 100644--- a/desktop/src/main.ts+++ b/desktop/src/main.ts@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';import { app, dialog, ipcMain, clipboard, nativeTheme, shell } from 'electron';import { startServer, ensureSessionToken, getUnifiedApiKey } from './server.mjs';import { loadConfig, saveConfig } from './config.js';+import { installFileLogger } from './logger.js';import { buildTray, refreshTrayLocale } from './tray.js';import { openDashboard } from './window.js';import { todayStats, hourlyRequests, successRateToday } from './stats.js';@@ -20,6 +21,11 @@ app.setPath('userData', path.join(app.getPath('appData'), 'FreeLLMAPI'));if (!app.requestSingleInstanceLock()) {app.quit();} else {+ // Before anything else can print: a packaged app has no attached stdout, so+ // without this the server's console output — the password-reset code above+ // all (#824) — is written nowhere the user can read it.+ installFileLogger();+let resolvedPort = DEFAULT_PORT;let sessionToken = '';// The dashboard owns the theme (its Settings dialog); the popover and thediff --git a/desktop/src/tray.ts b/desktop/src/tray.tsindex ae95c54e..3ad742eb 100644--- a/desktop/src/tray.ts+++ b/desktop/src/tray.ts@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';import { Tray, Menu, app, nativeImage } from 'electron';import { togglePopover } from './popover.js';import { openDashboard } from './window.js';+import { openLogsFolder } from './logger.js';import { dt, type NativeLocale } from './i18n.js';const __dirname = path.dirname(fileURLToPath(import.meta.url));@@ -38,6 +39,9 @@ export function buildTray({ type: 'separator' },// Toggling relaunches the app (the bind host is fixed at server start).{ label: dt(locale, 'lanAccess'), type: 'checkbox', checked: lanOn, click: () => onToggleLanAccess() },+ // #824: the password-reset code is printed to the log and nowhere else,+ // so the folder holding it needs to be reachable without a terminal.+ { label: dt(locale, 'openLogs'), click: () => openLogsFolder() },{ type: 'separator' },{ label: dt(locale, 'quitApp'), click: () => app.quit() },]));diff --git a/docs/README.md b/docs/README.mdindex 1431d1b1..42660a71 100644--- a/docs/README.md+++ b/docs/README.md@@ -6,7 +6,7 @@ The root [README](../README.md) is the product overview; the detailed guides liv## Guides-- **[Install & deploy](install.md)** — quick start, Docker Compose, local development, declarative startup config, the Docker image, backups, the desktop app, and where your data lives.+- **[Install & deploy](install.md)** — quick start, Docker Compose, local development, declarative startup config, the Docker image, backups, the desktop app, where your data lives, and an FAQ on password resets, logs and uninstalling.- **[API reference](api.md)** — chat completions, `auto:*` routing strategies, streaming, tool calling, vision, Gemini Google Search grounding, embeddings, response headers, and the Anthropic Messages surface.- **[Clients & coding agents](clients.md)** — OpenAI-compatible clients, recipes for Claude Code / Codex CLI / Cline / Continue / Aider / opencode / Cursor, the MCP server, editor autocomplete, and Context Handoff.- **[Prompt compression](compression.md)** — request-side modes, safeguards, per-request controls, custom tool-output filters, statistics, and preview APIs.diff --git a/docs/install.md b/docs/install.mdindex 2f629e73..083446bd 100644--- a/docs/install.md+++ b/docs/install.md@@ -4,7 +4,7 @@[← Back to README](../README.md) · [Documentation index](README.md)-Everything about getting FreeLLMAPI running: the one-liner, Docker Compose, local development, declarative config, production builds, the desktop app, and where your data lives.+Everything about getting FreeLLMAPI running: the one-liner, Docker Compose, local development, declarative config, production builds, the desktop app, where your data lives, and how to reset a password, read the logs, or uninstall.- [Quick start (one-liner)](#quick-start-one-liner)- [Docker Compose](#docker-compose)@@ -13,6 +13,7 @@ Everything about getting FreeLLMAPI running: the one-liner, Docker Compose, loca- [Docker image & operations](#docker-image--operations)- [Desktop app](#desktop-app)- [Credentials and where your data lives](#credentials-and-where-your-data-lives)+- [FAQ: passwords, logs, uninstall](#faq-passwords-logs-uninstall)## Quick start (one-liner)@@ -266,8 +267,85 @@ another machine or into a container):| macOS | `~/Library/Application Support/FreeLLMAPI/` || Linux | `~/.config/FreeLLMAPI/` |-That folder holds `freeapi.db` (all keys, models, settings, encrypted at rest)-and `config.json` (window/theme/port/LAN preferences). Copy both to move an+That folder holds `freeapi.db` (all keys, models, settings, encrypted at rest),+`config.json` (window/theme/port/LAN preferences) and `logs/freeapi.log` (what+the app would print to a terminal if it had one). Copy the first two to move aninstall. For the server (non-desktop) deployment, the equivalent state is the`.env` file and the SQLite DB at `server/data/freeapi.db` (or wherever`FREEAPI_DB_PATH` points).++## FAQ: passwords, logs, uninstall++### I forgot my dashboard password++**Desktop app — there is no password.** The dashboard signs itself in with a+hidden local account, so there is nothing to remember and nothing to reset. If+you cannot see the dashboard, open it from the tray icon → **Open Dashboard**.++**Server installs** (Docker, one-liner, `npm run dev`) do have an email ++password account, and there is no email delivery to send a reset link to. The+flow is a one-time code printed to the server log:++1. On the login page, click **Forgot password?**, then **Send reset code**.+2. Read the code from the server log (see below). It looks like this:++ ```+ Password-reset code: HWNHPU5QGZ+ Enter this code on the reset form to set a new password.+ ```++3. Type it into the reset form together with your new password.++The code is valid for **15 minutes**, and requesting a new one invalidates the+previous code. Requests are rate-limited, so ask for one code and wait for it+rather than clicking repeatedly.++### Where are the logs?++| Install method | Where the log goes |+|----------------|--------------------|+| Docker Compose | `docker compose logs -f freellmapi` |+| Plain Docker | `docker logs -f <container>` (`docker ps` lists the name) |+| One-liner install | `cd ~/freellmapi && docker compose logs -f freellmapi` |+| `npm run dev` / `node server/dist/index.js` | the terminal the server is running in |+| Desktop app | `<data dir>/logs/freeapi.log` — tray icon → right-click → **Open Logs Folder** |++The desktop app has no terminal attached, so it also tees everything it prints+to a file: `freeapi.log` in the `logs` folder inside the data directory listed+[above](#credentials-and-where-your-data-lives) — for example+`~/Library/Application Support/FreeLLMAPI/logs/freeapi.log` on macOS. It keeps+the current file plus one rotated `freeapi.log.1`, 1 MB each. Open it in any+text editor; the reset code above appears there too.++### How do I uninstall?++Removing the app never removes your data directory — deleting that is a+separate, deliberate step, which is also what makes it safe to reinstall over+the top.++**Desktop app**++1. Quit from the tray menu (**Quit FreeLLMAPI**). If you turned on *Start at+ login* in the popover, switch it off first so no stale login item is left.+2. Remove the application:+ - **macOS** — drag `FreeLLMAPI.app` from `/Applications` to the Trash.+ - **Windows** — *Settings → Apps → Installed apps → FreeLLMAPI → Uninstall*.+ - **Linux** — delete the AppImage, or `sudo apt remove freellmapi` for the `.deb`.+3. Delete the data directory to remove your keys, settings and logs for good:+ - **Windows** — `%APPDATA%\FreeLLMAPI\`+ - **macOS** — `~/Library/Application Support/FreeLLMAPI/`+ - **Linux** — `~/.config/FreeLLMAPI/`++**Docker**++```bash+docker compose down -v # -v also drops the freellmapi-data volume+docker image rm ghcr.io/tashfeenahmed/freellmapi:latest+rm -rf ~/freellmapi # the one-liner's directory: .env + compose file+```++Leave off `-v` if you want to keep the database for a later reinstall.++**From source** — delete the checkout. The state that matters is `.env` and+`server/data/freeapi.db` (or wherever `FREEAPI_DB_PATH` points), so back those+up first if you plan to come back.