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 Forge

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 Forge (/foundry/forge), under the API Keys section.

Adding a Key

1. 1.

   Navigate to The Foundry → The Forge.

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, Ollama, 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 Forge 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 Forge (/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 → The Forge, 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.
   • • Top P — An alternative to temperature for controlling output diversity.
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.

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.

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 Forge 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.

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)
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.

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.

Troubleshooting