How to Install FreeLLM API: Complete Setup Guide for Docker and Node.js

You can install FreeLLM API using a Docker one-liner, Docker Compose, or a local Node.js environment, with the Docker one-liner being the fastest method for production deployment.

FreeLLM API is an open-source unified interface for multiple LLM providers, distributed under the tashfeenahmed/freellmapi repository. Whether you need a quick production deployment or a local development environment, this guide covers the three supported installation methods with exact commands from the source code.

Prerequisites

Before installing FreeLLM API, ensure you have:

• Docker Engine 20.10+ for containerized deployments (recommended)
• Git and Node.js 20+ for local development
• OpenSSL or Node.js crypto module for generating the required ENCRYPTION_KEY

Method 1: Docker One-Liner (Fastest)

The quickest way to install FreeLLM API uses the official install script hosted at freellmapi.co. This method automatically handles environment setup, encryption key generation, and container deployment.

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

What the Script Does

The docs/install.sh script performs four critical operations:

1. Creates a persistent data directory at ~/freellmapi (or $FREELLMAPI_DIR if set)
2. Generates a random 256-bit AES encryption key for credential storage
3. Writes ENCRYPTION_KEY and PORT=3001 to a .env file in the data directory
4. Pulls ghcr.io/tashfeenahmed/freellmapi:latest and starts the container

The API becomes available immediately at http://localhost:3001/v1.

Method 2: Docker Compose (Production-Ready)

For persistent storage and easier upgrades, use the Docker Compose configuration defined in docker-compose.yml. This setup creates a named volume for SQLite data and supports LAN exposure through environment variables.

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

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

docker compose up -d

Persistent Data Configuration

This method differs from the one-liner in three key ways:

• SQLite storage persists in a Docker volume named freellmapi-data, surviving container restarts
• Source code availability allows you to modify docker-compose.yml for custom networking
• LAN exposure requires setting HOST_BIND=0.0.0.0 before starting the services

The Express proxy and React dashboard both serve on port 3001 as defined in the Compose file.

Method 3: Local Node.js Development

For contributing to the codebase or running custom modifications, install FreeLLM API directly from source using npm.

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

cp .env.example .env
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

Development Server Setup

Running locally starts two distinct services:

• API server at http://localhost:3001 (Express entry point in server/src/index.ts)
• Dashboard UI at http://localhost:5173 (Vite-powered React app in client/src/App.tsx)

The local method requires Node.js 20 or higher and uses the .env.example template for configuration.

Windows Installation (PowerShell)

Windows users can run the PowerShell equivalent of the install script. The docs/install.ps1 script mirrors the Bash version's functionality, creating the data directory, generating encryption keys, and managing the container lifecycle.

Invoke-Expression (Invoke-WebRequest -Uri https://freellmapi.co/install.ps1 -UseBasicParsing).Content

Verify Your Installation

Test your FreeLLM API installation using the OpenAI-compatible endpoint. The API requires a bearer token formatted as freellmapi-your-unified-key.

Using curl

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

Using Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key"
)

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarise the plot of Inception."}]
)

print(resp.choices[0].message.content)

Summary

• Docker one-liner (docs/install.sh) provides the fastest deployment for production use with automatic encryption key generation
• Docker Compose (docker-compose.yml) offers persistent SQLite storage and easier configuration management through environment variables
• Local Node.js setup requires cloning the repository, running npm install, and configuring the .env file from the provided example
• Windows PowerShell users have dedicated support through docs/install.ps1
• All methods expose the API at http://localhost:3001/v1 with OpenAI-compatible endpoints

Frequently Asked Questions

What is the minimum Node.js version required for local development?

FreeLLM API requires Node.js 20 or higher when running outside Docker. The package.json and development scripts in the repository are tested against Node 20+, and using earlier versions may result in dependency conflicts with the Express proxy server.

Where does FreeLLM API store encrypted credentials?

In Docker deployments, credentials are stored in a SQLite database within a Docker volume named freellmapi-data. The encryption key itself resides in the .env file as ENCRYPTION_KEY, which the docs/install.sh script generates as a 256-bit random hex string using OpenSSL.

Can I change the default port from 3001?

Yes. While the default PORT=3001 is set in the environment configuration, you can modify this value in the .env file before starting the service. When using Docker Compose, you must also update the port mapping in docker-compose.yml to match your custom port.

Is the Windows PowerShell installer different from the Bash version?

The PowerShell installer (docs/install.ps1) functions identically to the Bash script, creating the same directory structure (~/freellmapi), generating the same 256-bit encryption key format, and pulling the same ghcr.io/tashfeenahmed/freellmapi:latest container image. The only difference is the PowerShell syntax for environment variable handling.

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