Iron Curtain — Design Documentation

LLM Provider Setup Guide

Settings → LLM → [+ Add Provider]

This page walks players through enabling AI features. Iron Curtain ships with built-in CPU models that work with zero setup — just click [Enable Built-in AI →]. For higher quality, you can connect a cloud provider or a local server like Ollama. All LLM features are optional; the game is fully functional without one.

What You Need

Iron Curtain supports four provider tiers (D047). Pick whichever fits your situation:

All tiers work identically in-game. You can use one for some tasks and another for others (task routing).

Quickest Start: Built-in AI (Zero Setup)

Iron Curtain includes optimized CPU models via Workshop model packs. No accounts, no downloads beyond the model pack, no configuration.

1. Settings → LLM → [Enable Built-in AI →]
2. IC downloads the default model pack (~850 MB)
3. Done — all AI features are active

The built-in models are designed for CPU inference. They provide good results for coaching, mission generation, and AI orchestration while requiring no GPU.

Why upgrade to a cloud or local-GPU provider? Built-in models share your CPU with the game. An external provider (cloud or Ollama with GPU) frees those resources — the game runs smoother, and the AI responds faster with stronger models. Cloud providers may charge per use (typically a few cents per session), but many offer free tiers. See the comparison table above to decide what fits your situation.

Option A: Local Setup with Ollama (Free, Private)

Ollama runs AI models on your own computer. No account needed, no API key, no cost.

Step 1 — Install Ollama

Download from ollama.com and install. It runs as a background service.

Step 2 — Pull a model

Open a terminal and run:

ollama pull llama3.2

This downloads a ~4 GB model. Smaller models (llama3.2:1b, ~1.3 GB) work too but give lower quality strategic advice. Larger models (llama3.1:70b) give better advice but require more RAM/VRAM.

Step 3 — Verify Ollama is running

ollama list

If you see your model listed, Ollama is ready.

Step 4 — Add in Iron Curtain

1. Open Settings → LLM → [+ Add Provider]
2. Select Ollama from the provider type dropdown
3. Endpoint: http://localhost:11434 (default, pre-filled)
4. Model: type the model name (e.g., llama3.2)
5. Click [Test Connection]
6. If the test passes, click [Save]

