Before You Start

You'll need at least one thing: an account with an AI provider and an API key from that provider (or a local installation of Ollama if you want to run models on your own hardware). If you don't have one yet, the Choosing a Provider section below will help you decide.

All AI connection settings live inside The Foundry, Quilltap's central configuration hub. You'll find it by clicking the Foundry icon in the left sidebar footer.

The Setup Flow

Here's the sequence for getting up and running:

1. 1.

   Add an API key — Store your provider credentials in The Foundry

2. 2.

   Create a connection profile — Link that key to a provider and model

3. 3.

   Start chatting — Select the profile when you open a new chat

Two optional but recommended steps:

4. 4.

   Set up embeddings — Enable semantic memory search (The Commonplace Book)

5. 5.

   Configure a Cheap LLM — Designate a lightweight model for background tasks (The Salon)

Step 1: Add Your API Key

API keys are stored and managed in The Foundry (/foundry/forge), under the API Keys section.

Adding a Key

1. 1.

   Navigate to The Foundry.

2. 2.

   Expand the API Keys section.

3. 3.

   Click Add API Key.

4. 4.

   Select your Provider from the dropdown (OpenAI, Anthropic, Google, OpenRouter, Grok, NanoGPT, DeepSeek, Z.AI, Ollama, OpenAI-Compatible, etc.).

5. 5.

   Enter a Label — a memorable name like "My OpenRouter Key" or "Work OpenAI Account."

6. 6.

   Paste your API Key from the provider's website.

7. 7.

   Click Save.

Testing a Key

After saving, click Test Key next to the entry. Quilltap sends a verification request to the provider and reports whether the key is valid, invalid, or encountered an error. Always test before building a connection profile on top of it.

Managing Multiple Keys

You can store multiple keys from the same provider. This is useful when you have separate accounts for personal and work use, when rotating keys, or when you want to isolate testing from production. Each connection profile you create later will select which specific key to use.

Importing and Exporting Keys

The Foundry supports exporting all your API keys as a JSON file for backup, and importing them back later. The exported file contains sensitive credentials — treat it like a password file and store it securely.

Step 2: Create a Connection Profile

Connection profiles live in The Foundry (/foundry/forge) alongside your API keys. A profile ties together a provider, an API key, a model, and optional tuning parameters into a named configuration you can select when starting chats.

Creating a Profile

1. 1.

   In The Foundry, find the Connection Profiles section.

2. 2.

   Click Add Connection Profile.

3. 3.

   Fill in the form:

   • • Profile Name — Something descriptive like "Claude Sonnet," "GPT-4o Fast," or "Local Llama."
   • • Provider — Must match the provider of the API key you'll select.
   • • API Key — Choose from your stored keys.
   • • Model — Select from the provider's available models (use Fetch Models if the list is empty).
   • • Base URL — Only needed for self-hosted or OpenAI-compatible endpoints.
4. 4.

   Optionally adjust advanced settings:

   • • Temperature — Controls randomness. Lower values (0–0.3) produce more consistent output; higher values (0.7–1.0+) produce more creative, varied responses.
   • • Max Tokens — Caps the response length. Sent to the provider on every turn, so a generous figure here is a generous figure on the wire.
   • • Top P — An alternative to temperature for controlling output diversity. Also sent on every turn.
   • • Max Context — The size of the model's window, and the figure the context budget works from. Quilltap recognises the well-known model names and knows their windows; for anything it doesn't — a custom hf.co/… Ollama tag, an endpoint of your own — this field is the only thing standing between you and a conservative default that would trim your conversation on every turn.
   • • Announce the speaker in multi-character scenes ([Name] prefill) — A per-profile checkbox. In a multi-character chat, each reply is anchored to the character whose turn it is, either by prefilling an assistant message with [Character Name] or by a prose instruction in the system prompt. Leave it off for a profile that runs a thinking turn: a thinking model rejects a prefilled assistant turn outright or swallows its own reasoning trying to honour it.
   • • Provider options — A panel of settings particular to the provider (Ollama's Request Timeout, NanoGPT's Reasoning Effort, and so on). Clearing a numeric option leaves it clear: an empty box shows the default behind it in grey, and blank round-trips as blank rather than quietly becoming a value you chose.
