Frequently Asked Questions

What LLM providers are supported?

LoreForge supports three LLM providers:

• Ollama — Run models locally on your own hardware. This is the default for self-hosted installations. Recommended models: qwen2.5:14b (creative writing) and qwen2.5:7b (utility tasks). Any Ollama-compatible model works.
• Anthropic — Claude models via the Anthropic API. Default models: claude-sonnet-4-6 (writer) and claude-haiku-4-5-20251001 (utility). Requires an API key.
• OpenAI — GPT models via the OpenAI API. Default models: gpt-4o (writer) and gpt-4o-mini (utility). Requires an API key.

You can switch providers at any time through the Settings page in the web app without restarting the server.

Can I use my own API key?

Yes. LoreForge supports Bring Your Own Key (BYOK) for both Anthropic and OpenAI. Enter your API key in the Settings page or in your .env file. BYOK users get unlimited AI generations with no monthly cap — you pay only for the tokens you use through your provider.

On the cloud version, BYOK is available on any plan, including the free tier.

Can I use a different Ollama model?

Yes. LoreForge works with any model available in your Ollama installation. Change the WRITER_MODEL and UTILITY_MODEL settings to any model name that Ollama supports. Visit ollama.ai/library to browse available models.

For the best results, use a model with at least 7B parameters for utility tasks and 14B+ for creative writing. Smaller models work but may produce lower-quality output.

What GPU do I need for local Ollama?

It depends on the model size:

• qwen2.5:7b — 5 GB VRAM minimum (runs on most modern GPUs)
• qwen2.5:14b — 10 GB VRAM minimum (RTX 3060 12GB, RTX 3080, RTX 4070 or better)
• Larger models (30B+) — 24 GB+ VRAM (RTX 3090, RTX 4090, A100)

Ollama can also run on CPU-only machines, but expect significantly slower response times.

Is my data private?

Self-hosted: Completely private. Your data stays on your machine. If you use Ollama, even the AI processing happens locally — nothing leaves your network.

Cloud (loreforge.co): Your entries and world data are stored in our PostgreSQL database. AI generations are processed through Anthropic or OpenAI APIs, which means entry content is sent to those providers when you use AI actions. We do not sell or share your data. Refer to our privacy policy for full details.

BYOK with Ollama: If you use your own Ollama instance (even with the cloud frontend), AI processing happens on your hardware. Only entry CRUD goes through our server; AI content stays on your machine.

How do I back up my data?

Multiple options:

• In-app JSON export — The easiest method. Go to your world settings and click Export. This downloads a complete JSON file with all entries, edges, settings, and metadata.
• SQLite file copy — For self-hosted: docker cp loreforge-api:/workspace/data/loreforge.db ./backup.db
• PostgreSQL dump — For cloud/PostgreSQL: pg_dump -U loreforge loreforge > backup.sql
• Uploaded files — Map images and entry images are stored separately in /workspace/uploads/. Back these up with docker cp.

See the Self-Hosting Guide for detailed backup instructions.

Can I delete my account and all data?

Yes. On the cloud version, go to Settings and request account deletion. LoreForge runs GDPR-compliant cleanup that purges expired accounts and hard-deletes old soft-deleted entries automatically. Self-hosted users have full control over their data — delete the Docker volume or database file to remove everything.

What is the difference between Free, Writer, and Studio?

New accounts get a 14-day free trial with full Writer-level access.

What happens when my trial expires?

Your account drops to the Free tier. All your worlds, entries, and data remain intact — nothing is deleted. You can still read, edit, and export your content. AI generation is limited to 50 per month until you subscribe or add your own API key (BYOK).

Is self-hosted LoreForge free?

Yes. Self-hosted LoreForge is fully functional with no restrictions. All features work out of the box. An optional license key unlocks Pro-level features and priority support, but is not required.

Can I migrate from World Anvil?

Yes. Export your data from World Anvil, then use POST /import/world-anvil or the Import button in the web app. LoreForge will map World Anvil article types to LoreForge entry types and preserve as much structure as possible.

Can I migrate from Campfire?

There is no direct Campfire importer yet, but you can export your Campfire data and import it as a ZIP of Markdown files using the generic ZIP importer. Each Markdown file becomes an entry. You may need to manually set entry types and create edges after import.

Can I migrate from Notion?

Yes. Export your Notion workspace as Markdown + CSV, then use the Notion importer (POST /import/notion). Pages become entries, and LoreForge attempts to detect entry types from page properties.

Can I move between cloud and self-hosted?

Yes. Use the JSON export from either version and import it into the other. The JSON format is identical between cloud and self-hosted installations.

How do I reset my password?

Cloud: Go to the login page and click “Forgot password?” Enter your email and you will receive a reset link. Alternatively, use the API: POST /auth/forgot-password with your email, then POST /auth/reset-password with the token from the email.

Self-hosted: If auth is enabled and you've lost your password, you can reset it directly in the database or delete and recreate your account. For SQLite: sqlite3 loreforge.db "DELETE FROM users WHERE email='your@email.com'"

Can I use LoreForge without creating an account?

Self-hosted: Yes. By default, self-hosted LoreForge has no authentication. Just open the app and start building.

Cloud: No. Cloud requires an account to isolate your data from other users.

What databases are supported?

SQLite (default for self-hosted) and PostgreSQL (used by the cloud version and recommended for multi-user self-hosted deployments). The DATABASE_URL environment variable controls which database is used. Both use async SQLAlchemy 2.0.

Can I run LoreForge without Docker?

Yes, though Docker is the recommended approach. To run natively:

1. Backend: cd services/api && pip install -r requirements.txt && uvicorn app.main:app --port 8250
2. Frontend: cd apps/web && pnpm install && pnpm dev

Requires Python 3.11+ and Node.js 18+.

How do I access LoreForge from other devices on my network?

Set HOST_IP in your .env to your machine's LAN IP (e.g., 192.168.1.100) and update NEXT_PUBLIC_API_URL accordingly. Then access LoreForge at http://192.168.1.100:3500 from any device on your network.

On Windows, use 127.0.0.1 instead of localhost in URLs, as Windows may resolve localhost to IPv6.

Why do AI actions return errors?

Common causes:

• Ollama not running — Check that Ollama is started and the URL in settings is correct.
• Model not pulled — Run ollama pull <model-name> to download the model.
• Invalid API key — Verify your Anthropic or OpenAI key in Settings.
• Database config override — Settings in the database (changed via the Settings UI) override .env values. Check GET /app-config to see the active configuration.
• Quota exceeded — Free tier users are limited to 50 generations/month. Upgrade or add your own API key.

How do I view the API documentation interactively?

Visit http://localhost:8250/docs for Swagger UI or http://localhost:8250/redoc for ReDoc. Both provide interactive documentation generated from the API's OpenAPI schema, with request/response models and a “Try it out” feature.

What is the wiki-link syntax?

Use double brackets to reference other entries: [[Entry Name]]. The editor provides autocomplete suggestions as you type. In the Markdown preview, wiki-links become clickable with hover preview cards showing entry details.

What are the entry type colors?

Each entry type has a distinctive color used in the graph view and badges:

• Character, Location, Event, Item, Faction, Lore, Magic, Species, Culture, Language, Religion

Colors are defined in src/lib/constants.ts and used consistently across the graph, whiteboard, and sidebar.