Vellium — local-first AI workbench for chat, roleplay and writing

One desktop app for character chat, multi-character roleplay, long-form writing, RAG, MCP tools, plugins and local models.

Vellium is a free, open-source desktop AI workspace that works with OpenAI-compatible APIs, OpenRouter, LM Studio, Ollama, KoboldCpp and custom endpoints. Your chats, characters, projects and knowledge stay in a local SQLite database.

Download for macOS, Windows or Linux · Quick start · User guide

Current Release

Latest release: v1.0.0
Desktop builds: macOS (arm64, x64), Windows (x64), Linux (x64 AppImage).
Release builds are unsigned. macOS and Windows may require manual confirmation on first launch.
The app is usable day to day, but still moving quickly. Expect active iteration around Agents, tool calling, and provider compatibility.

Why Vellium?

Bring your own model. Use cloud APIs or local models without locking the workspace to one provider.
Built for stories, not just prompts. Characters, personas, LoreBooks, scene state, branching conversations and automatic multi-character turns live together.
Write beyond chat. Organize projects, chapters and scenes; rewrite, expand, summarize and export to DOCX or Markdown.
Give models useful context. Connect knowledge collections through RAG and scripted world facts through LoreBooks.
Extend it locally. Add MCP tools, plugin tabs, widgets, themes, endpoint adapters and desktop pets.
Keep control. Local storage, local-only networking mode and explicit security gates for powerful tools.

User Documentation

Detailed user guide: docs/vellium/README.md

Important

Use npm run dev for day-to-day development.
Use npm run dev:electron when testing the real desktop shell.
Use npm run dist:mac, npm run dist:win, or npm run dist:linux for platform bundles.
CI publishes GitHub Release assets when a v* tag is pushed.
Local data is stored in data/ during development and in the Electron user-data directory in packaged builds.

Stack

Electron
React + TypeScript + Vite
Express
SQLite + better-sqlite3
Tailwind CSS

Core Features

Agents

Dedicated Agents workspace with ask, build, and research modes.
Workspace tools for listing, reading, searching, editing, moving, deleting, and diffing files.
Optional command execution for tests/builds, with separate security gates for shell-like commands, network commands, destructive file operations, and git writes.
OpenAI-compatible structured planning with JSON-schema responses when supported.
Mid-run corrections, abort/resume/retry, event traces, reasoning traces, and partial-response recovery.
Context management for long agent threads, including auto-compaction, continuation cues, duplicate read-only call guards, and stale-run cleanup after edits/deletes.

Chat / RP

Branching chat history.
Edit, delete, resend, regenerate.
Multi-character chats with auto-turns.
RP controls: prompt stack, author note, scene state, presets, personas.
LoreBook / World Info support, including SillyTavern-compatible world info import/export.
Reasoning support, including streamed reasoning fields and <think>...</think> parsing.
Vision attachments and chat attachments.
MCP tool calling for OpenAI-compatible chat/completions providers, with text-tool-call fallback parsing for providers that do not emit native tool calls cleanly.

Writing

Projects, chapters, scenes, outlines.
Summaries, rewrite/expand flows, consistency tools.
Character-aware writing workflows.
DOCX import and DOCX / Markdown export.
Writing-side RAG support.

Knowledge / RAG

Knowledge collections and ingestion.
RAG bindings for chat and writing.
Embedding and reranker model settings.
Hybrid retrieval-oriented foundation.

Providers

OpenAI-compatible providers.
KoboldCpp support.
Custom endpoint adapters for non-OpenAI / non-Kobold backends.
Presets for OpenAI, LM Studio, Ollama, KoboldCpp, OpenRouter, and custom OpenAI-compatible endpoints.
Manual fallback models for providers whose /models endpoint is missing, empty, or provider-specific.
Separate models for translate / compress / TTS / RAG.
API parameter forwarding controls for providers that reject unsupported sampling fields.

Localization

Built-in UI translations: English, Russian, Japanese, and Chinese.
Language selectable in Settings, with English as the fallback locale.

Desktop Pet

Optional always-on-top desktop companion window.
Animated states (idle, hop, pop, sway, spin, shake, bounce) with configurable state presets.
Chat with the pet directly from the desktop, including attachments and a configurable context token limit.