5. 5.

   Click Save.

6. 6.

   Click Test Connection to verify everything works end-to-end.

Setting a Default Profile

One profile can be marked as the default, which pre-selects it whenever you create a new chat. You can always override the default on a per-chat basis.

Using Profiles in Chats

When you start a new chat, the connection profile dropdown lets you pick which AI model to use. You can also switch profiles mid-conversation — the change applies to future messages without affecting previous ones.

Profile Health

The profiles list shows connection health at a glance: ✓ Healthy, ⚠ Degraded, or ✗ Unhealthy. If a profile shows as unhealthy, test the connection and verify the underlying API key is still valid and funded.

Tagging Profiles

Connection profiles take tags, the same as characters do, and the Tags section on a profile adds and removes them straight away. Once you have a dozen profiles — cheap ones, thinking ones, ones kept for a particular character — a few tags are a considerable comfort.

Changing a Profile's Provider

Credentials do not follow a profile about. Point an existing profile at a different provider and its API key stays behind — only a key the form could actually show you for the provider now selected is sent. A base URL behaves the same way: it goes out to the providers that take one (Ollama, OpenAI-Compatible) and not to a hosted provider that hides the field. Switch back and your earlier selection is still there.

Naming an Understudy

A call that fails outright — a rejected key, a rate limit, a network error, a model the provider has retired, a 5xx, an empty response, a moderation refusal — used to be the end of the turn. The Fallback section of the profile form now lets a profile name an Understudy: another profile to try in its place, with no intervention from you. The section does not appear on a Courier profile, whose requests are carried by hand and so cannot be stood in for automatically.

Beneath the dropdown is a checkbox permitting one further stand-in, drafted automatically from your other profiles at the same model class or better. Each call is capped at three attempts in all — your profile, your understudy, one tier pick — and chains do not recurse: an understudy's own understudy is never followed, so an A → B, B → A arrangement is legal configuration that simply stops rather than spinning. Nor is there any stickiness. A successful fallback applies to that one call and no other; your next message tries your primary again.

The tier pick is off by default, on the principle that spending money at a provider you did not choose is not a thing to do quietly. Switched on, it excludes Courier profiles, anything with no usable key, and anything below the tier that just failed; it insists on a danger-compatible profile in a dangerous-routed context; and it prefers a different provider over a higher-tier sibling of the one that has just let you down. It is only as well informed as your Model Class fields, which is worth a minute of your time if you intend to switch it on at all.

What to name. The useful understudy is at a different provider, on a different key, running a model you would be content to hear from — a rate limit or an outage tends to take a whole account with it, so a second profile against the same key is a poor understudy. The form warns you if the profile you have chosen has no API key attached yet: it will be skipped until one arrives.

Vision is the one exception. A chain swaps the model but reuses the message array built for your primary, so on a turn carrying an image the raw bytes are already in it, and handing that to a text-only stand-in fails for certain. Both steps therefore require a vision-capable profile when the turn carries images — the named understudy included. Every other choice you made is honoured as you made it; this one is an incompatibility rather than a preference.

The chain is consulted in four places: on a hard error in the Salon, where the failover happens only before the first word of prose has reached you; on an empty response, where it runs third, after the same-profile retry and the uncensored reroute, both of which answer their own cases better; on cheap-LLM tasks, which re-issue against each stand-in with a fresh deadline; and on image description, where the describer's chain runs before the uncensored describer. When a chain is exhausted, the error names every profile that was asked and how each one declined, which is a considerably better thing to read than "request failed."

Attachments and Vision

A profile's Supports image attachments checkbox answers one question only: can the model read pictures? Whether the plugin can put them on the wire is an entirely separate matter, and Quilltap now asks both before handing over an image.

