Migrate to uvilo-mono Vision
Vision
Replace LibreChat as Forge’s chat/agentic runtime with uvilo-mono, achieving feature parity so Forge can operate autonomously on its own stack.
Background
Forge currently depends on LibreChat for 10 capabilities: agent definitions, MCP tool routing, sub-agent spawning, streaming responses, conversation persistence, memory, model switching, authentication, file uploads, and UI controls. uvilo-mono provides native equivalents (Bot ≡ Agent, Convo ≡ Conversation, AI Tool ≡ MCP tool, Execution ≡ job runner) that cover the parity gap partially or fully.
Research Instructions
Evaluate Option A (Convert BotCraft → Forge) as the primary approach for agentic inference. If it fails, evaluate Option B (Railway-sidecar uvilo-ai). The agentic inference question (Research §1) must be resolved before implementation work begins.
Requirements
R0: Deployment Compatibility
The migrated system MUST run on Railway (Forge’s current infrastructure).
R1: Bot-to-Agent Parity
Each current LibreChat agent MUST be representable as a uvilo-mono Bot with system prompt, model binding, per-Bot MCP tool binding, and parameter defaults.
R2: External MCP Server Lifecycle
The system MUST support attaching external MCP servers (stdio and SSE) to Bots with configurable process lifecycle, tool discovery, and per-Bot filtering — equivalent to LibreChat’s mcpServers config.
R3: Sub-Agent Spawning API
The system MUST provide an API for programmatic agent execution (create convo, send message, stream/poll responses, monitor, abort/restart) — replacing forge-spawn’s dependency on LibreChat’s UI Chat API.
R4: Runtime Model Override
The system MUST allow selecting a model variant when starting a conversation with a Bot, without requiring duplicate Bot definitions.
R5: Auth Integration for Programmatic Access
The system MUST support API-key-based authentication for programmatic agent spawning. (Already implemented — see Research §2.)
Success Criteria
| # | Criterion | Measured by |
|---|---|---|
| V0 | Entire system runs on Railway without LibreChat | LibreChat removed from stack |
| V1 | All 19 LibreChat agents created as uvilo-mono Bots | Agent list matches; equivalent behavior |
| V2 | All 16 MCP servers attached with tools routed to correct Bots | MCP server list matches; tool routing verified |
| V3 | Sub-agents spawned and monitored without LibreChat | Spawn/monitor/abort all work |
| V4 | Model override works without duplicate Bot definitions | Select model at conversation start |
| V5 | API-key auth verified for programmatic access | Existing implementation confirmed working |
Out Of Scope
- Replacing LibreChat’s entire feature set (bookmarks, presets, search, etc.) — only Forge-used features
- Changing uvilo-mono’s SaaS product architecture — extending it for Forge’s agentic use case
- Multi-tenant isolation — Forge is single-user
- LibreChat agent handoffs (already rejected in Libre_Agents research)