Plugins / Extensions

Toolbar tabs from plugins.
Plugin widgets in chat, writing, and settings slots.
Plugin actions in toolbar, messages, composer, and writing.
Plugin settings, permissions, plugin-local storage.
Pluginfile install/export.
Plugin themes.
Custom inspector fields.
Custom endpoint adapters.

Requirements

Node.js + npm. Node.js 20+ is recommended because CI builds with Node 20.
Python 3 + Pillow for icon generation:

pip install pillow

Notes:

better-sqlite3 is native. Keep dev/build Node versions consistent.
If native ABI breaks, run npm run rebuild:native.

Quick Start

Install dependencies:

npm install

Start frontend + local API:

npm run dev

Open:

http://localhost:1420

Electron Dev

npm run dev:electron

This builds Electron entrypoints, starts the local server, starts Vite, waits for health checks, then launches Electron.

One-Click Bootstrap

macOS:

./setup-and-run-dev.sh

Windows:

setup-and-run-dev.bat

These scripts try to:

install Node.js LTS,
run npm install,
start npm run dev.

Build Desktop App

All desktop targets:

npm run dist

macOS only:

npm run dist:mac

Windows only:

npm run dist:win

Linux AppImage only:

npm run dist:linux

Build output goes to release/.

GitHub Actions

Workflow:

.github/workflows/build-desktop.yml

What it does:

builds macOS (x64, arm64), Windows (x64), and Linux (x64 AppImage) bundles,
uploads workflow artifacts,
publishes GitHub Release assets on v* tag pushes.

Plugins

Vellium now has a real plugin system.

Plugin capabilities:

toolbar tabs,
slot widgets,
modal and inline actions,
plugin-local settings,
permission-gated API access,
plugin themes,
Pluginfile import/export.

Useful docs:

docs/plugins/README.md

Runtime plugin locations:

user plugins: data/plugins
bundled plugins: data/bundled-plugins

Important:

plugins are local extensions, not a trusted public plugin marketplace model,
plugin permissions should be reviewed before enabling write access,
plugin settings and permissions are managed in Settings -> Plugins.

Pluginfile

Pluginfile is the portable single-file plugin package format.

You can:

install a plugin from Settings -> Plugins -> Install Pluginfile,
export an existing plugin from Settings -> Plugins -> Export Pluginfile.

Bundled plugins can also be exported as Pluginfile.

Themes

Vellium supports:

built-in dark/light themes,
plugin-provided themes.

Bundled theme pack:

Catppuccin
- Latte
- Frappe
- Macchiato
- Mocha

Theme plugins also propagate into plugin UI kit styling.

Extensions API

Vellium includes an extensions layer beyond normal plugins:

custom inspector fields,
custom endpoint adapters,
unified plugin-side backend access through vellium.generate(...) and related SDK namespaces.

This makes it possible to:

add inspector controls,
integrate non-OpenAI / non-Kobold backends,
build workflow plugins against a stable host-side contract.

TTS

Vellium supports OpenAI-compatible TTS:

configurable endpoint,
model selection,
voice selection,
per-message TTS actions.

App Icons

Generate icons:

npm run build:icons

Generated files:

build/icon.png
build/icon.icns
build/icon.ico

Useful Scripts

npm run dev — frontend + server.
npm run dev:frontend — Vite only.
npm run dev:server — Express API only.
npm run dev:electron — Electron + frontend + server.
npm run build — frontend production build.
npm run build:server — bundled server build.
npm run build:desktop — full desktop build pipeline without publishing.
npm run dist — package all desktop targets supported by the current host/CI runner.
npm run dist:mac / npm run dist:win / npm run dist:linux — package a specific desktop target.
npm run rebuild:native — rebuild better-sqlite3.
npm run test — Vitest.

Data Storage

In dev: local data/
In packaged app: SLV_DATA_DIR maps to Electron userData/data

Troubleshooting

`ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION ...`

Cause: better-sqlite3 was built against a different Node ABI.

Fix:

npm run rebuild:native

If needed, remove node_modules and reinstall.

`EADDRINUSE: address already in use :::3001`

Cause: an old server process is still alive.