FAQ & Troubleshooting

This page is the short answers. Every question here gets a fuller treatment somewhere else in the docs — installation, settings, the agent sections, the individual module pages — but this is the place to start when you just want to know whether Ishvana runs on your machine or what the license costs or why the installer is making Windows yell at you. If you don’t find what you’re looking for here, the sidebar search should get you the rest of the way.

The basics

What is Ishvana?

A desktop creative writing studio for fiction authors working on complex, lore-heavy projects. Fantasy, sci-fi, alt-history, anything with deep worldbuilding. One application that bundles a manuscript editor, a worldbuilding database called the Legendry, an outline system, a plot studio, six specialized agents, a research browser, a publishing pipeline, and correspondence tools. Think Scrivener meets a worldbuilding wiki meets a writing partner that reads your world — except everything actually talks to everything else, and nothing lives on somebody else’s server.

How much does it cost?

$99, one time. No subscription. You own it. Every patch and minor feature update inside your purchased major version is free. There’s no “Pro tier” that gates features behind a higher price. You pay once and you get the whole thing.

What platforms does it run on?

Windows 10 and Windows 11, 64-bit only. Ishvana is Windows-only right now. Mac and Linux aren’t supported — the backend is Python via PyInstaller and the frontend is Electron, so both could theoretically be ported, but neither is shipping today.

Where is my data stored?

Your Windows AppData folder:

C:\Users\<YourName>\AppData\Roaming\Ishvana\

Manuscripts, worldbuilding entries, agent conversations, settings, bookmarks, research — all local. The Divinity Engine runs on bundled local handlers, not cloud inference providers. Your project doesn’t live in the cloud. Your drafts aren’t on somebody’s server.

How do I back up my projects?

Back up the whole data folder

Copy the entire C:\Users\<YourName>\AppData\Roaming\Ishvana\ folder to wherever you keep backups. External drive, cloud storage, another machine — anywhere. That one folder contains everything. Restoring is dropping it back.

Projects are files on disk, not entries in a cloud service. That’s a deliberate design choice, because cloud-based writing tools have a history of losing people’s work during outages and account lockouts. If you want redundancy, use a sync tool pointed at the AppData folder — OneDrive, Dropbox, Google Drive, Syncthing, all of them work because your data is standard files.

Can I sync between machines?

Your license activates on up to three machines. For actual file sync, use any cloud sync tool pointed at the AppData folder. Ishvana doesn’t include built-in sync — the reason is that building a real-time sync engine correctly is a massive amount of work for something standard sync tools already do well, and cramming it in would compromise the rest of the product.

How does the license work?

• One purchase, up to three machine activations.
• Deactivate in Settings to free up a slot before switching machines.
• Auto-updates are included within your purchased major version.
• 14-day refund policy, no questions asked.

Engine setup

Which model provider should I use?

None. As of v1.2.0 on May 1, 2026, Ishvana no longer supports external LLM providers. You do not choose between Ollama, Anthropic, or OpenRouter; the Divinity Engine ships with the app and runs through local handlers.

The old provider comparison is historical. The current setup is simpler: install Ishvana, activate your license, create a project, and the agents are ready.

No provider account needed

If you are reading an older guide that tells you to paste in an API key or install Ollama, skip that step. Those settings were removed when the Divinity Engine replaced the provider layer.

Can I use multiple providers?

No. There are no provider assignments or per-agent model overrides in v1.2.0. Agents map to fixed Divinity Engine handlers.

What engine assets does Ishvana use?

Ishvana bundles local intelligence assets for embeddings, contradiction checks, classifiers, authored-library rendering, and handler-specific analysis. Some deeper features prompt you to install the optional Deep Analysis Pack, which remains local after installation.

How much does inference cost?

There is no per-message inference bill. You paid for Ishvana; local handler dispatch does not bill tokens or call a provider dashboard.

Do I need a GPU?

An Nvidia GPU with 8 GB VRAM is recommended for the fastest local embedding, contradiction, and deep-analysis workloads. CPU fallback works, but large scans take longer.

How do I set up Ollama?

You don’t. Ollama integration was removed with the external provider layer. Ishvana does not need it.

Writing and editing

Can I import from Scrivener, Word, or Google Docs?

DOCX imports directly — that covers Word and anything you export from Google Docs via File → Download → Microsoft Word. For Scrivener, use its Compile feature to export your project to DOCX and then import those files. PDF, Markdown, and plain text work too.

What file formats does Ishvana support?

• Import: DOCX, PDF, Markdown (.md), plain text (.txt).
• Export: DOCX and print-ready PDF through the Bookmaker.
• Internal storage: Documents are saved as .docx files on disk in your data folder. Nothing proprietary — if Ishvana disappeared tomorrow, your manuscripts would still open in Word.

Does it support Markdown?

The editor is a rich text editor based on TipTap, not a Markdown editor. It supports familiar formatting shortcuts and will import Markdown files. Lore imported through the lore ingestion pipeline gets parsed as Markdown if you feed it Markdown. If you’re deep in a Markdown-first workflow you can still use Ishvana, but the editor itself isn’t Markdown-native.

How does auto-save work?

Documents save automatically as you type. Your work gets written to .docx files on disk in your AppData data folder. There’s no “unsaved changes” state. Hit close whenever you want — nothing is in-flight.

Can I use Ishvana without a model provider?

Yes. There is no model provider to configure in v1.2.0. The editor, outline, Legendry, plot studio, timelines, maps, documents, publishing, chat, local analysis, and council workflows all run through the bundled Divinity Engine. Only internet-backed features such as Lagan web research, uncached WorldKnowledge Wikipedia lookups, email, license activation, and updates need a network connection.

