DEV Community

Lynkr
Lynkr

Posted on

How to Configure LibreChat with Lynkr Using a Custom OpenAI-Compatible Endpoint

#devops #ai #opensource #webdev

How to Configure LibreChat with Lynkr Using a Custom OpenAI-Compatible Endpoint

LibreChat is one of the best open-source AI chat and agent surfaces for teams that want self-hosting, MCP support, flexible model backends, and a real product surface instead of a demo UI.

Lynkr is an open-source LLM gateway built for coding assistants, agents, and MCP-heavy workflows. It gives you one OpenAI-compatible endpoint in front of multiple providers, with routing, caching, and cleaner model infrastructure behind it.

Put together, they make a clean split:

  • LibreChat handles the app layer: chat UI, agents, files, MCP, user workflows
  • Lynkr handles the gateway layer: routing, provider switching, fallback, caching, and model control

That is why this pairing works so well. LibreChat already supports custom OpenAI-compatible endpoints, and Lynkr is a strong fit for the kind of multi-provider, tool-using, agentic traffic LibreChat users actually generate.

This article is the practical follow-up to the architecture case: the goal here is to get LibreChat talking to Lynkr with a minimal working setup.

I built Lynkr, so founder disclosure applies. I’m keeping this grounded to what LibreChat and Lynkr support today.

Why Lynkr fits LibreChat especially well

There are plenty of tools that can sit between an app and a model provider, but Lynkr is a particularly strong fit for LibreChat for a few reasons:

  • OpenAI-compatible endpoint: LibreChat already has a clean seam for custom OpenAI-compatible APIs, which makes Lynkr easy to drop in underneath it
  • Built for agentic traffic: LibreChat is not just plain chat. It supports agents, MCP, tools, and more complex request patterns. Lynkr is designed for those heavier workflows, not just one-shot completions
  • Routing + caching in one place: if you want LibreChat to stay clean at the product layer while the backend evolves, Lynkr gives you a better home for that logic
  • Provider portability: you can keep LibreChat stable while moving between Ollama, OpenRouter, Bedrock, OpenAI, and others behind the gateway
  • Good fit for MCP and coding workflows: Lynkr was built around the kind of traffic these users actually generate

That means this setup is not just “put any proxy in front of LibreChat.” It is specifically about using a gateway that matches the workload.

What you need

Before starting, you need:

  • a running LibreChat instance
  • Node.js 20+ for Lynkr
  • at least one backend provider configured in Lynkr
  • one LibreChat endpoint that points to Lynkr instead of directly to a provider

Repo references:

Two details matter here:

  1. LibreChat explicitly supports custom OpenAI-compatible APIs
  2. Lynkr exposes an OpenAI-compatible /v1 endpoint

That’s the seam we’re using.

The target architecture

The setup we want looks like this:

Browser
  ↓
LibreChat
  ↓
Lynkr (OpenAI-compatible endpoint)
  ↓
OpenAI / Bedrock / OpenRouter / Ollama / Anthropic-compatible backends / others
Enter fullscreen mode Exit fullscreen mode

In other words:

  • LibreChat owns the chat UI, agents, MCP, files, and workflows
  • Lynkr owns routing, caching, and model-side control

Step 1: Install and start Lynkr

Install Lynkr globally:

npm install -g lynkr
Enter fullscreen mode Exit fullscreen mode

Now create a minimal .env for Lynkr.

Example A: local testing with Ollama 

MODEL_PROVIDER=ollama
OLLAMA_ENDPOINT=http://localhost:11434
OLLAMA_MODEL=qwen2.5-coder:latest
FALLBACK_ENABLED=false
PORT=8081
PROMPT_CACHE_ENABLED=true
SEMANTIC_CACHE_ENABLED=true
Enter fullscreen mode Exit fullscreen mode

Then start Lynkr:

lynkr start
Enter fullscreen mode Exit fullscreen mode

Example B: cloud setup with OpenRouter 

MODEL_PROVIDER=openrouter
OPENROUTER_API_KEY=your_openrouter_key
FALLBACK_ENABLED=false
PORT=8081
PROMPT_CACHE_ENABLED=true
SEMANTIC_CACHE_ENABLED=true
Enter fullscreen mode Exit fullscreen mode

Then start it:

