Skip to content
Back to search

vellium

Local-first desktop AI workbench for roleplay, multi-character chat, long-form writing, RAG, MCP tools, plugins, and local models.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tg-prplx/vellium with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tg-prplx/vellium'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tg-prplx--vellium/badge.svg)](/listings/tg-prplx--vellium)

HTML

<a href="/listings/tg-prplx--vellium"><img src="/api/listings/tg-prplx--vellium/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Download the current artifacts from [GitHub Releases](https://github.com/tg-prplx/vellium/releases/latest):

- macOS: Apple Silicon (`arm64`) and Intel (`x64`); - Windows: `x64`; - Linux: `x64` AppImage.

Release builds are currently unsigned. The operating system may require manual confirmation on first launch. The release badge above is the source of truth; this README deliberately does not hardcode a version number.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 203 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Vellium
  2. [![Latest release](https://img.shields.io/github/v/release/tg-prplx/vellium?display_name=tag&sort=semver)](https://github.com/tg-prplx/vellium/releases/latest)
  3. [![Downloads](https://img.shields.io/github/downloads/tg-prplx/vellium/total)](https://github.com/tg-prplx/vellium/releases)
  4. [![Stars](https://img.shields.io/github/stars/tg-prplx/vellium?style=flat)](https://github.com/tg-prplx/vellium/stargazers)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
  6. <img width="1440" height="898" alt="image" src="https://github.com/user-attachments/assets/87797380-21ab-452d-ac5f-2bd0e119116e" />
  7. Vellium is a local-first desktop workbench for AI chat, character roleplay, live
  8. voice conversations, and long-form writing. It connects to OpenAI-compatible
  9. APIs, OpenRouter, Requesty, Demon Route, Cheaper Inference, API Route, UberLLM, LM Studio, Ollama,
  10. KoboldCpp, and configurable custom endpoints. Chats, characters, projects, settings, and knowledge collections are
  11. stored locally in SQLite.
  12. <p align="center">
  13. <a href="https://github.com/tg-prplx/vellium/releases/latest"><strong>Download for macOS, Windows, or Linux</strong></a>
  14. ·
  15. <a href="./docs/vellium/getting-started.md">Quick start</a>
  16. ·
  17. <a href="./docs/vellium/README.md">User guide</a>
  18. </p>
  19. > [!IMPORTANT]
  20. > **Agents is deprecated.** It is disabled by default and is not a primary
  21. > Vellium workspace. Existing agent threads and the implementation are retained
  22. > for compatibility under **Settings → Legacy → Agents**. New workflows should
  23. > use Chat, Writing, MCP tools, or plugins. See the
  24. > [Legacy and Agents policy](./docs/vellium/legacy-and-agents.md).
  25. ## What Vellium includes
  26. - **Chat and roleplay:** branching timelines, message editing, multiple
  27. characters, personas, LoreBooks, author notes, scene state, prompt blocks,
  28. translation, attachments, export, and controllable automatic turns.
  29. - **Reasoning-aware context:** provider reasoning fields and `<think>` traces can
  30. be displayed, bounded, persisted, and optionally returned to the model as
  31. context. RP Reasoning is a separate simulated prompt mode.
  32. - **Live voice and Inochi2D avatars:** microphone input, Whisper-compatible STT,
  33. streaming TTS, parameter-driven lip sync/emotions for `.inp`/`.inx` puppets,
  34. model and RP controls, attachments, screen context, and chat tools in Live mode.
  35. - **Writing:** projects, chapters, scenes, Character Forge, summaries, rewrite
  36. and expansion actions, RAG context, DOCX import, and DOCX/Markdown export.
  37. - **Characters and world data:** character-card import/editing, manual character
  38. ordering, multi-character participation, LoreBooks, and world-info import.
  39. - **Knowledge and RAG:** collections, bounded ingestion, embeddings, optional
  40. reranking, and explicit bindings for Chat and Writing.
  41. - **Providers:** OpenAI-compatible APIs, KoboldCpp, custom endpoint adapters,
  42. manual model fallbacks, job-specific model routing, and API parameter policy.
  43. - **Tools and extensions:** MCP tool calls, structured image results, local
  44. plugins, themes, widgets, custom inspector fields, and desktop pets.
  45. - **Local control:** SQLite persistence, Full Local Mode, provider URL checks,
  46. permission-gated plugins, and separate security gates for powerful legacy
  47. workspace tools.
  48. The interface is translated into English, Russian, Chinese, and Japanese.
  49. ## Install a desktop build
  50. Download the current artifacts from
  51. [GitHub Releases](https://github.com/tg-prplx/vellium/releases/latest):
  52. - macOS: Apple Silicon (`arm64`) and Intel (`x64`);
  53. - Windows: `x64`;
  54. - Linux: `x64` AppImage.
  55. Release builds are currently unsigned. The operating system may require manual
  56. confirmation on first launch. The release badge above is the source of truth;
  57. this README deliberately does not hardcode a version number.
  58. ## Run from source
  59. Requirements:
  60. - Node.js 20 or newer;
  61. - npm;
  62. - Python 3 and Pillow only when regenerating application icons.
  63. ```bash
  64. npm install
  65. npm run dev
  66. ```
  67. The development renderer runs at `http://127.0.0.1:1420` and proxies `/api` to
  68. the Express server at `http://127.0.0.1:3002`.
  69. Use the real desktop shell when testing Electron behavior:
  70. ```bash
  71. npm run dev:electron
  72. ```
  73. `better-sqlite3` is a native dependency. If Node or Electron reports an ABI
  74. mismatch, rebuild it for the runtime you are about to use:
  75. ```bash
  76. npm run rebuild:native
  77. npm run rebuild:native:electron
  78. ```
  79. ## Build and package
  80. ```bash
  81. npm run build:desktop
  82. npm run dist:mac
  83. npm run dist:win
  84. npm run dist:linux
  85. ```
  86. `build:desktop` compiles the renderer, server bundle, Electron main process, and
  87. preload. Platform packages are written to `release/`. Pushing a `v*` tag starts
  88. the multi-platform workflow in `.github/workflows/build-desktop.yml` and
  89. publishes GitHub Release assets; do not use release tags as a local test command.
  90. ## Headless local web mode
  91. ```bash
  92. npm run headless
  93. ```
  94. This builds and serves the frontend and API at `http://127.0.0.1:3001` without
  95. opening Electron. Public binding is opt-in and requires Basic Authentication.
  96. See the [runtime and integration reference](./docs/vellium/runtime-and-integration-reference.md)
  97. for flags and environment variables.
  98. ## Data and privacy
  99. - Development data: `data/`.
  100. - Packaged desktop data: `<Electron userData>/data` through `SLV_DATA_DIR`.
  101. - Primary database: `vellum.db` (`sillytauri.db` remains a legacy fallback).
  102. - API keys are masked at response boundaries, but local application data is not
  103. an encrypted vault by default. Protect the operating-system account and data
  104. directory accordingly.
  105. - Full Local Mode blocks configured public provider endpoints; it does not turn
  106. untrusted plugins, MCP commands, or legacy workspace tools into safe code.
  107. Do not commit `data/`, `output/`, `release/`, generated bundles, or imported user
  108. assets.
  109. ## Settings and timeouts
  110. Press `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS) to search settings, jump to the
  111. owning section, and highlight the target control.
  112. Long operations do not share a hidden renderer-wide timeout. Endpoint discovery,
  113. speech transcription, translation, MCP servers, and other bounded operations
  114. have settings at the layer that owns them. Endpoint discovery and speech limits
  115. are under **Settings → Generation → Runtime tuning**; each managed backend has
  116. its own startup timeout under **Settings → Backends**.
  117. ## Plugins and MCP
  118. Plugins are local extensions, not packages from a trusted marketplace. Review
  119. their declared permissions before enabling them. Plugin management and
  120. `Pluginfile` import/export live under **Settings → Tools & MCP → Plugins**.
  121. MCP child processes are allowlisted and reject inline-eval launch forms. MCP can
  122. still expose powerful tools, so enable only the servers and individual functions
  123. you intend to use.
  124. - [Plugin author guide](./docs/plugins/README.md)
  125. - [Tool calls and generated media](./docs/vellium/tool-calls-and-media.md)
  126. - [Plugins and security](./docs/vellium/plugins-and-security.md)
  127. ## Documentation
  128. - [User guide and documentation map](./docs/vellium/README.md)
  129. - [Getting started](./docs/vellium/getting-started.md)
  130. - [Chat and roleplay](./docs/vellium/chat-and-rp.md)
  131. - [Characters and LoreBooks](./docs/vellium/characters-and-lorebooks.md)
  132. - [Writing](./docs/vellium/writing.md)
  133. - [Knowledge and RAG](./docs/vellium/knowledge-and-rag.md)
  134. - [Settings and providers](./docs/vellium/settings-and-providers.md)
  135. - [Legacy and Agents](./docs/vellium/legacy-and-agents.md)
  136. - [Troubleshooting](./docs/vellium/troubleshooting.md)
  137. ## Repository map
  138. ```text
  139. src/ React renderer and shared contracts
  140. server/ Express API, SQLite repositories, provider and MCP services
  141. electron/ Desktop main process, preload bridge, managed backends, pets
  142. scripts/ Development, architecture, native rebuild, and packaging helpers
  143. docs/ User, runtime, security, and plugin documentation
  144. ```
  145. The main verification commands are:
  146. ```bash
  147. npm test
  148. npm run check:architecture
  149. npm run typecheck
  150. npm run build
  151. npm audit --audit-level=low
  152. ```
  153. See [AGENTS.md](./AGENTS.md) for repository boundaries, invariants, and the
  154. maintainer verification matrix.
  155. ## License
  156. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.