Proposal: Reverse-Connected External Agent Runtime

[r05323028]

Problem

LibreChat can connect to external model and agent endpoints, but this assumes the LibreChat server can directly reach those endpoints.

That becomes difficult when the agent runs on a developer laptop or inside a private network.

For example:

Kubernetes / Cloud
┌─────────────────────┐
│ LibreChat           │
└──────────┬──────────┘
           │
           │ cannot directly reach
           X
           │
Developer machine
┌─────────────────────┐
│ Pi / Codex /        │
│ Claude Code /       │
│ custom local agent  │
└─────────────────────┘

The local machine can usually reach LibreChat, but LibreChat cannot necessarily reach the local machine because of NAT, CGNAT, firewall rules, or network topology.

Today, one workaround is to expose the local agent through an OpenAI-compatible API and configure it as a custom endpoint.

That works, but still requires solving the networking problem separately.

---

Proposal

Add support for a reverse-connected agent runtime.

A lightweight connector runs alongside the local agent and establishes an outbound WebSocket connection to LibreChat.

Developer machine                     LibreChat

┌────────────────────┐
│ Local Agent        │
│ Pi / Codex / etc.  │
└─────────┬──────────┘
          │ localhost
          ▼
┌────────────────────┐
│ Agent Connector    │
└─────────┬──────────┘
          │
          │ outbound WSS
          ▼
                               ┌────────────────────┐
                               │ LibreChat Server   │
                               │ Runtime Registry   │
                               │ Agent Dispatcher   │
                               └────────────────────┘

LibreChat would invoke the runtime through the already-established connection.

The server would never need to initiate a connection back to the user's machine.

---

Example Flow

The user starts a connector:

librechat-agent connect \
  --server https://chat.example.com \
  --name sean-macbook

The connector registers available runtimes:

{
  "type": "runtime.register",
  "runtime": {
    "name": "sean-macbook",
    "agents": [
      {
        "id": "pi",
        "name": "Pi Coding Agent",
        "protocol": "openai-compatible"
      }
    ]
  }
}

LibreChat can then send an invocation through WebSocket:

{
  "id": "req_123",
  "type": "agent.invoke",
  "agent": "pi",
  "payload": {
    "messages": [],
    "stream": true
  }
}

The connector calls the local runtime:

LibreChat
    ↓
WebSocket
    ↓
Agent Connector
    ↓
http://127.0.0.1:8000/v1
    ↓
Local Agent

Streaming events travel back through the same WebSocket connection.

---

Adapter Model

I don't think LibreChat needs native support for every coding agent.

The connector could use adapters:

Agent Connector
   ├─ OpenAI-compatible
   ├─ A2A
   ├─ Pi
   ├─ Codex
   └─ Claude Code

For an MVP, supporting only an OpenAI-compatible local endpoint may already be enough:

agents:
  - id: pi
    type: openai-compatible
    baseURL: http://127.0.0.1:8000/v1

This would immediately support many existing tools without adding agent-specific logic to LibreChat core.

---

Why Not Just Use Tailscale / VPN / Public URLs?

Those are valid solutions, but they require users to configure networking separately.

A reverse-connected runtime would provide:

• no inbound port
• no public URL
• no Kubernetes-to-laptop routing
• NAT / CGNAT compatibility
• simpler onboarding
• runtime online/offline presence in LibreChat
• local credentials remain local
• local MCP servers and tools remain private

This is especially useful for coding agents that need access to local repositories, terminals, credentials, or MCP servers.

---

Security

The connector should not act as a generic reverse proxy.

Only explicitly registered runtimes should be callable.

For example:

agents:
  - id: pi
    endpoint: http://127.0.0.1:8000/v1

LibreChat should not be able to request arbitrary URLs on the user's machine.

Possible protections:

• device registration
• short-lived tokens
• user/workspace ownership
• explicit agent allow-list
• runtime permissions
• heartbeat and session IDs
• audit logging
• request size limits

---

Relationship to External Agents / A2A

I see this mainly as a transport option rather than a new agent abstraction.

External Agent

├─ HTTP
├─ A2A
└─ Reverse WebSocket

When the server can reach the agent:

LibreChat → HTTP/A2A → Agent

When the agent is private or local:

Agent Connector → WSS → LibreChat

The higher-level agent model could remain the same.

---

Possible MVP

Connector

login / device registration
outbound WebSocket
heartbeat
runtime registration
OpenAI-compatible adapter

LibreChat Server

runtime registry
WebSocket session management
agent invocation RPC
stream forwarding

UI

Something simple like:

Pi Coding Agent
● Online
Sean's MacBook

Codex
○ Offline
Sean's MacBook

---

Use Cases

This could allow LibreChat to act as a frontend for:

• Pi
• Codex CLI
• Claude Code
• local coding agents
• GPU workstation agents
• internal enterprise agents
• local MCP servers
• agents with access to local repositories
• OpenAI-compatible agent gateways

without exposing those machines to inbound traffic.

---

Would a reverse-connected runtime like this fit with LibreChat's existing External Agent / A2A direction?

I think it could be especially useful for local coding agents, where the execution environment naturally lives on the developer's machine rather than next to the LibreChat server.