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

Fix top issues: x-api-key auth (#103), /v1 rate limiting (#35), LAN docs (#147) (#151)

Tashfeenca7cb9ee02c8
diff --git a/.env.example b/.env.example
index fe9dd0ef..677a0666 100644
--- a/.env.example
+++ b/.env.example
@@ -4,6 +4,18 @@ ENCRYPTION_KEY=your-64-char-hex-key-here
# Server port (default: 3001)
PORT=3001
+# Docker only: which host interface the container's port is published on.
+# Defaults to 127.0.0.1, so the dashboard/API is reachable only from the
+# machine running Docker. To open it to other devices on your LAN (e.g. a
+# Raspberry Pi reached at http://192.168.1.x:3001), set HOST_BIND=0.0.0.0.
+# Only do this on a trusted network — the proxy is single-user and guarded
+# only by the unified API key.
+# HOST_BIND=0.0.0.0
+
+# Max /v1 proxy requests per minute per client IP (default: 120). Set to 0
+# to disable proxy rate limiting.
+# PROXY_RATE_LIMIT_RPM=120
+
# Comma-separated extra origins allowed to call the API from a browser.
# localhost:5173, 127.0.0.1:5173, [::1]:5173 are allowed by default for the
# Vite dev dashboard. Only set this if you serve the dashboard from a
diff --git a/README.md b/README.md
index bb8b9c3b..cac8df02 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,14 @@ docker compose up -d
Open http://localhost:3001, add your provider keys on the **Keys** page, reorder the **Fallback Chain** to taste, and grab your unified API key from the **Keys** page header. That unified key is what you point your OpenAI SDK at.
+> **Reaching it from another machine?** By default the container is published only on `127.0.0.1`, so `http://<server-ip>:3001` won't load from another device (the page just hangs). To expose it on your LAN — e.g. a Raspberry Pi at `http://192.168.1.x:3001` — start it with `HOST_BIND=0.0.0.0`:
+>
+> ```bash
+> HOST_BIND=0.0.0.0 docker compose up -d
+> ```
+>
+> Only do this on a trusted network: the proxy is single-user and guarded only by the unified API key.
+
### Local development
**Prerequisites:** Node.js 20+, npm.
@@ -165,6 +173,8 @@ docker compose up -d
docker compose logs -f freellmapi
```
+By default the container's port is bound to `127.0.0.1` (localhost only). To reach the dashboard/API from another machine on your network, publish it on all interfaces with `HOST_BIND=0.0.0.0 docker compose up -d` — only on a trusted LAN, since the proxy is single-user.
+
SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`. Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because provider keys are encrypted at rest.
More Docker operations and examples live in [docker/README.md](./docker/README.md).
diff --git a/server/src/__tests__/routes/proxy-auth-cors.test.ts b/server/src/__tests__/routes/proxy-auth-cors.test.ts
index 3f43b3ce..d0431151 100644
--- a/server/src/__tests__/routes/proxy-auth-cors.test.ts
+++ b/server/src/__tests__/routes/proxy-auth-cors.test.ts
@@ -1,7 +1,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import type { Express } from 'express';
import { createApp } from '../../app.js';
-import { initDb } from '../../db/index.js';
+import { initDb, getUnifiedApiKey } from '../../db/index.js';
async function request(app: Express, method: string, path: string, body?: any, headers: Record<string, string> = {}) {
const server = app.listen(0);
@@ -41,6 +41,29 @@ describe('Proxy authentication and CORS', () => {
expect(body.error.type).toBe('authentication_error');
});
+ // #103: Claude Code via CC Switch (and other Anthropic-format clients) send
+ // the key in the `x-api-key` header, not as an Authorization bearer token.
+ it('rejects a wrong key supplied via the x-api-key header', async () => {
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ messages: [{ role: 'user', content: 'hello' }],
+ }, { 'x-api-key': 'freellmapi-wrong-key' });
+
+ expect(status).toBe(401);
+ expect(body.error.type).toBe('authentication_error');
+ });
+
+ it('accepts the unified key supplied via the x-api-key header', async () => {
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ messages: [{ role: 'user', content: 'hello' }],
+ }, { 'x-api-key': getUnifiedApiKey() });
+
+ // Auth passes — it gets past the 401 gate. (Routing then fails because no
+ // provider keys are configured in this test DB, which is fine: we only
+ // care that the x-api-key header authenticated.)
+ expect(status).not.toBe(401);
+ expect(body?.error?.type).not.toBe('authentication_error');
+ });
+
it('does not grant CORS access to arbitrary browser origins', async () => {
const { status, headers } = await request(app, 'GET', '/api/ping', undefined, {
Origin: 'https://attacker.example',
diff --git a/server/src/__tests__/routes/proxy-rate-limit.test.ts b/server/src/__tests__/routes/proxy-rate-limit.test.ts
new file mode 100644
index 00000000..094f5886
--- /dev/null
+++ b/server/src/__tests__/routes/proxy-rate-limit.test.ts
@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb } from '../../db/index.js';
+
+async function request(app: Express, headers: Record<string, string> = {}) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const url = `http://127.0.0.1:${addr.port}/v1/chat/completions`;
+
+ const res = await fetch(url, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...headers },
+ body: JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] }),
+ });
+
+ const text = await res.text();
+ server.close();
+
+ let json: any = null;
+ try { json = JSON.parse(text); } catch {}
+
+ return { status: res.status, body: json, headers: res.headers };
+}
+
+describe('Proxy per-IP rate limiting (#35 item #6)', () => {
+ const originalRpm = process.env.PROXY_RATE_LIMIT_RPM;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ afterAll(() => {
+ if (originalRpm === undefined) delete process.env.PROXY_RATE_LIMIT_RPM;
+ else process.env.PROXY_RATE_LIMIT_RPM = originalRpm;
+ });
+
+ it('returns 429 once the per-minute cap is exceeded', async () => {
+ // Limiter reads the env at createApp() time, so set it before building.
+ process.env.PROXY_RATE_LIMIT_RPM = '3';
+ const app = createApp();
+
+ // First 3 requests pass the limiter (they 401 on auth, but the limiter is
+ // upstream of auth, so each one still counts against the window).
+ for (let i = 0; i < 3; i++) {
+ const res = await request(app);
+ expect(res.status).not.toBe(429);
+ }
+
+ // The 4th trips the limit.
+ const limited = await request(app);
+ expect(limited.status).toBe(429);
+ expect(limited.body.error.type).toBe('rate_limit_error');
+ expect(limited.headers.get('retry-after')).toBeTruthy();
+ expect(limited.headers.get('x-ratelimit-limit')).toBe('3');
+ });
+
+ it('does not rate-limit when PROXY_RATE_LIMIT_RPM=0', async () => {
+ process.env.PROXY_RATE_LIMIT_RPM = '0';
+ const app = createApp();
+
+ for (let i = 0; i < 5; i++) {
+ const res = await request(app);
+ expect(res.status).not.toBe(429);
+ }
+ });
+});
diff --git a/server/src/app.ts b/server/src/app.ts
index a2ab60e3..da29f4b3 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -13,6 +13,7 @@ import { healthRouter } from './routes/health.js';
import { settingsRouter } from './routes/settings.js';
import { authRouter } from './routes/auth.js';
import { requireAuth } from './middleware/requireAuth.js';
+import { createProxyRateLimiter } from './middleware/rateLimit.js';
import { errorHandler } from './middleware/errorHandler.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -63,7 +64,10 @@ export function createApp() {
app.use('/api/health', requireAuth, healthRouter);
app.use('/api/settings', requireAuth, settingsRouter);
- // OpenAI-compatible proxy
+ // OpenAI-compatible proxy. Per-IP rate limiting (#35 item #6) runs first so
+ // it throttles unauthenticated brute-force / flood attempts before any
+ // routing work. Tune via PROXY_RATE_LIMIT_RPM; 0 disables it.
+ app.use('/v1', createProxyRateLimiter());
app.use('/v1', proxyRouter);
// OpenAI Responses API shim (Codex CLI requires wire_api="responses"; see #96)
app.use('/v1', responsesRouter);
diff --git a/server/src/middleware/rateLimit.ts b/server/src/middleware/rateLimit.ts
new file mode 100644
index 00000000..7090bf3a
--- /dev/null
+++ b/server/src/middleware/rateLimit.ts
@@ -0,0 +1,78 @@
+import type { Request, Response, NextFunction } from 'express';
+
+// Per-IP fixed-window rate limiter for the public /v1 proxy (#35, item #6).
+//
+// The /v1 surface authenticates with the unified API key but has no password
+// login like the dashboard does, so without this an attacker who can reach the
+// server could brute-force the key or flood upstream providers. This caps how
+// many requests a single client IP can make per minute and returns a standard
+// OpenAI-shaped 429 once the cap is exceeded.
+//
+// FreeLLMAPI is a single-user tool, so the default ceiling is generous. Tune it
+// with PROXY_RATE_LIMIT_RPM (requests per minute per IP); set it to 0 to turn
+// rate limiting off entirely.
+
+const WINDOW_MS = 60_000;
+const DEFAULT_RPM = 120;
+// Bound the IP map so a flood of distinct (e.g. spoofed) source addresses can't
+// grow it without limit; expired entries are pruned opportunistically.
+const MAX_TRACKED_IPS = 10_000;
+
+interface WindowState {
+ count: number;
+ resetAt: number;
+}
+
+function parseLimit(): number {
+ const raw = process.env.PROXY_RATE_LIMIT_RPM;
+ if (raw === undefined || raw.trim() === '') return DEFAULT_RPM;
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n < 0) return DEFAULT_RPM;
+ return Math.floor(n);
+}
+
+export function createProxyRateLimiter() {
+ const limit = parseLimit();
+ const windows = new Map<string, WindowState>();
+
+ return function proxyRateLimit(req: Request, res: Response, next: NextFunction): void {
+ if (limit === 0) {
+ next();
+ return;
+ }
+
+ const now = Date.now();
+ const ip = req.ip ?? req.socket.remoteAddress ?? 'unknown';
+
+ let state = windows.get(ip);
+ if (!state || now >= state.resetAt) {
+ state = { count: 0, resetAt: now + WINDOW_MS };
+ windows.set(ip, state);
+ }
+ state.count += 1;
+
+ if (windows.size > MAX_TRACKED_IPS) {
+ for (const [key, value] of windows) {
+ if (now >= value.resetAt) windows.delete(key);
+ }
+ }
+
+ res.setHeader('X-RateLimit-Limit', String(limit));
+ res.setHeader('X-RateLimit-Remaining', String(Math.max(0, limit - state.count)));
+ res.setHeader('X-RateLimit-Reset', String(Math.ceil(state.resetAt / 1000)));
+
+ if (state.count > limit) {
+ const retryAfter = Math.max(1, Math.ceil((state.resetAt - now) / 1000));
+ res.setHeader('Retry-After', String(retryAfter));
+ res.status(429).json({
+ error: {
+ message: `Rate limit exceeded: more than ${limit} requests per minute. Retry in ${retryAfter}s.`,
+ type: 'rate_limit_error',
+ },
+ });
+ return;
+ }
+
+ next();
+ };
+}
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 370a9ef7..f8e93488 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -33,6 +33,22 @@ export function timingSafeStringEqual(provided: string, expected: string): boole
return crypto.timingSafeEqual(compareA, b) && a.length === b.length;
}
+// Extract the unified API key from an incoming request. Accepts both the
+// OpenAI-style `Authorization: Bearer <key>` header and the Anthropic-style
+// `x-api-key` header. Clients that speak the Anthropic wire format — notably
+// Claude Code routed through CC Switch (#103) — send the key in `x-api-key`
+// rather than a bearer token, and were getting a spurious "Invalid API key"
+// 401 before this fallback existed.
+export function extractApiToken(req: Request): string | undefined {
+ const bearer = req.headers.authorization?.replace(/^Bearer\s+/i, '').trim();
+ if (bearer) return bearer;
+
+ const apiKeyHeader = req.headers['x-api-key'];
+ const xApiKey = Array.isArray(apiKeyHeader) ? apiKeyHeader[0] : apiKeyHeader;
+ const trimmed = xApiKey?.trim();
+ return trimmed || undefined;
+}
+
// Sticky sessions: track which model served each "session"
// Key: hash of first user message → model_db_id
// This prevents model switching mid-conversation which causes hallucination
@@ -233,7 +249,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
// Authenticate with the unified API key for every proxy request, including
// loopback callers. Browser pages can reach localhost, so socket locality is
// not a reliable authorization boundary.
- const token = req.headers.authorization?.replace(/^Bearer\s+/i, '');
+ const token = extractApiToken(req);
const unifiedKey = getUnifiedApiKey();
if (!token || !timingSafeStringEqual(token, unifiedKey)) {
res.status(401).json({
diff --git a/server/src/routes/responses.ts b/server/src/routes/responses.ts
index bbbed628..8c81ca56 100644
--- a/server/src/routes/responses.ts
+++ b/server/src/routes/responses.ts
@@ -15,6 +15,7 @@ import { contentToString } from '../lib/content.js';
import {
isRetryableError,
timingSafeStringEqual,
+ extractApiToken,
getStickyModel,
setStickyModel,
logRequest,
@@ -229,8 +230,8 @@ export function buildResponseObject(opts: {
responsesRouter.post('/responses', async (req: Request, res: Response) => {
const start = Date.now();
- // Same unified-key bearer auth as the proxy.
- const token = req.headers.authorization?.replace(/^Bearer\s+/i, '');
+ // Same unified-key auth as the proxy (accepts Bearer or x-api-key).
+ const token = extractApiToken(req);
const unifiedKey = getUnifiedApiKey();
if (!token || !timingSafeStringEqual(token, unifiedKey)) {
res.status(401).json({ error: { message: 'Invalid API key', type: 'authentication_error' } });