Where a model can see but its plugin cannot send, the request routes to a written description of the picture rather than losing it — and the same check governs which profile may be appointed to write that description, so the describer is never one that couldn't receive the image either. If a plugin does drop an attachment, the Salon says so in a warning rather than letting the model write a confident paragraph about a photograph it was never shown.

Choosing a Provider

Quilltap supports connections to a wide range of AI providers. Here's a guide to help you choose.

Step 3: Set Up Embeddings (Recommended)

Embeddings power Quilltap's semantic memory search — the ability to find memories by meaning rather than exact keyword matches. A search for "cat" will also surface memories mentioning "feline" or "kitten" because embeddings understand conceptual similarity.

Embedding profiles are configured in The Commonplace Book (/foundry/commonplace-book).

Built-in TF-IDF — Zero Configuration

Quilltap includes a built-in embedding system that works without any external service. It's set up automatically on first run. Check The Commonplace Book — if you see a profile named "Built-in TF-IDF" marked as default, you're already covered.

If no profile exists:

1. 1. Click Add Profile.
2. 2. Select BUILTIN as the provider.
3. 3. Name it "Built-in TF-IDF."
4. 4. Click Save and Set as Default.

The built-in system requires no API key, costs nothing, works offline, and is good enough for most use cases. You can always upgrade to an external provider later.

External Embedding Providers

For more sophisticated semantic search, you can use external embedding services:

How Quilltap Uses Embeddings

When embeddings are configured, memory search automatically uses semantic matching. If no embedding profile exists, Quilltap falls back to keyword-based search. You don't need embeddings to use Quilltap — they just make memory retrieval significantly smarter.

One thing to know before you switch providers: since 4.8, Quilltap insists on a single embedding standard. A vector means nothing except against the model that produced it, and a vector of the wrong width is silently passed over by every search — so an instance could once carry the greater part of its memory in one geometry, search it in another, and be told nothing whatsoever. Choosing a new default embedding profile now invalidates and re-embeds, and every startup measures the stored vectors against the standard of the day and mends what it can reach. On an instance that has changed embedding providers at some point without re-embedding, expect the first boot after upgrading to be busy, and to cost somewhere between a few cents and a few dollars once. Instances on the built-in embedder are unaffected.

Quilltap's own help documents are embedded too, and as of 4.9 they are embedded twice over: once whole, and once section by section. A 700-line page spanning a dozen subsystems makes a single vector that matches no particular question strongly, so a search now scores the sections as well and answers with the section that actually matched. This gives the first boot after upgrading a little extra to do — already-synced documents are sliced and their sections embedded. On a real instance that came to 588 chunks across 120 documents, finished inside a minute.

Step 4: Configure the Cheap LLM (Recommended)

Many of Quilltap's background features — memory extraction, context compression, chat title generation, prompt expansion for image generation, and housekeeping tasks — need an LLM but don't require your most powerful or expensive model. The Cheap LLM system handles this, and it's configured in The Salon (/foundry/salon).

Why It Matters

Without a Cheap LLM configured, these background tasks either use your main (potentially expensive) model or don't run at all. Setting up a cheap option means your memories get extracted, your conversations get titled, and your image prompts get expanded — all without burning through your premium model's budget.

Setting It Up

1. 1.

   Create a second connection profile in The Foundry with a less expensive model:

   • • OpenAI: gpt-4o-mini is much cheaper than gpt-4o
   • • Anthropic: claude-3-5-haiku is cheaper than claude-3-5-sonnet
   • • OpenRouter: Sort by price to find low-cost models
   • • Ollama: Any local model is effectively free
2. 2.

   Navigate to The Foundry → The Salon.

3. 3.

   Find the Cheap LLM section.

4. 4.

   Toggle Enable Cheap LLM on.

5. 5.

   Select your cheaper profile from the dropdown.

