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

> Install FreeLLM API quickly with Docker or Node.js. Our guide streamlines setup for production environments. Get started with the fastest Docker one-liner installation.

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

---

**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.

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

```

### What the Script Does

The [`docs/install.sh`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml). This setup creates a named volume for SQLite data and supports LAN exposure through environment variables.

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

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/index.ts))
- **Dashboard UI** at `http://localhost:5173` (Vite-powered React app in [`client/src/App.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.

```powershell
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

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

```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`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/install.sh)) provides the fastest deployment for production use with automatic encryption key generation
- **Docker Compose** ([`docker-compose.yml`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.