Where to Find the Configuration File for FreeLLM API

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

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

By convention, the file is named 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:

{
  "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:

# .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 documents that FREEAPI_CONFIG_PATH must be passed to the container at runtime:

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 (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 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.
• 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, 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, 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. 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.

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