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. Nothing is sent anywhere unless you explicitly point an agent at a cloud model provider for inference, and even then, only the prompts for that specific request get sent. 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.

Model setup

Which model provider should I use?

Three options, and all three work. The right one depends on what you care about.

	Ollama (local)	Anthropic (Claude)	OpenRouter
Cost	Free after setup	Pay per token	Pay per token
Privacy	100% local	Prompts sent to Anthropic	Prompts sent to OpenRouter
Speed	Depends on your GPU	Fast and consistent	Varies by model
Quality	Good with 13B+ models	Excellent for creative writing	Varies
Setup	Install Ollama, pull a model	Paste in an API key	Paste in an API key
Hardware	Nvidia 8 GB VRAM minimum	No GPU needed	No GPU needed

Start with Anthropic

If you want the best creative writing quality with the least setup hassle, start with Anthropic. Claude is consistently the strongest model for creative prose and the setup is “paste an API key.” Switch to Ollama later if you want zero ongoing cost and you have the GPU to run it. OpenRouter is the right answer if you want to experiment across multiple models — GPT-4, Mistral, Llama, Claude, all through one API.

Can I use multiple providers?

Yes. You can configure all three and point different agents at different providers in Settings. The usual pattern is Claude for the main creative writing work and Ollama for everything else — analysis, consistency checking, background processing — where local inference is cheap enough to run without thinking about it.

What models work best for creative writing?

For cloud providers, Claude beats everything else for creative prose. This isn’t a marketing claim — there’s a blog post in the works about the benchmark data showing coder-oriented models actually outperform “creative” models at creative writing, and Claude is the strongest of them. For local models via Ollama, look for anything with 13B parameters or more. Smaller models produce recognizably weaker prose.

How much does inference cost?

With Ollama it’s free — you’re using your own hardware. With Anthropic or OpenRouter, you pay per token. A typical creative writing session — generating scenes, asking for feedback, running lore queries — runs somewhere between $0.50 and $3.00 per hour of active use, depending on which model you picked and how heavily you’re leaning on generation. Monitor usage in your provider’s dashboard. Ishvana also tracks it per-agent in Etherforce’s observability panel so you can see exactly where your money is going.

Do I need a GPU?

Only if you want to run models locally via Ollama. The minimum is an Nvidia GPU with 8 GB VRAM, and more is better. If you’re using Anthropic or OpenRouter inference runs on their servers and your machine doesn’t need a GPU at all.

How do I set up Ollama?

1. Download Ollama for Windows from ollama.ai.
2. Install it. Ollama runs as a background service on http://localhost:11434 once installed.
3. Pull a model. Open a terminal — the one time this page will ask you to touch a terminal — and run ollama pull llama3 or whichever model you prefer.
4. In Ishvana, go to Settings → Models, select Ollama as the provider, and pick your downloaded model from the list.

Ishvana auto-detects Ollama when it’s running locally, so if you start it up before opening Ishvana, the provider should already show as available.

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. The editor, the outline, the Legendry, the plot studio, timelines, maps, documents, and publishing all work without any model provider configured. The agent features — chat, prose generation, lore analysis, style feedback — need a provider, but the core writing and worldbuilding tools do not. If you want to use Ishvana as a pure writing tool and skip the agents entirely, you can, though you’d be leaving most of what makes it interesting on the table.

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

Depends on which provider you’re using:

• Ollama (local). Speed is entirely your GPU. Smaller models are faster, larger models are slower but better. Check that Ollama is using your GPU and not silently falling back to CPU — run ollama ps in a terminal. If the model is running on CPU, you’ll see it in the output, and the fix is updating your Nvidia drivers or checking that Ollama’s CUDA runtime is properly installed.
• Cloud providers. Slow responses almost always mean high load on the provider’s side, not a problem with Ishvana. Check the provider’s status page. If it’s consistently slow, switch to a different model or provider for the duration.
• 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.

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.

Ollama connection failed

Four things to check:

1. Is Ollama running? ollama list in a terminal tells you. If it responds with your installed models, Ollama is running. If it errors, start it.
2. Is the URL right? Ishvana expects Ollama at http://localhost:11434. If you changed Ollama’s port or host, update it in Settings → Models.
3. Firewall. Some firewalls block localhost connections by default. Add an exception for Ollama on port 11434.
4. Restart Ollama. Every now and then the Ollama service hangs. Restart it and try again.

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 (for Ollama)	Nvidia 12 GB+ VRAM
Storage	HDD works, SSD recommended	NVMe SSD
Display	1920x1080	2560x1440 or higher

If you’re using a cloud provider and skipping Ollama, the GPU requirement doesn’t apply — you don’t need one at all.

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 model providers, editor behavior, and license activation.

Keyboard Shortcuts The keyboard shortcuts worth learning.