# How to Set Up FreeLLMAPI for Local Development Without Docker

> Set up FreeLLMAPI for local development without Docker. Clone the repo, install dependencies, generate a key, create a .env file, and run npm run dev for Express API and React dashboard.

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

---

**To set up FreeLLMAPI for local development without Docker, clone the repository, install Node 20+ dependencies, generate an `ENCRYPTION_KEY`, create a `.env` file, and run `npm run dev` to start the Express API and React dashboard simultaneously.**

FreeLLMAPI is a Node.js Express server that hosts an OpenAI-compatible API and a React-based management dashboard. Running it locally from the source tree—rather than using a container—allows you to edit TypeScript files and see changes instantly via Vite’s hot-reload. This guide covers the exact workflow for configuring the `tashfeenahmed/freellmapi` repository for native development on your machine.

## Prerequisites

Before starting, ensure your environment meets the following requirements:

- **Node.js 20 or higher** (required by the workspace dependencies)
- **npm** (bundled with Node.js)
- **Git** for cloning the repository

The project uses an embedded SQLite database located at `server/data/freellmapi.db`, so no external database setup is necessary.

## Step-by-Step Installation Guide

### 1. Clone the Repository

Start by cloning the source code from GitHub:

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

```

### 2. Install Dependencies

Install all required packages using npm. The installation includes both the server-side Express dependencies and the client-side React tooling:

```bash
npm install

```

### 3. Generate an Encryption Key

FreeLLMAPI encrypts provider API keys stored in the SQLite database. You must generate a 32-byte hexadecimal encryption key before the server can start:

```bash
ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
echo "Generated key: $ENCRYPTION_KEY"

```

Store this value securely; losing it means losing access to encrypted provider credentials.

### 4. Create the Environment File

Create a `.env` file in the project root. The [`server/src/lib/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/config.ts) module loads these variables at runtime, supplying defaults where appropriate:

```dotenv
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
PORT=3001

# Optional: bind to all interfaces for LAN access

HOST_BIND=0.0.0.0

# Optional: disable CSP upgrade for plain HTTP testing

CSP_UPGRADE_INSECURE_REQUESTS=false

```

The `ENCRYPTION_KEY` variable is mandatory; without it, the `createApp` function in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) will fail to initialize the database layer.

### 5. Start the Development Server

Launch the combined development environment with a single command:

```bash
npm run dev

```

This script concurrently starts the Express API server and the Vite development server, proxying API requests from the React UI to the backend.

## Understanding the Local Development Architecture

When you run `npm run dev`, the system executes a specific boot sequence defined in the source code:

- **`createApp()` in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts)** (lines 46-98) orchestrates startup by calling `loadConfig()` to ingest your `.env` file, then wires up security middleware (Helmet, CORS, rate limiters) before mounting route handlers.
- **Database initialization** occurs immediately after configuration loading, connecting to `server/data/freellmapi.db` using the `ENCRYPTION_KEY` for transparent encryption of sensitive fields.
- **Vite proxy configuration** in [`client/vite.config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/vite.config.ts) forwards frontend API calls to the Express instance running on your configured `PORT`, enabling seamless frontend development without cross-origin issues.

This architecture matches the Docker deployment exactly, but exposes the TypeScript source for direct modification and debugging.

## LAN Development and Advanced Configuration

### Testing Across Your Network

To access the dashboard from another device on your local network, use the LAN-specific dev script:

```bash
npm run dev:lan

```

This binds the Vite server to `0.0.0.0`, making the UI accessible at `http://<your-ip>:5173` while keeping the API on port `3001`.

### Handling HTTP vs HTTPS

If you access the local instance via plain HTTP instead of HTTPS, set `CSP_UPGRADE_INSECURE_REQUESTS=false` in your `.env` file. This prevents the Content Security Policy middleware from upgrading requests to HTTPS, which would otherwise block local development resources.

## Testing the Setup

Verify the API is responding correctly with a simple `curl` request to the models endpoint:

```bash
curl -X GET http://localhost:3001/v1/models \
  -H "Authorization: Bearer <your-unified-api-key>"

```

A successful response confirms that the Express server, database layer, and routing logic are functioning correctly.

## Summary

- **Clone** the `tashfeenahmed/freellmapi` repository and run `npm install` with Node 20+.
- **Generate** a 32-byte `ENCRYPTION_KEY` for SQLite database encryption using Node’s crypto module.
- **Configure** your `.env` file with the encryption key and optional networking variables as parsed by [`server/src/lib/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/config.ts).
- **Launch** the stack with `npm run dev` to start both the Express API and React dashboard via Vite.
- **Access** the UI at `http://localhost:5173` and the API at `http://localhost:3001` by default.

## Frequently Asked Questions

### What Node.js version is required for FreeLLMAPI?

FreeLLMAPI requires **Node.js 20 or higher**. The [`package.json`](https://github.com/tashfeenahmed/freellmapi/blob/main/package.json) specifies this requirement to ensure compatibility with the modern syntax and APIs used in the Express server and React client.

### Why is the ENCRYPTION_KEY mandatory for local development?

The `ENCRYPTION_KEY` is required because FreeLLMAPI uses **AES-256-GCM encryption** to protect provider API keys stored in the local SQLite database at `server/data/freellmapi.db`. As implemented in the configuration loader, the server refuses to start without this key to prevent storing credentials in plaintext.

### How does the React dashboard communicate with the API during development?

During development, the Vite dev server—configured in [`client/vite.config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/vite.config.ts)—proxies API requests to the Express backend running on the port defined by your `PORT` environment variable (default 3001). This eliminates CORS issues and mimics the production deployment where the Express server statically serves the built UI from `/client/dist`.

### Can I run the API and dashboard on separate ports without Docker?

Yes. The Express API listens on the `PORT` you define (default 3001), while the React development server runs separately on port 5173. The `npm run dev` command orchestrates both processes, but you could theoretically run `npm run dev:server` and `npm run dev:client` in separate terminals if you need to restart them independently during debugging.