Troubleshooting

Windows SmartScreen blocks the installer

The Unknown Publisher warning

When you first run the Ishvana installer, Windows SmartScreen may show a warning saying “Windows protected your PC” or “Unknown publisher.” SmartScreen builds trust based on download volume, and new software triggers the warning regardless of whether it’s signed.

Click More info, then Run anyway. Ishvana is code-signed through Azure Trusted Signing (Microsoft’s own service, certificate issued to Swordsfall Studios LLC). The warning stops showing as more users install and SmartScreen builds reputation for the certificate.

The app won’t start

Four things to check, in order:

1. Port 37737 is in use. Ishvana’s backend lives on port 37737. If another application is holding that port, the backend can’t start. Open Task Manager, find the process using the port, and close it.
2. A previous session didn’t shut down cleanly. Restarting your machine clears any orphaned processes from the last Ishvana run.
3. Antivirus is blocking the backend. See the antivirus section below.
4. Run as admin once to test. If Ishvana starts as admin but not normally, there’s a permissions issue with your AppData folder that needs to be sorted before anything else works.

My license key isn’t accepted

• Check for extra spaces on either side of the key when pasting. This catches more people than you’d think.
• Make sure you’re entering the license key from your purchase confirmation email — not the order number, not the transaction ID. The key is the long alphanumeric string.
• If you’ve already activated on three machines, deactivate one before trying a new one.
• If none of that works, email support. Keys aren’t locked to machines forever — human intervention fixes most activation problems inside a day.

Agent responses are slow

Usually one of three things is happening:

• Deep local analysis. Strict and Deep passes do more handler work, so they take longer than a quick scene scan.
• Large lore databases. If you have thousands of Legendry entries, queries that search lore take longer because more context is being assembled. This is expected and not a bug — the responses are better because of it.
• Background indexing. ChromaDB or Lore ML indexing can use CPU/GPU for a minute after a large import. Watch the status bar and Etherforce Observability to see what is running.

The editor is laggy

• Very long documents. The editor is tuned for documents under 5,000 words. Chapters over 10,000 words start feeling sluggish on lower-spec hardware. Split them.
• Too many documents open at once. Close documents you’re not actively using.
• ChromaDB indexing. After importing a big batch of lore, the background vector indexer uses CPU for a minute or two. Watch the status bar — once it finishes, the editor goes back to normal.

Backend won’t start (port conflict)

Port 37737 is the backend. If something else is using it:

1. Open PowerShell and run netstat -ano | findstr 37737.
2. Look at the PID in the last column.
3. Open Task Manager, find that PID, end the process.
4. Restart Ishvana.

If this keeps happening, something on your system is configured to claim port 37737 at startup. Find it and reconfigure it — there’s no fix inside Ishvana itself, the port is hardcoded.

Antivirus is blocking Ishvana

PyInstaller false positives are real

Aggressive antivirus scanners sometimes flag Ishvana’s backend executable because it’s a bundled Python application built with PyInstaller, which has a long history of false-positive triggers. Ishvana is code-signed through Azure Trusted Signing, but signing doesn’t always stop heuristic scanners.

The fix: add the Ishvana installation folder and your data folder (C:\Users\<YourName>\AppData\Roaming\Ishvana\) to your antivirus exclusion list. Exact steps vary by product — search for “add exclusion” in your AV’s settings.

Engine dispatch failed

Four things to check:

1. Is the backend running? The desktop app starts FastAPI on port 37737. If it is not running, restart Ishvana.
2. Did a handler fail? Open Analysis → Etherforce Observability and inspect the latest dispatch error.
3. Is indexing still running? Large imports can keep background workers busy. Wait for the status bar to clear, then retry.
4. Check the logs. If the same handler fails twice, the error is a bug worth reporting with the dispatch ID and log entry.

Performance

Minimum vs recommended specs

	Minimum	Recommended
CPU	6-core / 12-thread	8-core / 16-thread or better
RAM	16 GB	32 GB or more
GPU	Nvidia 8 GB VRAM	Nvidia 12 GB+ VRAM
Storage	HDD works, SSD recommended	NVMe SSD
Display	1920x1080	2560x1440 or higher

Ishvana can run without a supported GPU, but local embedding, contradiction, and deep-analysis work will be slower on CPU.

Do I need an SSD?

Strongly recommended. Ishvana reads and writes project files, SQLite databases, and ChromaDB vector indexes frequently. On an SSD those operations are effectively instant; on a spinning drive you’ll notice brief delays every time you open a project, search lore, or switch documents. A cheap SATA SSD is enough — you don’t need NVMe, though NVMe is better.

How does Ishvana handle large projects?

Large, complex projects are the target use case — that’s the whole point. Hundreds of Legendry entries, dozens of documents, deep character webs, sprawling plot structures, multi-book series. SQLite handles structured data, ChromaDB handles the semantic search vectors, and documents are individual .docx files on disk. The architecture avoids loading everything into memory at once, so projects scale into the thousands of entries without becoming unusable.

What is ChromaDB indexing?

ChromaDB is the vector database Ishvana uses for semantic search — it’s what lets the agents find relevant lore, characters, and world details by meaning instead of keyword matching. When you add or import content, ChromaDB embeds and indexes it in the background. Big imports take a minute or two. Normal use is instant. If you ever see the status bar mentioning indexing, that’s ChromaDB catching up.

What’s next

Installation System requirements, download, and first-run walkthrough.

Settings Configure local engine behavior, editor behavior, and license activation.

Keyboard Shortcuts The keyboard shortcuts worth learning.