┌──────────────────────────────────────────────────────────┐
│  ADD LLM PROVIDER                              [Cancel]   │
│                                                           │
│  Provider Type:  [Ollama           ▾]                     │
│  Name:           [My Local Ollama    ]                    │
│  Endpoint:       [http://localhost:11434]                  │
│  Model:          [llama3.2           ]                    │
│  API Key:        (not needed for Ollama)                  │
│                                                           │
│  [Test Connection]                                        │
│                                                           │
│  ✓ Connected — llama3.2 loaded, 340ms latency             │
│                                                           │
│  [Save Provider]                                          │
└──────────────────────────────────────────────────────────┘

No API key needed. No account needed. Everything stays on your machine.

Option B: OpenAI (ChatGPT) Setup

Uses OpenAI’s cloud API. Requires an account and API key. Pay-per-use (typically a few cents per game session with the orchestrator AI).

Step 1 — Get an API key

1. Go to platform.openai.com
2. Create an account (or sign in)
3. Navigate to API Keys → [+ Create new secret key]
4. Copy the key (starts with sk-...)
5. Add credit to your account (Settings → Billing — minimum $5)

Step 2 — Add in Iron Curtain

1. Open Settings → LLM → [+ Add Provider]
2. Select OpenAI from the provider type dropdown
3. Endpoint: https://api.openai.com/v1 (default, pre-filled)
4. Model: gpt-4o-mini (recommended — cheapest good model) or gpt-4o (best quality, ~10x cost)
5. API Key: paste your sk-... key
6. Click [Test Connection]
7. If the test passes, click [Save]

┌──────────────────────────────────────────────────────────┐
│  ADD LLM PROVIDER                              [Cancel]   │
│                                                           │
│  Provider Type:  [OpenAI           ▾]                     │
│  Name:           [My OpenAI          ]                    │
│  Endpoint:       [https://api.openai.com/v1]              │
│  Model:          [gpt-4o-mini        ]                    │
│  API Key:        [sk-••••••••••••••••] [Show]             │
│                                                           │
│  [Test Connection]                                        │
│                                                           │
│  ✓ Connected — gpt-4o-mini, 280ms latency, ~$0.01/consult│
│                                                           │
│  [Save Provider]                                          │
└──────────────────────────────────────────────────────────┘

Approximate cost per game session (10 orchestrator consultations): $0.05–$0.50 depending on model.

Your API key is encrypted on your machine (OS credential manager) and never shared — not in exports, not in replays, not in Workshop configs.

Option C: Anthropic Claude Setup

Uses Anthropic’s cloud API. Same pattern as OpenAI — account, API key, pay-per-use.

Step 1 — Get an API key

1. Go to console.anthropic.com
2. Create an account (or sign in)
3. Navigate to API Keys → [Create Key]
4. Copy the key (starts with sk-ant-...)
5. Add credit (Settings → Billing)

Step 2 — Add in Iron Curtain

1. Open Settings → LLM → [+ Add Provider]
2. Select Anthropic from the provider type dropdown
3. Model: claude-sonnet-4-20250514 (recommended) or claude-haiku-4-5-20251001 (cheaper, faster)
4. API Key: paste your sk-ant-... key
5. Click [Test Connection]
6. If the test passes, click [Save]

Option D: Google Gemini Setup

Google Gemini exposes an OpenAI-compatible API. Free tier available.

Step 1 — Get an API key

1. Go to aistudio.google.com
2. Sign in with a Google account
3. Click “Get API key” → “Create API key”
4. Copy the key

Step 2 — Add in Iron Curtain

1. Open Settings → LLM → [+ Add Provider]
2. Select OpenAI Compatible from the provider type dropdown
3. Endpoint: https://generativelanguage.googleapis.com/v1beta/openai
4. Model: gemini-2.0-flash (free tier, fast) or gemini-2.5-pro (paid, best quality)
5. API Key: paste your Google AI key
6. Click [Test Connection]

Option E: Other OpenAI-Compatible Services

Many services use the same API format as OpenAI. Use OpenAI Compatible provider type with these settings:

Get an API key from the service’s website, then add as OpenAI Compatible in Iron Curtain.

Task Routing — Use Different Providers for Different Tasks

After adding one or more providers, you can assign them to specific tasks:

┌──────────────────────────────────────────────────────┐
│  TASK ROUTING                                         │
│                                                       │
│  Task                    Provider                     │
│  ──────────────────────  ────────────────────────     │
│  AI Orchestrator         [My Local Ollama      ▾]     │
│  Mission Generation      [My OpenAI            ▾]     │
│  Campaign Briefings      [My OpenAI            ▾]     │
│  Post-Match Coaching     [My Local Ollama      ▾]     │
│  Asset Generation        [My OpenAI            ▾]     │
│                                                       │
│  [Save Routing]                                       │
└──────────────────────────────────────────────────────┘

Recommended routing for players with both local and cloud:

Community Configs — Skip the Setup

Don’t want to configure everything yourself? Browse community-tested configurations:

1. Settings → LLM → [Advanced →] → Browse Community Configs
2. Browse by tag: local-only, budget, high-quality, fast
3. Click [Import] on a config you like
4. The config pre-fills provider settings and task routing — you only need to add your own API keys

Community configs never include API keys. They share everything else: endpoint URLs, model names, prompt profiles, and task routing.

Troubleshooting

Credential Recovery

If you see an “AI features need your attention” banner, or a provider card shows a ⚠ badge in Settings → LLM, it means IC can’t read the saved login for one or more AI providers. This typically happens when:

• You moved to a new computer (your login was protected by your old machine’s system keychain)
• You reinstalled your operating system (the OS keychain was reset)
• You cleared your system keychain (Windows Credential Manager, macOS Keychain, Linux Secret Service)
• You forgot your vault passphrase (if you were using passphrase-based protection)

Your provider settings are safe — name, endpoint, model, and task routing are all intact. Only the login (API key or sign-in token) needs to be re-entered.

To fix:

1. Click [Fix Now →] in the banner, or go to Settings → LLM
2. Providers that need attention show a ⚠ badge and a [Sign In] button
3. Click [Sign In] → the edit form opens with all your settings preserved
4. Paste your API key (from your provider’s dashboard) or click Sign In to redo the login flow
5. Click [Save] — the new login is encrypted with your current machine’s key

If you don’t want to fix it right now: Click [Use Built-in AI] to fall back to built-in models for this session, or [Not Now] to dismiss the banner. Features that need the affected provider will show a guidance panel with options to fix, switch to built-in, or cancel.

If you forgot your vault passphrase: Go to Settings → Data → Security → [Reset Vault Passphrase]. This clears all saved logins and lets you set a new passphrase. You’ll need to sign in to your AI providers again afterward. (Power users: /vault reset in the console does the same thing.)

This is by design: IC stores your logins encrypted, and the encryption key doesn’t travel with your data files. A stolen backup or copied database can’t expose your API keys. The trade-off is re-entering logins when the encryption key is unavailable.

Related Docs

• LLM Manager UI: decisions/09f/D047-llm-config.md
• LLM-Enhanced AI: decisions/09d/D044-llm-ai.md
• LLM Missions: decisions/09f/D016-llm-missions.md
• Skill Library: decisions/09f/D057-llm-skill-library.md
• Implementation spec: research/byollm-implementation-spec.md