# How to Set Up ChocolateLMLite: Complete Installation and Configuration Guide

> Install and configure ChocolateLMLite a self-hosted C# .NET 8 AI chat app. Learn how to set up ChocolateLMLite for real-time conversation management with this comprehensive guide.

- Repository: [Segment (gpsnmeajp)/chocolatelmlite](https://github.com/gpsnmeajp/chocolatelmlite)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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:

```bash
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:

```bash
dotnet restore

```

## Starting the Server for the First Time

Launch the application using the .NET CLI. The [`src/Program.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/Program.cs) file bootstraps the Kestrel host, loads configuration, and initializes the SQLite database.

```bash
dotnet run

```

By default, the server listens on `http://localhost:8010`. On first startup, [`src/SQLiteDB.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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:

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

```

This endpoint, implemented in [`src/WebServer.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/LLM.cs) and the HTTP handler in [`src/OpenRouterHttpHandler.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/OpenRouterHttpHandler.cs).

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

```bash
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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/Persona.cs) class manages these entities through CRUD operations backed by [`src/SQLiteDB.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/SQLiteDB.cs).

**Create a new persona:**

```bash
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:**

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

```

According to the [`src/WebServer.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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:**

```bash
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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/WebServer.cs), lines 720-770):

```bash
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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/Program.cs) entry point starts a Kestrel server on **port 8010**, persisting data to `data/main.db` via [`src/SQLiteDB.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`.