How to Set Up the FreeLLMAPI Dashboard: Installation & Configuration Guide

Install FreeLLMAPI using the one-liner script or Docker Compose, start the server on port 3001, navigate to http://localhost:3001, add your provider keys on the Keys page, and copy the unified API key to begin routing LLM requests through the React dashboard.

FreeLLMAPI is an open-source LLM gateway that unifies multiple providers behind a single OpenAI-compatible API. This guide walks you through how to set up the FreeLLMAPI dashboard from the tashfeenahmed/freellmapi repository, covering Docker deployment, local development, and initial configuration of the React-based management interface.

Architectural Overview

FreeLLMAPI consists of two tightly coupled components that share the same runtime:

• Express Server (server/src/index.ts): Handles all OpenAI-compatible endpoints (/v1/*), admin routes (/api/*), rate limiting, and response caching. It serves the React dashboard as static assets from client/dist/.

• React Dashboard (client/src/App.tsx): A single-page application providing the visual management console for keys, models, routing, and analytics. It authenticates via session tokens stored in SQLite.

• Data Layer (server/src/db/index.ts and server/src/lib/crypto.ts): SQLite database (server/data/freeapi.db) persists provider keys, model profiles, and settings. All provider keys are encrypted using the ENCRYPTION_KEY environment variable.

The dashboard runs inside the same container (or Node process) as the API server. Both are reachable via port 3001 in production. All admin routes are protected by the requireAuth middleware (server/src/middleware/requireAuth.ts), which validates the x-dashboard-token header.

Installation Methods

One-Liner Script (Recommended)

Run the official install script to automate Docker setup and environment configuration:

curl -fsSL https://freellmapi.co/install.sh | bash

This script creates ~/freellmapi/.env containing a randomly generated ENCRYPTION_KEY, pulls the Docker image, and starts the container.

Docker Compose Deployment

For manual control over the deployment, clone the repository and use Docker Compose:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# Generate a 32-byte hex encryption key

ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env

docker compose up -d

The docker-compose.yml mounts a named volume (freellmapi-data) that persists the SQLite database across container restarts. To expose the dashboard on your LAN, ensure the container binds to 0.0.0.0 (set HOST_BIND=0.0.0.0 in your .env file).

Local Development Setup

For development or debugging, run the stack directly with Node:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install

# Generate encryption key using Node's crypto module

ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env

npm run dev

This starts the API server on port 3001 and the Vite development server for the dashboard on port 5173. In development mode, the dashboard proxy API requests to the backend.

Accessing the Dashboard

Once the container or process is running, open your browser to the appropriate URL:

Environment	URL	Notes
Docker / Production	http://localhost:3001	Dashboard and API share the same port. Express serves static React assets from client/dist/.
LAN Access	http://<host-ip>:3001	Requires HOST_BIND=0.0.0.0 in your .env file.
Development	http://localhost:5173	Vite dev server hot-reloads UI changes; API calls proxy through to port 3001.

On first access, you will see a login screen. The initial admin account is created automatically on server startup. The temporary password reset code is printed in the server logs, which you can view with docker compose logs -f freellmapi. The login handler is implemented in server/src/routes/auth.ts via POST /api/auth/login.

Initial Dashboard Configuration

Add Provider API Keys

Navigate to the Keys page in the left sidebar to configure your upstream LLM providers:

1. Click Add Provider and select a platform (e.g., groq, google, openrouter).
2. Paste your provider's API key into the form.
3. Click Save.

The UI encrypts the key client-side before transmission using the encrypt function from server/src/lib/crypto.ts. The encrypted payload is stored in server/data/freeapi.db via the routes defined in server/src/routes/keys.ts. The React components for this interface reside in client/src/pages/KeysPage.tsx.

Retrieve Your Unified API Key

After adding providers, copy the unified API key displayed in the Keys page header. This token (formatted as freellmapi-xxxxxxxxxxxxxxxx) is the single credential you provide to any OpenAI-compatible client.

export OPENAI_API_KEY=freellmapi-xxxxxxxxxxxxxxxx

The key generation logic is located in server/src/services/auth.js within the generateUnifiedKey function. This token authenticates requests to /v1/chat/completions and other inference endpoints.

Configure the Fallback Chain

Go to Models → Fallback Chain to customize request routing:

• Drag and drop providers to reorder the priority chain.
• Enable or disable specific models.
• Create profiles (named fallback chains) for different use cases.

Profiles are stored in the profiles table and can be switched programmatically via PUT /v1/fallback/profile/:name without accessing the dashboard. The routing logic is implemented in server/src/services/router.ts.

Optional Settings

Tab	Configuration Options
Settings	Toggle response caching (X-FreeLLM-Cache), enable prompt compression, configure per-model quotas.
Analytics	View hourly request counts and token usage statistics.
Health	Monitor provider latency and retry/back-off status.
Logs	Browse server logs (requires valid dashboard session token).

Usage Examples

Query the API with curl

Use the unified key to make requests against the gateway:

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "auto",
        "messages": [{"role":"user","content":"Hello world"}]
      }'

Switch Routing Profiles via API

Change the active fallback chain without opening the dashboard:

curl -X POST http://localhost:3001/v1/fallback/profile/my-coding-chain \
  -H "Authorization: Bearer freellmapi-xxxxxxxxxxxxxxxx"

Enable Response Caching

Force the server to cache a specific request using the X-FreeLLM-Cache header:

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-xxxxxxxxxxxxxxxx" \
  -H "X-FreeLLM-Cache: on" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Repeat: 42"}]}'

Summary

• Install FreeLLMAPI using the one-liner script (install.sh), Docker Compose, or local Node development environment.
• Secure the installation by setting a strong ENCRYPTION_KEY in your .env file to protect provider credentials stored in SQLite.
• Access the dashboard at http://localhost:3001 (production) or http://localhost:5173 (development), logging in with credentials from the server logs.
• Configure provider keys on the Keys page (client/src/pages/KeysPage.tsx), copy the unified API key, and arrange your fallback chain in the Models section.
• Route requests through the unified endpoint (/v1/chat/completions) using standard OpenAI client libraries.

Frequently Asked Questions

What port does the FreeLLMAPI dashboard run on?

In production deployments using Docker or the one-liner script, the dashboard and API both share port 3001. During local development with npm run dev, the React dashboard runs on port 5173 via the Vite development server, while the API server remains on port 3001.

How do I generate the required ENCRYPTION_KEY?

The ENCRYPTION_KEY must be a 32-byte hexadecimal string. Generate it using OpenSSL (openssl rand -hex 32) or Node.js (node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))'). This key is used by server/src/lib/crypto.ts to encrypt provider API keys before they are stored in the SQLite database.

Where are provider API keys stored?

Provider keys are encrypted using AES-256-GCM and stored in the SQLite database at server/data/freeapi.db (persisted via the freellmapi-data Docker volume). The encryption/decryption logic resides in server/src/lib/crypto.ts, and the database schema is managed in server/src/db/index.ts.

Can I run the dashboard separately from the API server?

No. The React dashboard is designed to run as a static single-page application served by the Express server (server/src/index.ts). In production, Express mounts the built assets from client/dist/. While the Vite dev server can proxy requests during development, the dashboard requires the Express backend for all API calls and authentication via the requireAuth middleware.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}