LibreChat

LibreChat is a self-hosted, privacy-focused AI conversation platform that integrates multiple major AI providers into a single interface.

Key capabilities include:

• AI Model Support: Connect to Anthropic, OpenAI, Azure, Google (Vertex AI), AWS Bedrock, and custom endpoints compatible with the OpenAI specification. It also supports local/remote providers like Ollama, Groq, Mistral, and more.
• Agents & Tools: Build no-code custom assistants, use an Agent Market, and leverage the Model Context Protocol (MCP) for tool calling. Features include Skills (reusable instruction sets) and Subagents (isolated task delegation).
• Code Execution: A secure sandbox for running Python, Node.js, Go, C/C++, Java, PHP, Rust, and Fortran via the Code Interpreter API.
• Advanced UI: Supports Generative UI with Code Artifacts (React, HTML, Mermaid), dynamic Reasoning UI for models like DeepSeek-R1, and Resumable Streams for connection reliability.
• Multimodal & Media: Image generation (DALL-E, Stable Diffusion, Flux), image analysis, and voice/audio interaction (STT/TTS) via OpenAI, Azure, and Elevenlabs.
• Enterprise & Management: Multi-user authentication (OAuth2, LDAP, Email), conversation search, message/dialogue forking, and import/export capabilities (Markdown, JSON, etc.).

Tool Intent & Outcome Labels is a capability that allows an AI model to declare its purpose for a specific tool call. Instead of showing generic, mechanical labels (e.g., Ran search_code in github), the UI displays a natural-language statement of what the model is attempting to do.

Key Concepts

• Intent: A live, per-call string provided by the model as the first argument of a tool call. It streams into the UI while the tool is running (e.g., "Searching for OAuth handling").
• Outcome: A settled, per-call string that replaces the intent once the tool call completes (e.g., "Searched for OAuth handling"). This is authored by the tool/model and acts as an in-place edit of the intent.
• Relationship to Activity Labels:
  • Intents are live, per-call, and authored by the calling model via tool arguments.
  • Activity Labels are settled, per-block, and authored by a fast-model to provide a narrative summary of a group of tool calls.

The Helm chart can optionally deploy a Langfuse fanout gateway with an internal OpenTelemetry Collector sidecar. This handles media fanout and proxies traces to both a central Langfuse project and tenant-specific projects.

Key Configuration Options:

• Enable/Disable: Controlled via the chart (disabled by default). When enabled, it sets LANGFUSE_FANOUT_ENABLED and LANGFUSE_FANOUT_COLLECTOR_URL.
• Tenant Export: Set librechat.configEnv.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED=true to keep central traces flowing while disabling tenant-specific trace and score export.
• Redis: The gateway uses Redis to store one-time media upload plans. Use langfuseFanout.redis.uri for an external service, or enable the bundled Redis via redis.enabled=true.
• Scaling: Scale the gateway using langfuseFanout.replicaCount. Note that the chart does not create a Horizontal Pod Autoscaler (HPA) for the fanout component.
• Metrics: The gateway exposes Prometheus metrics at /metrics. To secure this, use langfuseFanout.metrics.secret.name and .key to provide a bearer token.

The chat_search_db uses a least-privilege model with three specific security roles created via search/init/chat-search-roles.sh. All roles have search_path set to chat_search, public to allow unqualified type and table references.

Roles

1. chat_search_owner: The migration owner. It owns the chat_search schema. Every table it creates automatically grants full DML and sequence usage to chat_search_writer via default privileges.
2. chat_search_writer: The projection writer. Used by the projector, outbox consumer, and sweep processes.
3. chat_search_reader: The request reader. This role is subject to Row Level Security (RLS). It has no default grants on new tables (like outbox or watermark), enforcing a deny-by-default policy.

Security Implementation Details

• Extensions: vector (for embeddings) and pg_trgm (for trigram search) are installed into the chat_search schema.
• RLS: While the init script sets up the roles, Track 4 migrations are responsible for enabling RLS on specific tables (e.g., chat_search.documents) and creating the necessary policies (e.g., tenant_id/user_id predicates).
• Default Privileges: ALTER DEFAULT PRIVILEGES is used so that chat_search_owner's new tables are automatically accessible to the writer, but the reader remains restricted until explicit GRANT SELECT commands are run during migration.

The MCP (Model Context Protocol) authority proof is an additive, default-off substrate designed to ensure that tool calls, connections, and publications are backed by a verified, immutable configuration state.

Core Workflow

1. Resolver Initialization: A caller creates one MCPAuthorityProofResolver per immutable boot configuration.
2. Proof Resolution: The resolver resolves selected servers into an "authority proof" envelope.
3. Proof Carrying: This envelope is carried alongside the parsed configuration and schemas.
4. Fence Verification: Integration "fences" (helpers) accept only the resolution envelope issued by the resolver. They verify the artifact revision and pass the exact envelope to the publication, binding, or execution callback.

Key Constraints

• Immutability: The resolver never freezes or mutates caller-owned config or schema objects.
• No Detached Proofs: Fences do not accept detached proofs with arbitrary artifacts; they must use the envelope issued by the resolver.
• No Side Effects: A current-authority assertion does not reload YAML, call the MCP registry, scan Redis, initialize servers, or perform network I/O. It operates within a fresh MongoDB transaction with majority read/write concerns.

Tool Intent and Activity Labels are complementary systems that operate on different layers:

Key Integration Rules:

• Do not couple transports: Intents ride tool_call.args, while activity labels use SSE events (on_activity_label).
• Enhancement: Activity labels benefit from intents. Instead of echoing raw JSON, an activity label can use the intent to read: "Searching for OAuth handling in the callback router".
• Auto-collapse: The UI auto-collapse feature for tool groups should remain keyed only on the activity label. An intent-labeled group without an activity label should remain expanded.

LibreChat uses FerretDB (PostgreSQL-backed) to achieve database-per-org data isolation.

Key Architectural Details:

• Logical Isolation: FerretDB does not create separate PostgreSQL schemas per MongoDB database. Instead, all data resides in a single documentdb_data PG schema.
• Data Mapping: Each MongoDB collection is mapped to a documents_<id> and retry_<id> table pair in PostgreSQL. The catalog is managed in documentdb_api_catalog.collections and .collection_indexes.
• Database Creation: Using mongoose.connection.useDb('org_X') creates a logical database within FerretDB's catalog.
• Isolation Enforcement: Isolation is enforced at the FerretDB wire protocol layer, not at the PostgreSQL schema level.

Important: Because isolation is logical, you cannot use standard pg_dump for backups/restores. You must use driver-level or FerretDB-compatible methods.

LibreChat's compatibility with Amazon DocumentDB depends on the engine version and cluster type. Use the following matrix to determine your deployment capability:

Critical Warnings:

• Elastic Clusters: These are unsupported. They lack unique indexes (required for email + tenantId), partial indexes, ACID transactions, and change streams.
• DocumentDB 4.0: Works, but partial unique indexes (used for OAuth account uniqueness) will fail to build. LibreChat will log this failure loudly at startup, but uniqueness will not be enforced by the database.