Moltis TS Gateway Fork

TypeScript-first AI gateway fork of Moltis with a real-time chat UI, WebSocket RPC, SQLite session storage, and optional Redis tooling.

This README is intentionally fork-specific and focused on what you can run today in this repo.

Why this fork

TypeScript gateway runtime under src/gateway/
Existing Preact UI retained and integrated
SQLite-backed sessions and chat history
OpenAI streaming chat in the new gateway
Optional Redis helper under src/redis/
Clear migration path from Rust workspace to full TS stack

Quick start (2 minutes)

npm install
cp .env.example .env
# set OPENAI_API_KEY in .env
npm run build:web
npm start

Open: http://127.0.0.1:8080

What you get right now

Area	Status
Web UI served by TS gateway	Ready
WebSocket `connect` handshake	Ready
`chat.send` streaming replies	Ready
Sessions list/switch + history API	Ready
SQLite persistence (`better-sqlite3`)	Ready
Redis utility module (`src/redis`)	Ready
Full upstream parity (tools/channels/sandbox)	In migration

Architecture (current fork)

flowchart LR
  UI[Preact Web UI] --> WS[WebSocket RPC /ws/chat]
  UI --> HTTP[REST /api/*]
  WS --> GW[TypeScript Gateway src/gateway]
  HTTP --> GW
  GW --> DB[(SQLite)]
  GW --> OAI[OpenAI API]
  GW -. optional .-> REDIS[(Redis helper)]

Runtime modes

Recommended: TypeScript gateway

npm run build:web
npm start

Legacy: upstream Rust runtime

Use this only if you need upstream-only features not migrated yet.

cargo build
cargo run

Commands

Command	Purpose
`npm start`	Start TypeScript gateway
`npm run build:web`	Build Preact assets from `crates/web/ui`
`npm run dev`	Build web assets and run gateway
`npm run typecheck`	Type-check TS sources
`npm run test`	Run Vitest suite
`npm run validate:redis`	Typecheck + tests for Redis tooling

Configuration

Copy .env.example and set at least OPENAI_API_KEY.

Core gateway

Variable	Default	Notes
`MOLTIS_GATEWAY__HOST`	`127.0.0.1`	Bind host
`MOLTIS_GATEWAY__PORT`	`8080`	HTTP/WebSocket port
`MOLTIS_DATA_DIR`	`.moltis/data`	SQLite DB location
`OPENAI_API_KEY`	unset	Required for live chat
`MOLTIS_DEFAULT_MODEL`	`gpt-4o-mini`	Default model
`MOLTIS_DEFAULT_PROVIDER`	`openai`	Provider id

Optional Redis tooling

import { RedisConnectionManager, withRedis } from "moltis/redis";

Variable	Default
`REDIS_URL`	unset
`REDIS_HOST`	`127.0.0.1`
`REDIS_PORT`	`6379`
`REDIS_DB`	`0`
`REDIS_KEY_PREFIX`	`moltis:`

Project map

moltis/
├── src/
│   ├── gateway/          # TypeScript gateway runtime
│   └── redis/            # Optional Redis module
├── tests/redis/          # Vitest tests for Redis module
├── crates/web/ui/        # Existing Preact UI source
├── package.json
├── tsconfig.json
└── docs/internal/
    └── TYPESCRIPT-GATEWAY.md

Migration note

This fork is migrating from the original Rust workspace to a full TypeScript stack in phases.

Current migration details: docs/internal/TYPESCRIPT-GATEWAY.md
crates/ still exists to preserve upstream compatibility while TS features are brought over.

Troubleshooting

Blank UI after start: run npm run build:web again.
Chat returns fallback response: check OPENAI_API_KEY.
Port in use: change MOLTIS_GATEWAY__PORT in .env.
Redis tests fail: Redis is optional for runtime; ensure env values are valid when testing Redis-specific code.

Contributing

PRs are welcome. Keep changes scoped, include verification commands, and call out whether changes target:

TypeScript gateway (src/gateway)
Redis tooling (src/redis)
UI integration (crates/web/ui)
Migration/docs

License

MIT. See LICENSE.md.

moltis-gateway-mcp