Torvian Chatbot

Why Torvian Chatbot

Torvian Chatbot is a self-hosted AI workspace for users who want control over data, model providers, and tool execution. You run the server, bring your own LLM setup, and keep humans in the loop for agentic actions.

Key Features

• 🧠 Bring your own LLM providers: OpenAI-compatible APIs and local Ollama models.
• 📡 Stream model responses in real time, with support for concurrent responses from different chat sessions.
• 🧵 Organize long conversations with threaded/branched message flows.
• 🛡️ Keep control of tool execution: tool calls require approval by default, with optional per-tool auto-approve or auto-deny preferences.
• 🔁 Easily restart agentic conversations from any previous message, with full context and tool state restoration.
• 👥🔐 Manage multi-user access with authentication plus role/permission-based authorization.
• 💻📱🌐 Multi-platform clients for desktop, web, and Android, all connecting to the same server.
• ⚙️⏰ Run tools 24/7 on any machine (local, remote, VM), independent from where the client apps are running.

Live Demo

For a live demonstration of the Torvian Chatbot, please visit our demo page.

Platform Architecture

• Server: Core API and orchestration layer for authentication/authorization, chat sessions, message processing, LLM integration, tool lifecycle, and persistence.
• Client apps: Compose Multiplatform UI for Desktop, Web (WASM), and Android to chat, configure providers/models, and manage tools.
• Worker (optional): Standalone process for tool execution, useful for workspace isolation and always-on availability.

System Architecture

For a detailed explanation of the system architecture, including the LLM chat loop, remote tool execution flows, worker registration, and security context, see the System Architecture Flows document.

High-Level Architecture

flowchart TB
    subgraph Clients["Client Applications"]
        direction TB
        Desktop["Desktop App<br/>(Kotlin Compose)"]
        Android["Android App<br/>(Kotlin Compose)"]
        Web["Web App<br/>(WASM/JS)"]
    end

    subgraph Server["Torvian Server"]
        direction TB
        API["Ktor HTTP Server<br/>(REST + WebSocket)"]
        Business["Chat Service<br/>(Business Logic)"]
        DB["SQLite Database<br/>(Exposed ORM)"]
    end

    subgraph Workers["Worker Processes"]
        Worker1["Worker 1<br/>(MCP Executor)"]
        Worker2["Worker 2<br/>(MCP Executor)"]
        WorkerN["Worker N<br/>(MCP Executor)"]
    end

    subgraph External["External Services"]
        OpenAI["OpenAI<br/>(GPT Models)"]
        Ollama["Ollama<br/>(Local Models)"]
        OpenRouter["OpenRouter<br/>(Multi-Provider)"]
    end

    Clients -->|"HTTPS + SSE<br/>WebSocket"| Server
    Server -->|"WebSocket<br/>(Custom JSON Protocol)"| Workers
    Server -->|"HTTPS REST API<br/>(Streaming SSE)"| External
    Server -->|"JDBC/SQLite"| DB

    style Clients fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style Server fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style Workers fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style External fill:#fce4ec,stroke:#c2185b,stroke-width:2px

Project Status

This project is in active development.

• Server + Desktop: Most complete and stable combination for daily use.
• Web (WASM): Stable with some limitations
• Android: Early-stage usability with known UX limitations.

Getting Started

1. Download pre-built packages

Pre-built packages are available from the Releases page:

• Server: Optional; Use this package only if you want to run the server directly using Java. Otherwise, use the prebuilt Docker image from ghcr.io or build it locally from source.
• Worker: Optional; Use this package only if you want to run the worker directly using Java. Otherwise, use the prebuilt Docker image from ghcr.io or build it locally from source.
• Desktop Client: Available for Windows and Linux.
• Web Client: Available as a static web app. It must be served over HTTP(S).

2. Run the server

# Linux/Mac
<install-path>/start-server.sh
# Windows
<install-path>/start-server.bat

Docker quick start:

docker run -d \
  --name chatbot-server \
  -p 8080:8080 \
  -e SERVER_HOST=0.0.0.0 \
  -e SERVER_CONNECTOR_TYPE=HTTP \
  -v chatbot-server-config:/app/config \
  -v chatbot-server-data:/app/data \
  -v chatbot-server-logs:/app/logs \
  --restart unless-stopped \
  ghcr.io/torvian-eu/chatbot-server:latest

Notes:

