Marginalia

Marginalia is a self-hosted writing tool for long-form fiction co-written with large language models. You write the instructions for each part of the story, the model writes the prose, and Marginalia keeps everything around it in order: the branching story, the world lore, the summaries that keep long books within the model's context, and the prompt settings that shape the style.

It runs in your browser - either as a small server for you and your friends (Docker) or as a desktop app on your own computer - and works with any OpenAI-compatible API: OpenAI, OpenRouter, LiteLLM, llama.cpp, LM Studio, Ollama, vLLM and others.

The manual is at enerccio.github.io/Marginalia.

日本語

Marginalia は、大規模言語モデル（LLM）と共同で長編小説を書くためのセルフホスト型ツールです。各場面の指示を 書くとモデルが本文を生成し、Marginalia が分岐するストーリー、世界設定（ロアブック）、長い作品をコンテキストに 収めるための要約、文体を決めるプロンプト設定を管理します。

• ブラウザで動作します。サーバー（Docker）としても、デスクトップアプリとしても使え、OpenAI 互換 API （OpenAI、OpenRouter、LiteLLM、llama.cpp、LM Studio、Ollama、vLLM など）に対応しています。
• 画面は日本語に翻訳済みです。ワークスペース下部の「言語」セレクターで日本語を選ぶと、設定がアカウントに保存され、 次回ログイン時にも使われます。ログイン画面は英語です。
• インストール方法は下の Installation を、マニュアル（英語）は上のリンクをご覧ください。

Features

• Books with branching stories - regenerate or swipe a part, branch from any point, navigate the story tree, edit the generated text, mark chapters.
• Lorebooks - world and character notes inserted into the prompt when they matter: activation by book tags, text or regex filters, insertion into the lore block or right before the instructions, lorebooks nested in lorebooks. SillyTavern world info can be imported.
• Templates and macros - prompts are Handlebars templates with SillyTavern-compatible macros ({{user}}, {{getvar}}, {{random}}, {{if}}...), so imported lore keeps working.
• Summaries - older parts of the story are condensed so long books fit in the context window.
• Any OpenAI-compatible model - including reasoning models, with per-model context and response limits and generation settings ("protocols") you can switch per book.
• Backups - per-book backups with restore and copy, plus full database backups on a cron schedule.
• Multiple users - each with their own books, lore and models; administrators manage users, backups and cleanup.
• Languages - the interface is available in English and Japanese; every user picks their own language, and extensions can add more (Simplified Chinese is included as a plugin).
• Published books - share a read-only view of a book.
• Search and replace, commands - search and replace in the story and in lorebooks (also with regular expressions), and a command line in the story editor with commands that read and change the book.
• Agents (experimental) - a model works on a book on its own, on a copy, through the same commands; you follow it in a console, review what it changed and take over what you want. Needs the permission Agents (administrators have it).
• Permissions - an administrator decides per user who creates models, uses the help assistant or uses agents.
• Extensions - plugins add features at runtime (chapter markers, lorebook version history, AI reviews, side questions to the model).

Books	Lorebook	Story tree

Installation

Marginalia stores everything (database, backups, extensions) in a .marginalia folder in the home directory of the user that runs it. On first start it asks you to create the administrator account.

Desktop app (Windows, macOS, Linux)

A self-contained version for one computer: no Java or server to install, it listens only on your computer (http://127.0.0.1:8765) and opens in your browser.

1. Download the archive for your system from the releases page: marginalia-<version>-<os>-<arch>-app is the app, marginalia-<version>-<os>-<arch> a portable folder.
2. Extract it and start Marginalia:
   • macOS - move Marginalia.app to Applications and open it. The app is not signed yet: the first time, right-click it and choose Open, or run xattr -dr com.apple.quarantine /Applications/Marginalia.app.
   • Windows - run Marginalia\Marginalia.exe. SmartScreen may warn about an unknown publisher: More info → Run anyway.
   • Linux - run Marginalia/bin/Marginalia.
   • Portable folder - run bin/marginalia (or bin\marginalia.bat on Windows).
3. Marginalia appears as an M icon in the system tray (menu bar on macOS) with Open and Quit.

Data is kept in ~/.marginalia (%USERPROFILE%\.marginalia on Windows), logs in ~/.marginalia/desktop/logs. Starting the app again while it runs just opens it in the browser. Options for the portable launcher:

marginalia --port 8765        # another port (a free one is picked automatically when 8765 is taken)
marginalia --home /path       # keep the .marginalia folder somewhere else
marginalia --no-browser --no-tray

Server (Docker)

For several users or access from other devices.

git clone https://github.com/Enerccio/Marginalia.git
cd Marginalia
docker compose up -d

To use the prebuilt image (ghcr.io/enerccio/marginalia, amd64 and arm64) instead of building it, see the Docker guide.

Marginalia is then available on port 8080 and keeps its data in ./data. Memory and other JVM options are set in docker-compose.yml (JAVA_TOOL_OPTIONS).

Marginalia uses login cookies, so don't expose it to the internet over plain HTTP - put it behind a reverse proxy with HTTPS (Caddy, nginx, Traefik...) and forward to port 8080. Don't leave an account without a password on a server.

The image reports its health to Docker (docker ps shows healthy once Marginalia is up, which takes a minute).

Upgrading: the database is migrated automatically when a newer version starts. A migration that fails is rolled back and Marginalia does not start, but one that went through stays, and an older version refuses the migrated database. So before changing the structure of an existing database Marginalia saves a copy in db-backups (the last three are kept, listed in Admin → Database Backups). It's still wise to make your own database backup first, then git pull && docker compose up -d --build (or docker compose pull && docker compose up -d with the prebuilt image).

Build from source

Requirements: JDK 25 or newer and Maven 3.9+. Node.js for the frontend is downloaded by the build.

cd marginalia
mvn package               # deployable WAR (Vaadin production mode) in target/, runs the tests
mvn package -Pdesktop     # desktop app for the current OS in target/desktop/ (see the desktop profile in pom.xml)

The Docker image is built from source by docker compose build.

Connecting a model

In Inference Providers, add the base URL of your OpenAI-compatible API (for example https://api.openai.com/v1, https://openrouter.ai/api/v1 or http://localhost:8080/v1 for llama.cpp), an API key if it needs one, and pick the model. Then create a book, choose the provider and a protocol, and start writing.

Extensions

Extensions are OSGi bundles (JAR files). Administrators install them in Admin → Extensions; they are stored in ~/.marginalia/extensions. Eighteen plugins are included in marginalia/plugins and built separately with Maven, or in Docker (see the plugins README):

• Anthropic Claude - Anthropic's Claude models as an inference provider, over the Anthropic Java SDK,
• Arc Outline - the arcs of the book and their chapters in the story sidebar, written by the model if you want,
• Author's Note - a note to the model inserted into every generation,
• Chapter Marker - chapters in the story sidebar,
• Character Tracker - the characters of the book with their relationships and a map of them,
• Gemma 4 tools fix - function calling with Gemma 4 models whose API wants another role for tool results,
• Google Gemini - Google's Gemini models as an inference provider, over the Google Gen AI SDK,
• Instruction Exporter - copy the instructions, scene settings and characters of the story to the clipboard,
• Lore Generator - write a lorebook entry with the model from the existing lore,
• Lorebook VCS - revision history for lorebook entries,
• Manga Generator - turn parts of the story into a manga script and image generation tags,

The extension API is not frozen in 1.0: extensions are built for one Marginalia version, and Marginalia refuses to start one that does not fit the version it is running.

License

MIT, see LICENSE.