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

> Easily set up the FreeLLMAPI dashboard with our installation and configuration guide. Install via script or Docker, add keys, and start routing LLM requests.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/db/index.ts) and [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```bash
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:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts). The React components for this interface reside in [`client/src/pages/KeysPage.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.

```bash
export OPENAI_API_KEY=freellmapi-xxxxxxxxxxxxxxxx

```

The key generation logic is located in [`server/src/services/auth.js`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts), and the database schema is managed in [`server/src/db/index.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.