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

Desktop log file plus a passwords, logs and uninstall FAQ (#1002)

Tashfeen90aaa5bc02c2
diff --git a/README.md b/README.md
index 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-provid
One 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)**.
+
## Limitations
Stacking 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 the
diff --git a/desktop/src/tray.ts b/desktop/src/tray.ts
index 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.md
index 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.md
index 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 an
install. 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.