How to Set Up FreeLLMAPI for Local Development Without Docker

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:

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:

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:

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 module loads these variables at runtime, supplying defaults where appropriate:

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 will fail to initialize the database layer.

5. Start the Development Server

Launch the combined development environment with a single command:

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 (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 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:

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:

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.
• 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 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—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.

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