# Where to Find the Configuration File for FreeLLM API

> Locate the FreeLLM API configuration file easily. Learn about the FREEAPI_CONFIG_PATH environment variable and its default JSON file path for quick access and customization.

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

---

**The FreeLLM API configuration file is a JSON file whose location is specified by the `FREEAPI_CONFIG_PATH` environment variable, defaulting to [`/app/server/data/freellmapi.config.json`](https://github.com/tashfeenahmed/freellmapi/blob/main//app/server/data/freellmapi.config.json) when the variable is not set.**

The FreeLLM API relies on a declarative JSON configuration to define models, providers, and fallback priorities at runtime. Unlike hardcoded settings, this approach allows you to adjust your LLM infrastructure without rebuilding the application. Understanding where to place this file and how the server discovers it is essential for both local development and production deployments.

## How FreeLLM API Locates Its Configuration File

The server determines the configuration file location through the **`FREEAPI_CONFIG_PATH`** environment variable. According to the source code in [`server/src/services/declarative-config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/declarative-config.ts), the application reads this variable at startup using `process.env.FREEAPI_CONFIG_PATH?.trim()` to resolve the absolute path to your JSON configuration.

When this environment variable is set, the server loads the specified file immediately after completing database migrations. The loader returns an object containing both the source path and parsed configuration: `{ source: configPath, value: JSON.parse(...) }`. This design ensures that your configuration is applied idempotently after the database schema is ready.

## Default Configuration File Location

If you do not set `FREEAPI_CONFIG_PATH`, the service falls back to a conventional default location. The commented entry in `.env.example` (line 46) illustrates this default path:

```text

# FREEAPI_CONFIG_PATH=/app/server/data/freellmapi.config.json

```

By convention, the file is named **[`freellmapi.config.json`](https://github.com/tashfeenahmed/freellmapi/blob/main/freellmapi.config.json)** and resides in the server’s data directory. While you can use any filename and location, placing the configuration under `/app/server/data/` aligns with the project’s documented structure and Docker volume mounts.

## Configuration File Format and Structure

The configuration file must contain valid JSON defining your models, API keys, and fallback behavior. Here is a minimal example that configures a single OpenAI model with a fallback priority:

```json
{
  "models": [
    {
      "id": "gpt-4",
      "provider": "openai",
      "key_id": "my-openai-key"
    }
  ],
  "fallbacks": [
    {
      "model_id": "gpt-4",
      "priority": 1,
      "enabled": true
    }
  ]
}

```

The server validates this structure during startup and merges it with any persisted database state, allowing you to update runtime behavior without service interruption.

## Setting Up the Configuration File in Different Environments

### Local Development

For local development, export the environment variable in your shell or add it to a `.env` file:

```bash

# .env

FREEAPI_CONFIG_PATH=/path/to/your/freellmapi.config.json

```

### Docker Deployment

When running in Docker, mount your configuration as a volume and set the environment variable. The [`docker/README.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker/README.md) documents that `FREEAPI_CONFIG_PATH` must be passed to the container at runtime:

```bash
docker run -e FREEAPI_CONFIG_PATH=/app/server/data/freellmapi.config.json -v /host/path/config.json:/app/server/data/freellmapi.config.json tashfeenahmed/freellmapi

```

## How the Server Loads the Configuration

The loading logic in [`server/src/services/declarative-config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/declarative-config.ts) (line 116) handles the configuration bootstrap sequence:

1. **Variable Check**: The service checks `process.env.FREEAPI_CONFIG_PATH` for a non-empty value.
2. **File Resolution**: It trims whitespace and resolves the absolute path.
3. **JSON Parsing**: The file contents are read and parsed via `JSON.parse()`.
4. ** state Merge**: The configuration is merged with the database state after migrations complete.

This process ensures that your declarative configuration always takes precedence over default values while maintaining compatibility with existing database records.

## Summary

- The **configuration file location** is controlled by the `FREEAPI_CONFIG_PATH` environment variable.
- If unset, the default path is [`/app/server/data/freellmapi.config.json`](https://github.com/tashfeenahmed/freellmapi/blob/main//app/server/data/freellmapi.config.json) as documented in `.env.example`.
- The file must contain **valid JSON** defining models, providers, and fallback strategies.
- The server loads and validates this configuration at startup, applying it after database migrations in [`declarative-config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/declarative-config.ts).
- You can use any filename or path, provided the environment variable points to the correct location.

## Frequently Asked Questions

### What format does the FreeLLM API configuration file use?

The configuration file uses **JSON format**. It must contain a valid JSON object with properties such as `models` and `fallbacks` that define your LLM providers and routing logic. The server parses this file using `JSON.parse()` during the startup sequence.

### Can I use a custom filename for the configuration file?

**Yes.** While the default convention is [`freellmapi.config.json`](https://github.com/tashfeenahmed/freellmapi/blob/main/freellmapi.config.json), you can name the file anything you like. Simply set the `FREEAPI_CONFIG_PATH` environment variable to the absolute path of your chosen file, including the custom filename, and the server will load it accordingly.

### When does FreeLLM API read the configuration file?

The server reads the configuration file **once during startup**, specifically after database migrations have completed. As implemented in [`server/src/services/declarative-config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/declarative-config.ts), the loader applies the configuration idempotently at boot time, ensuring your JSON settings are merged with the current database state before accepting requests.

### What happens if the FREEAPI_CONFIG_PATH variable is not set?

If the environment variable is undefined, the service falls back to the default path documented in `.env.example`: [`/app/server/data/freellmapi.config.json`](https://github.com/tashfeenahmed/freellmapi/blob/main//app/server/data/freellmapi.config.json). However, if the file does not exist at that location and no variable is set, the server may fail to load your custom configuration, potentially falling back to internal defaults or raising an error depending on your version.