lynkr start
Enter fullscreen mode Exit fullscreen mode

Optional direct smoke test against Lynkr

Before touching LibreChat, you can test Lynkr directly with a simple OpenAI-compatible request:

curl http://localhost:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dummy-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'
Enter fullscreen mode Exit fullscreen mode

If that succeeds, the gateway path is working before LibreChat is added on top.

Quick health check

Once Lynkr is running, verify the endpoint responds:

curl http://localhost:8081/
Enter fullscreen mode Exit fullscreen mode

You should get a JSON response showing the service is running.

At this point, Lynkr should expose an OpenAI-compatible base URL at:

http://localhost:8081/v1
Enter fullscreen mode Exit fullscreen mode

That is the URL LibreChat should talk to.

Step 2: Decide how LibreChat should see Lynkr

LibreChat supports custom endpoints and also lets users provide a custom baseURL for supported endpoint flows.

For this setup, the important part is simple:

  • LibreChat should send requests to Lynkr’s /v1 base URL
  • LibreChat should use a model name that Lynkr will accept and route
  • LibreChat should not need to know which upstream provider you finally use behind Lynkr

So the mental model is:

LibreChat config → one base URL → Lynkr
Lynkr config → actual providers, routing, fallback, cache
Enter fullscreen mode Exit fullscreen mode

That separation is the whole point.

Step 3: Add Lynkr as the LibreChat custom endpoint

The exact UI path can differ depending on how you run LibreChat and how you expose custom endpoints, but the working shape is the same.

In LibreChat, configure a custom OpenAI-compatible endpoint with:

  • Base URL: http://localhost:8081/v1
  • API key: any value Lynkr accepts for your setup, or the key your deployment expects
  • Model: a model string that Lynkr can map or forward

Minimal example values 

Endpoint Type: Custom OpenAI-compatible endpoint
Base URL: http://localhost:8081/v1
API Key: dummy-key
Model: gpt-4o-mini
Enter fullscreen mode Exit fullscreen mode

If your LibreChat instance and Lynkr instance run on different hosts, replace localhost with the actual reachable host:

http://lynkr.internal:8081/v1
Enter fullscreen mode Exit fullscreen mode

or

https://lynkr.yourdomain.com/v1
Enter fullscreen mode Exit fullscreen mode

If you are running LibreChat in Docker and Lynkr on the host machine, you may need to use a host-reachable name rather than localhost, for example:

http://host.docker.internal:8081/v1
Enter fullscreen mode Exit fullscreen mode

That’s one of the most common gotchas.

Step 4: Pick a model name strategy

This part trips people up more than it should.

LibreChat wants a model name. Lynkr also needs to know what to do with that model name.

There are two clean ways to handle this.

Option 1: pass through a real model name

Use a model name that corresponds to the backend you want Lynkr to use.

Example:

gpt-4o-mini
Enter fullscreen mode Exit fullscreen mode

or

claude-3-5-sonnet
Enter fullscreen mode Exit fullscreen mode

This is the simplest starting point if Lynkr is forwarding traffic in a straightforward way.

Option 2: use stable logical model names in LibreChat

A better long-term pattern is to let LibreChat use a stable name like:

chat-fast
Enter fullscreen mode Exit fullscreen mode

or

chat-quality
Enter fullscreen mode Exit fullscreen mode

Then map those choices in the gateway layer.

That way:

  • LibreChat users keep the same model choices
  • Lynkr can change the real backend later
  • you can move from OpenRouter to Bedrock or from cloud to local without rewriting the app-side model menu

Even if you do not formalize that on day one, this is the direction I’d recommend.

Step 5: Run a smoke test from LibreChat

Once the endpoint is configured, test a simple chat request first.

Use something cheap and easy to inspect, like:

Write a Python function that reverses a string.

If that works, test a second request that makes backend behavior easier to reason about, like:

Summarize the difference between Redis and PostgreSQL in 5 bullets.

What you’re looking for:

  • LibreChat sends successfully to Lynkr
  • Lynkr forwards successfully to the configured provider
  • the response comes back normally in LibreChat

If this works, the base integration is done.

Step 6: Add one routing policy behind Lynkr

This is where the setup becomes more useful than direct provider wiring.

A good first pattern is:

  • route lightweight general chat to a cheaper model
  • route harder reasoning or code-heavy work to a stronger model