• For powershell, replace \ with `
• For full deployment options and configuration details (including Docker Compose + Caddy), see deploy/README.md.

3a. Run the desktop application (recommended)

# Windows
<install-path>/Chatbot-with-logs.bat
# Linux/Mac (if building from source, see below)
<install-path>/Chatbot-with-logs.sh

3b. Serve the web client (optional, not recommended)

The web client is a static web application and must be served over HTTP(S). Opening index.html directly via file:// will not work, because browsers block loading WASM and related assets from local files.

For local testing, you can use any simple static file server.

Example using Python:

cd <web-client-dist-path>
python -m http.server 4000

Then open your browser and navigate to:

http://localhost:4000

Notes:

• For production or VPS deployments, serve the same files using a regular web server such as Caddy or nginx.
• The address of the web client will need to be added to the CORS allowed origins in the server configuration to allow the web client to connect. (see application.json -> corsAllowedOrigins, or use environment variables to set SERVER_CORS_ALLOWED_ORIGIN_1 etc.)

4. Login

Login with username admin and password admin123. You will be asked to change the password on first login.

5. Run the worker (required for MCP tool execution)

# Linux/Mac
<install-path>/start-worker.sh
# Windows
<install-path>/start-worker.bat

Notes:

• The server must be running before starting the worker.
• An active user (or admin) account is required to start the worker, because the worker needs to authenticate with the server.
• On first startup, the worker will prompt you to enter the server URL and user credentials to connect. An SSL certificate will be generated during setup. On subsequent startups, the stored SSL certificate (and private key) will be used for authentication.
• To let clients authorize tool-execution requests on this worker, register their signer credentials via the --add-trusted-signer CLI flag (or environment variables). See the Trusted Signers guide for details.

Docker quick start:

docker run -it \
  --name chatbot-worker \
  -e CHATBOT_WORKER_SETUP_SERVER_URL=http://host.docker.internal:8080 \
  -e CHATBOT_WORKER_SETUP_AUTO_START=true \
  -e PUID=1000 \
  -e PGID=1000 \
  -v chatbot-worker-config:/app/config \
  -v chatbot-worker-data:/app/data \
  -v chatbot-worker-logs:/app/logs \
  -v chatbot-worker-npm-cache:/app/cache/npm \
  -v chatbot-worker-uv-cache:/app/cache/uv \
  --restart unless-stopped \
  ghcr.io/torvian-eu/chatbot-worker:latest

Notes:

• For powershell, replace \ with `
• The switch -it is used to allow interactive input during the worker setup process. After the initial setup, you can remove -it and add -d for subsequent runs if you prefer to run the worker in detached mode.
• We use host.docker.internal to allow the worker to reach the server running on the host machine.
• For full deployment options and configuration details (including Docker Compose + Caddy), see deploy/README.md.
• When using the prebuilt Docker image, the usable commands for starting an MCP server are limited to uvx and npx.
• The main benefit of using Docker for the worker is that it offers better isolation and therefore better security for tool execution. Malicious or buggy tools that are executed by the worker will not be able to access the host system or other processes, and will be limited in their ability to cause harm. Mounted volumes for config, data, and logs allow the worker to persist necessary information while still maintaining isolation.

Build from Source

Prerequisites

• Git
• JDK 21 or higher
• Gradle 9.x (included via wrapper)

Clone the repository

cd <parent-path>
git clone https://github.com/Torvian-eu/chatbot.git

Build & Install Server application

./gradlew server:installDist

The files will be installed to server/build/install/server/. You can run the server using the scripts in that folder.

Build & Install Desktop application

./gradlew app:createDistributable

The files will be installed to app/build/compose/binaries/main/app/Chatbot. You can run the desktop client using the scripts in that folder.

Build & Install Web application

./gradlew app:wasmJsBrowserDistribution

The files will be installed to app/build/dist/wasmJs/productionExecutable. You can serve the web client using any static file server, as described in the "Serve the web client" section above.

Build & Install Worker application

./gradlew worker:installDist

The files will be installed to worker/build/install/worker/. You can run the worker using the scripts in that folder.

Guides

These guides provide information on how to configure and use specific features of the chatbot.

• LLM configuration guide - How to configure LLM providers, models and model settings. And how to use them in the chatbot.
• MCP server configuration guide - How to configure and use MCP servers.
• Trusted Signers guide - How to authorize clients for worker tool execution via trusted signers (E2EA).

Deployment

For information on deploying the chatbot application to a VPS or server environment, please refer to the Deployment Guide. This includes:

• Quick Docker server startup
• Docker setup with Caddy reverse proxy
• VPS deployment with Docker Compose
• Configuration via environment variables

Additional deployment-related documentation:

• VPS Deployment Guide - Comprehensive guide for VPS deployment
• VPS Basics Guide - Linux basics for VPS management
• Docker Installation Guide - How to install Docker on a VPS

Project Structure

chatbot/
├── server/                 # Server module
├── worker/                 # Worker module for MCP tool execution
├── app/                    # Client application module (Desktop, Web, Android)
├── common/                 # Shared code
├── build-logic/            # Gradle convention plugins
├── docs/                   # Documentation
└── gradle/                 # Gradle wrapper and dependencies

Tech Stack

• Languages: Kotlin 2.3.10
• UI Framework: Compose Multiplatform 1.10.2 (with Material 3 1.9.0)
• Server: Ktor 3.4.1
• Database: SQLite with Exposed ORM 1.1.1 (Server)
• Dependency Injection: Koin 4.1.1
• Functional Programming: Arrow 2.2.2
• Logic: kotlinx.serialization
• Build Tool: Gradle 9.4.0

Additional Documentation

• Project Directory Tree
• Known Issues
• TODO List
• New feature ideas

License

This project is licensed under the MIT License

Contributing

We welcome community contributions to the Torvian Chatbot! Your feedback, bug reports, feature suggestions, and code contributions are highly valued.

Please see our comprehensive Contributing Guide for detailed information on how to get involved.

Support

For support or general questions, please post a message in the GitHub discussion forum.

Screenshots

• Desktop app GUI:
• MCP server configuration: