Installation and launch

Requirements

Installer

A Windows installer will come later (#30). Until then, install the application from source with the steps below.

Obscura connects to chat clients (Claude Desktop, Claude Code) with the “Connect to Claude” button in the library; see Chat clients (MCP).

Installing from source

Download the obscura-text-writer repository and open PowerShell in its folder:

python -m venv .venv
./.venv/Scripts/python.exe -m pip install -r requirements-lock.txt
./.venv/Scripts/python.exe -m pip install --no-deps -e ".[web,publication]"
if (-not (Test-Path .env)) { Copy-Item .env.example .env }

The last command creates .env only when the file does not exist yet, so running the block again does not erase your keys.

Provider keys

Open .env in a text editor and fill in the key only for the provider you will use:

A local provider needs no key. Keys stay on your computer; do not publish the .env file.

A key in the settings instead of .env

You can also enter the key in the application: Settings → Models, the "Provider key" block under the provider and model fields (the evaluator and helper classification settings have the same block). The key is kept in the Windows credential store, works at once without a restart, and is never shown again: you only see where it comes from.

In an installation from source this needs the keyring package, which is not in requirements-lock.txt:

./.venv/Scripts/python.exe -m pip install "keyring>=25,<26"

Without it the block reports that the store is unavailable, and the key has to be set in .env.

Launch

Keep personal stories in a separate folder outside the application folder:

./scripts/start.ps1 -DataDir "$env:LOCALAPPDATA/ObscuraTextWriter/data"

The browser opens http://127.0.0.1:8765. The server listens only on your computer. The -Port parameter sets another port, for example -Port 8770. Stop it with Ctrl+C in the PowerShell window.

If running PowerShell scripts is not allowed, use the direct command:

./.venv/Scripts/python.exe -m storygen.server --data-dir "$env:LOCALAPPDATA/ObscuraTextWriter/data" --env-file .env --open-browser

Launch without a console

The storygen-desktop command starts the application without a PowerShell window:

./.venv/Scripts/pythonw.exe -m storygen.desktop --env-file .env

On Windows the tray icon appears right away. A left click opens the application, and a right click shows the menu "Open Obscura", "Stories folder", "Quit". On other systems there is no icon: stop the application with Ctrl+C in the terminal.

Models

After the first launch open Settings → Models and, for each role, set the provider, the API address, the exact model ID and the limits. A local server usually listens on http://localhost:1235/v1. The model list button shows available IDs and known prices.

Backup

Stop the server before copying. The built-in backup checks integrity and hashes:

./.venv/Scripts/storygen.exe backup --data-dir "$env:LOCALAPPDATA/ObscuraTextWriter/data" --destination "D:/Backups/obscura-2026-11-11" --json
./.venv/Scripts/storygen.exe restore --backup-dir "D:/Backups/obscura-2026-11-11" --destination "D:/Restored/obscura" --json

Destination parent folders must exist. Restore creates only a new folder and overwrites nothing. You can also copy the whole data folder of a stopped server; do not copy the database apart from the texts.

To check the data folder without changing it, run ./.venv/Scripts/storygen.exe fsck --data-dir "<folder>" --json. It reports problems but repairs and deletes nothing. If a backup or restore was interrupted, do not use the incomplete folder: repeat the restore from a verified backup into another new folder.

Updating

Save manual edits, stop the server, update the code and start the server again. The data schema is updated when the storage opens. After a crash, unfinished runs are marked interrupted and continue only on your command.