Conceptually, the setup looks like this:

LibreChat user chooses: chat-fast
  → Lynkr routes to cheaper tier

LibreChat user chooses: chat-quality
  → Lynkr routes to stronger tier
Enter fullscreen mode Exit fullscreen mode

Even without exposing every provider in LibreChat, you still get flexibility behind the gateway.

That’s cleaner than giving end users six raw vendor choices and expecting them to know when each one is appropriate.

Step 7: Add fallback once the happy path works

Do not start with fallback complexity on the first try. Get one provider working first.

After that, the next useful improvement is fallback.

Example pattern:

  • primary backend: OpenRouter
  • fallback backend: Bedrock

or

  • primary backend: local Ollama model
  • fallback backend: stronger cloud model

This gives you a much better operational story than “LibreChat is hardwired to one provider and breaks when that provider has a bad day.”

That’s one of the clearest reasons to keep failover logic below the app layer.

A concrete request flow example

Here’s what this looks like in practice.

Without Lynkr 

LibreChat → OpenAI directly
Enter fullscreen mode Exit fullscreen mode

If you want to change providers, add fallback, or introduce routing, those concerns start leaking into the app layer.

With Lynkr 

LibreChat → Lynkr → OpenRouter
                    ↘ Bedrock fallback
Enter fullscreen mode Exit fullscreen mode

LibreChat stays pointed at one endpoint.

That means:

  • less config churn in the app
  • easier backend changes
  • cleaner rollout of new models
  • a better place to add caching and routing

Common gotchas

Here are the ones most likely to waste your time.

1. Wrong base URL

If you point LibreChat at:

http://localhost:8081
Enter fullscreen mode Exit fullscreen mode

instead of:

http://localhost:8081/v1
Enter fullscreen mode Exit fullscreen mode

you may hit endpoint mismatches depending on how the OpenAI-compatible client path is built.

Use the /v1 base URL.

2. Docker networking confusion

If LibreChat runs in Docker, localhost usually means the container itself, not your host machine.

Use a network-reachable host such as:

http://host.docker.internal:8081/v1
Enter fullscreen mode Exit fullscreen mode

or a proper internal hostname.

3. Model name mismatch

If LibreChat sends a model string Lynkr does not recognize or route correctly, requests will fail even though the endpoint is reachable.

When debugging, simplify:

  • pick one known model string
  • use one provider
  • get one request working
  • only then layer routing or aliases on top

4. Starting with too much complexity

Don’t try to validate all of these at once:

  • custom endpoint
  • multiple providers
  • fallback
  • caching
  • routing
  • agents
  • MCP tools

Get the base chat completion path working first.

Then expand.

5. Treating LibreChat like the provider control plane

LibreChat is excellent at the user/product layer.

But if you keep using the app layer to own provider switching, cost control, and failover, you lose the main architectural benefit of using a gateway underneath it.

Keep the responsibilities split.

Why this setup is worth it

Even the minimal version gives you a better foundation than direct provider wiring.

You get:

  • one stable endpoint in LibreChat
  • provider portability behind the scenes
  • a better place for routing
  • a better place for fallback
  • a better place for caching
  • a cleaner path from simple chat UI to broader agent infrastructure

And as your setup grows, that separation only gets more valuable.

Minimal checklist

If you just want the shortest possible version, this is it:

  1. Install Lynkr
  2. Start Lynkr on port 8081
  3. Verify http://localhost:8081/v1 is reachable
  4. In LibreChat, add a custom OpenAI-compatible endpoint
  5. Set the base URL to http://localhost:8081/v1
  6. Use a model string Lynkr can route
  7. Run one smoke-test prompt
  8. Only after that, add routing and fallback

Final take

LibreChat already gives you the hard part: a good open-source surface for chat, agents, MCP, and self-hosting.

Lynkr gives you the missing infrastructure layer under it.

That combination is stronger than pushing all model concerns into the app itself.

If you’re building a self-hosted AI stack that needs to survive provider churn, model changes, and growing workflow complexity, this is the shape I’d use.

If this article was useful, star the repos and let me know if you want the next one to go deeper on:

  • LibreChat + Lynkr with Docker Compose
  • model aliases and routing strategy
  • using LibreChat agents on top of a Lynkr-backed stack

Top comments (0)