WebFV
Local API gateways / Field guide

Set up FreeLLMAPI and preserve your local data

Separate server health from provider readiness, and keep the database and encryption key together.

By WebFV Editorial · Checked October 23, 2026 · Source 2359d30bc2d7 · Node 24.5.0 API test

What the evidence coversSource API startup, health checks and same-state restart tested. Docker, dashboard setup, provider inference and backup restoration were not tested.

Start with the official self-hosted project

FreeLLMAPI runs a local API gateway and dashboard. You add provider credentials to the gateway, then give your client its separate unified API key. Installing it does not create provider accounts, grant credits or remove their quotas.

This guide covers a first local installation and the state you must preserve when restarting or upgrading. The repository and installation guide were checked on October 23, 2026, at source commit 2359d30bc2d7. For choosing between gateways, the separate FreeLLMAPI and 9Router comparison covers routing and migration decisions.

Choose Docker or a source installation

Docker Compose runs the API and dashboard together on port 3001, with SQLite in a named volume. The source workflow uses Node and npm; its development dashboard runs on 5173 and proxies requests to the API on 3001. Do not point an API client at the development dashboard port.

The README says Node 20+, while the checked package manifest is more precise: Node >=20.18.0 and <25, npm >=10. Check node --version and npm --version before installing source dependencies. A newer major version is not automatically supported.

For Docker, first confirm the engine is running:

docker version
docker compose version

A Docker executable on PATH is insufficient if it cannot connect to the daemon. That was the case on our test machine; we tested the source API instead. We did not start Docker Desktop or validate a container deployment.

Create the encryption key once

In a new folder, clone the official repository. Inspect its Compose file before starting it:

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

The following Bash commands create .env only when it does not already exist. They require OpenSSL and protect the new file with owner-only permissions:

if [ ! -e .env ]; then
  (umask 077
   printf 'ENCRYPTION_KEY=%s\nPORT=3001\n' "$(openssl rand -hex 32)" > .env)
fi

Keep a secure backup of that file. The 64-character hexadecimal key protects stored credentials. Generating a replacement during an update does not rotate existing encrypted data; it can make those credentials unreadable. The official installation guide has a separate, server-stopped re-encryption procedure for deliberate key rotation.

The default Compose service publishes only on 127.0.0.1. Keep that default for this local check. The optional automatic updater has additional permissions and is not required for installation.

Start the selected workflow

For Docker Compose:

docker compose up -d
docker compose ps
docker compose logs --tail=50 freellmapi

Open http://localhost:3001. The server dashboard has a first-account setup flow; the desktop application's automatic local sign-in is a different workflow. Follow the current setup screen. Do not paste passwords, setup codes or provider keys into a public issue.

For a source development installation, in the same checkout with .env preserved:

npm install
npm run dev

Open http://localhost:5173 for the development dashboard. The documented non-development build is npm run build, followed by node server/dist/index.js; that serves the built dashboard and API together. Our narrower test built the server workspace only and did not validate the dashboard UI.

If a native dependency reports a Node module version mismatch, compare the runtime used for installation with the runtime used to start the server. Rebuild dependencies under the intended supported Node version. We encountered that mismatch in better-sqlite3; it is a dependency/runtime problem, not a provider-key failure.

Check the process before testing a model

Run these against the API port. They need no provider credentials:

curl --noproxy '*' -i http://localhost:3001/api/ping
curl --noproxy '*' -i http://localhost:3001/livez
curl --noproxy '*' -i http://localhost:3001/readyz

The probes answer different questions:

Check What it establishes
/api/ping The HTTP application answers
/livez The database responds and the encryption key is initialized
/readyz The gateway sees a configured, eligible upstream state

In our isolated macOS test with Node 24.5.0, ping and liveness both returned HTTP 200. Readiness returned HTTP 503 because no upstream was configured. The protected /v1/models endpoint returned HTTP 401 without a key. After stopping and restarting against the same database and encryption key, all four checks returned the same statuses. This was a source API test with catalog synchronization disabled, no provider credentials and no model requests.

Readiness is still not a completed model response. A newly added, unprobed key can count as ready. After adding a permitted provider key on Keys, copy the gateway's unified key for your client and inspect /v1/models with that key. Select an available model, send one small request, then inspect the response and provider usage together. That last request can consume the provider's allowance or balance; no funded inference request was made for this guide.

Restart and back up the same state

For Compose, keep both the original .env and the freellmapi-data volume. docker compose down stops the stack while retaining its named volume; adding -v deletes the volume and is not an ordinary restart step. A database copied without the encryption key is not a complete recovery plan.

For a source installation, the default database is server/data/freeapi.db; an explicit FREEAPI_DB_PATH changes it. Stop the server cleanly before making a simple filesystem copy. Preserve its state and original encryption key together in a protected backup. Do not copy a live SQLite database while ignoring its write-ahead log.

The project also documents encrypted backup targets and an optional separate backup-envelope key. That envelope key and the key encrypting credentials have different jobs. Restoring a backup must preserve the required original secrets; replacing either with a new random value is not recovery. Our restart check reused the same database and key. It did not restore a populated provider database or test encrypted remote backups.

Locate the failed layer

If the browser cannot connect, check the process, API port and local binding first. A remote device cannot reach a service published only on loopback. If the dashboard loads but a model fails, inspect the configured provider, its key status, model availability and quota before reinstalling the gateway.

A container has its own loopback address. A host proxy configured as 127.0.0.1 is not automatically reachable from inside Docker; follow the official networking instructions for your environment. Do not make the whole gateway public merely to repair an outbound connection.

Finally, “free” describes provider allowances under their own terms. Catalog freshness, optional paid services and inference credits are separate. The upstream README recommends personal experimentation and advises arranging suitable paid API access before shipping a production product. A healthy local process cannot establish those service commitments.