How to Set Up ChocolateLMLite: Complete Installation and Configuration Guide

ChocolateLMLite is a self-hosted C# .NET 8 AI chat application that runs a lightweight Kestrel web server on port 8010, using SQLite for persistence and offering both REST and WebSocket APIs for real-time conversation management.

ChocolateLMLite, available at gpsnmeajp/chocolatelmlite, provides a lightweight, authentication-free alternative to cloud-based AI services. This guide explains how to set up ChocolateLMLite from source, configure external LLM providers, and begin chatting through its web interface or API endpoints.

Prerequisites and Installation

Before running the server, install the required toolchain and optionally prepare an LLM backend.

Required components:

• Git – for cloning the repository

• .NET 8 SDK – the runtime and build tools for the C# application

• LLM Provider (optional) – OpenRouter, Ollama, LM Studio, or any OpenAI-compatible endpoint

On Windows, install dependencies via WinGet and clone the repository:

winget install --id Git.Git -e --source winget
winget install --id Microsoft.DotNet.SDK.8
git clone https://github.com/gpsnmeajp/chocolatelmlite.git
cd chocolatelmlite

Restore NuGet packages to prepare the build:

dotnet restore

Starting the Server for the First Time

Launch the application using the .NET CLI. The src/Program.cs file bootstraps the Kestrel host, loads configuration, and initializes the SQLite database.

dotnet run

By default, the server listens on http://localhost:8010. On first startup, src/SQLiteDB.cs automatically creates data/main.db in the project directory to store personas, messages, and system settings.

Verify the server is running by requesting the current settings:

curl http://localhost:8010/api/setting

This endpoint, implemented in src/WebServer.cs (lines 180-210), returns a JSON object containing LlmEndpointUrl, DefaultModel, EnableVoiceVox, and other configuration keys.

Configuring Your LLM Backend

ChocolateLMLite delegates all inference to external providers through the abstraction layer in src/LLM.cs and the HTTP handler in src/OpenRouterHttpHandler.cs.

Update the backend URL and API key via the settings API:

curl -X POST http://localhost:8010/api/setting \
     -H "Content-Type: application/json" \
     -d '{"LlmEndpointUrl":"https://openrouter.ai/api/v1","LlmApiKey":"sk-..."}'

Supported providers include OpenRouter, Ollama (local), LM Studio, and any OpenAI-compatible service. The LLM.cs class handles model selection, temperature, token limits, and timeout settings for each request.

Creating and Managing Personas

Conversations in ChocolateLMLite are organized around personas – isolated contexts with unique system prompts, memory, and model assignments. The src/Persona.cs class manages these entities through CRUD operations backed by src/SQLiteDB.cs.

Create a new persona:

curl -X POST http://localhost:8010/api/persona/new \
     -H "Content-Type: application/json" \
     -d '{"name":"Project Bot"}'

The server returns {"id": 2} (or similar), representing the new persona's primary key in the SQLite database.

Activate a persona for chatting:

curl -X POST http://localhost:8010/api/persona/active \
     -H "Content-Type: application/json" \
     -d '{"id":2}'

According to the src/WebServer.cs implementation, this cancels any ongoing generation and switches the active context to the specified persona ID.

Sending Messages and Monitoring Responses

Interact with the active persona through the message endpoint and WebSocket stream.

Send a chat message:

curl -X POST http://localhost:8010/api/persona/active/message \
     -H "Content-Type: application/json" \
     -d '{"Role":"User","Text":"こんにちは"}'

The server immediately returns {"success":"done","uuid":"<guid>"} and begins asynchronous LLM generation in the background.

Monitor real-time progress:

Connect to the WebSocket endpoint at ws://localhost:8010/ws (implemented in src/WebServer.cs, lines 720-770):

wscat -c ws://localhost:8010/ws

The server streams JSON-lines containing generation status and partial responses. If VoiceVox integration is enabled via EnableVoiceVox in settings, the src/VoiceVox.cs module also streams binary audio blobs for text-to-speech output.

Security Considerations

ChocolateLMLite is deliberately authentication-free, designed for trusted local networks, Tailscale meshes, or personal development machines. As implemented in the gpsnmeajp/chocolatelmlite source code, no login mechanism protects the REST or WebSocket endpoints.

If exposing the server publicly, place a reverse proxy (nginx, Caddy, or Traefik) in front of port 8010 to enforce basic authentication, IP filtering, or TLS termination. The application assumes a benign environment and does not sanitize inputs for hostile network exposure.

Summary

• ChocolateLMLite requires only the .NET 8 SDK and Git to build from source at gpsnmeajp/chocolatelmlite.
• The src/Program.cs entry point starts a Kestrel server on port 8010, persisting data to data/main.db via src/SQLiteDB.cs.
• Configure external LLM providers (OpenRouter, Ollama) through the /api/setting endpoint.
• Create and activate personas via /api/persona/new and /api/persona/active to isolate conversation contexts.
• Send messages to /api/persona/active/message and receive real-time updates through the WebSocket at /ws.
• Deploy behind a reverse proxy if exposing beyond localhost, as the application lacks built-in authentication.

Frequently Asked Questions

How do I change the default port from 8010?

Modify the configuration before starting the server. The port is defined in the host builder setup within src/Program.cs. Alternatively, set the ASPNETCORE_URLS environment variable: ASPNETCORE_URLS=http://localhost:5000 dotnet run.

Where is the conversation data stored?

All personas, messages, and memory entries persist in data/main.db, an SQLite file created automatically on first launch. The src/SQLiteDB.cs class manages all database operations, ensuring state survives server restarts.

Can I run ChocolateLMLite on Linux or macOS?

Yes. Since the application targets .NET 8, it runs cross-platform. Install the .NET 8 SDK for your distribution via the Microsoft package repositories or Homebrew on macOS, then follow the same git clone and dotnet run steps.

How do I add authentication to the server?

The codebase intentionally excludes authentication mechanisms. To secure the application, deploy a reverse proxy such as nginx or Caddy in front of the Kestrel server. Configure the proxy to require HTTP Basic Authentication or restrict access by IP address before forwarding traffic to localhost:8010.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}