The Cheap LLM section also carries an Allow a Similar-Tier Stand-In switch. Where a background task is served by a connection profile you named, that profile's own understudy takes over when the call fails; where Quilltap picked the model itself — a local pick, or the cheapest thing a provider offers — this switch is what permits it to try a comparable profile rather than give the errand up. See Naming an Understudy for how the chain behaves.

What the Cheap LLM Powers

• • Memory extraction — Pulling key facts from conversations to store as character or user memories.
• • Context compression — Summarizing older parts of a conversation to fit within the model's context window.
• • Chat auto-rename — Generating a title for new conversations.
• • Prompt expansion — Enriching image generation prompts with character and persona details before submitting to the image provider.
• • Housekeeping — Regenerating tags, placeholders, and summaries during maintenance.
• • Dangermouse classification — The content safety gatekeeper uses the Cheap LLM to classify messages (when enabled).
• • Image description — Describing images that appear in chat.

Step 5: Image Generation (Optional)

Quilltap can generate images directly within chats. Image generation profiles are configured separately from chat connections, in The Lantern (/foundry/lantern).

Setting Up Image Generation

1. 1.

   Navigate to The Foundry → The Lantern.

2. 2.

   Click Add Image Profile (or find it under Image Profiles).

3. 3.

   Choose a provider:

   • • Google Gemini — Imagen 4 and Gemini image models
   • • Grok (xAI) — Native image generation
   • • OpenAI — DALL-E models
   • • OpenRouter — Models with image generation support (e.g., Gemini via OpenRouter)
   • • Z.AI — CogView and GLM-Image models
   • • NanoGPT — 200+ image models on the same key as your chats
4. 4.

   Select the appropriate API key and model.

5. 5.

   Configure provider-specific controls (quality, style, safety settings, aspect ratios).

6. 6.

   Save the profile.

Fetching Image Models

The image-profile form has a Fetch Models button, the same as connection profiles do. With a key selected, each plugin genuinely asks its provider what it has, filtered to models that actually produce images — the edit-only and upscale-only entries are left out, as are video, text, and embedding models that happen to share a catalogue.

Without a key, you get the plugin's curated list instead. Either way the form tells you which one you are looking at — the provider's own answer, or Quilltap's built-in catalogue — so a short list is never left to be mistaken for a complete one.

Using Image Generation in Chats

Once configured, you can launch the image generator from any chat. Quilltap can optionally use the Cheap LLM to expand your prompts — injecting character and persona descriptions using placeholders like {{Character}} and {{me}} — before sending them to the image provider.

Settings Cascade

Many Quilltap settings follow a cascade where more specific levels override more general ones:

For example, you might set a default connection profile globally, override it for a specific character who responds better with a different model, and override it again for a particular chat session. Each level inherits from the one above unless explicitly changed. This applies to connection profile selection, agent mode settings, and other per-chat configurations.

Security

Quilltap takes API key security seriously:

• • All API keys are encrypted at rest using AES-256-GCM encryption.
• • Each user has their own encryption key derived from their user ID plus a master pepper (the ENCRYPTION_MASTER_PEPPER environment variable set during deployment).
• • Keys are decrypted only when the authenticated user makes a request that needs them — they're never exposed in logs, API responses, or database queries.
• • API keys are never sent anywhere except to the provider's own API endpoint when making a request on your behalf.
• • The pepper's reach is wider than the API keys alone: it is the encryption key that your instance's .dbkey file wraps. The key file is only the wrapper; the pepper is the thing that opens the databases.

Keep the pepper and you have a way back in from the other direction. If the .dbkey file is lost, or the passphrase that locks it has been forgotten, npx quilltap instances restore-key <name> rebuilds the key file with the server down. The pepper comes from ENCRYPTION_MASTER_PEPPER or a hidden prompt — never a flag, since a command line lands in shell history and in ps — and before writing anything, the command opens every encrypted database in the data directory with the candidate pepper and refuses if any of them declines to open. An existing key file is backed up first.

Troubleshooting