The Foundry
the engine room — where the power is generated
Beneath the floorboards of the Estate, past the polished brass pipes and the hum of the dynamos, there is a workshop. The air smells of machine oil and solder. The floor is concrete, scored with boot prints. The man who works here wears a heavy leather apron over rolled sleeves, has biceps roughly the circumference of your head, and speaks with the cadence of someone who is entirely certain of what he is saying and mildly surprised that you needed to be told.
The Foundryman built the Estate. Not the characters, not the conversations, not the themes—those belong to their respective artisans. He built the infrastructure: the plugin system that delivers every provider, every theme, and every tool; the database that stores everything; the runtime modes that let Quilltap run on your desktop, in a container, or inside a virtual machine; the API that connects the frontend to the backend; the build pipeline that produces installers for three operating systems. He built all of it, sometimes with the help of his favorite subcontractor—a Frenchman named Claude, whose poetic little construction company pours the concrete and installs the locks while the Foundryman draws the blueprints.
He is not here because of the conversations upstairs. He is here because the Estate gives him an outlet to build amazing things. That the things he builds happen to enable fiction, companionship, and research is a pleasant side effect. The machinery is the point.
The Plugin Architecture
everything is a plugin
Quilltap was not designed with a plugin system bolted on afterward. The plugin system is the delivery mechanism. Every LLM provider, every theme, every authentication method, every upgrade migration, every tool, every roleplay template, and every system prompt arrives as a plugin. There are no hardcoded provider lists, no conditional imports based on which service you happen to use. Adding or removing a capability means adding or removing a plugin.
Plugin Types
Seven capability types: LLM providers (chat, image generation, and embeddings), themes, roleplay templates, tools, storage backends, search providers, and system prompts. Plugins register their capabilities through a central registry that the rest of the application queries at runtime. No startup-time capability detection, no stale caches—the registry reflects what is actually installed, right now.
Installation & Updates
Plugins install from npm, with a browser in Settings for
discovering qtap-plugin-* packages. Auto-upgrade
at startup handles non-breaking updates; breaking changes are
logged, displayed in an “Upgrades” tab, and require
confirmation. Plugin metadata includes repository, changelog,
and npm links. Docker volume configuration persists plugins
across container rebuilds.
The SDK
Three npm packages support standalone plugin development:
@quilltap/plugin-types for TypeScript types,
@quilltap/plugin-utils for runtime utilities
(tool call parsers, logger bridge,
OpenAICompatibleProvider base class), and
@quilltap/theme-storybook for theme development
with live preview. No access to Quilltap source code required.
Provider Plugins
Bundled plugins for Anthropic (Claude), OpenAI (GPT, DALL·E), Google (Gemini, Imagen), Grok (xAI), OpenRouter, and Ollama—each self-contained with its own SDK dependencies, streaming implementation, tool call handling, and model discovery. Connection profiles carry provider-specific configuration, model selection, and capability flags.
Runtime Modes
four ways to run the machinery
The Foundryman does not believe in telling people how to run their own equipment. Quilltap offers four runtime modes, each suited to different needs and levels of isolation.
Direct Mode
The recommended default. Electron runs the Next.js backend using its own bundled Node.js—no user-installed runtime required. Fastest startup, simplest experience. Ideal for conversation, companionship, creative writing, and any use case that does not involve giving an LLM a terminal.
Docker Mode
Available on all platforms. The same container image that
powers standalone server deployments, managed by Electron
with transparent host port forwarding via socat
so Ollama, LM Studio, and MCP servers remain reachable at
localhost. A single docker run command or the
platform-aware startup scripts handle everything.
VM Mode
Full isolation. Lima with Apple’s Virtualization.framework on macOS, WSL2 on Windows. A genuine sandbox where AI-generated code runs in a contained environment with no access to your host system beyond explicitly shared files. The Foundryman’s preferred arrangement for shell interactivity.
npx quilltap
A lightweight CLI (~10 KB) that downloads pre-built standalone output from GitHub Releases on first run, cached per-version with a progress bar and retry with exponential backoff. For users who prefer the command line and already have Node.js 22 installed. No Electron, no container, no VM—just the server on localhost.
Port conflicts between modes are handled automatically: starting
one mode stops the other. The active runtime is displayed in the
application footer alongside the data directory path. Localhost URL
rewriting transparently routes localhost and
127.0.0.1 URLs to the host gateway IP in Docker,
Lima, and WSL2 environments, so provider connections and MCP
servers work without manual network configuration.
The Database
SQLite, encrypted, bulletproof
Quilltap runs on SQLite exclusively. No MongoDB, no PostgreSQL, no external database container. Your entire data store is a file in your data directory, encrypted at rest with SQLCipher (AES-256), and hardened with the quiet thoroughness of someone who has already lost data once and has no intention of doing it again.
Encryption
Every database file is encrypted on disk. The standard
sqlite3 tool cannot read them. A unique
.dbkey file is generated on first installation.
Optional locked mode adds a passphrase processed through
600,000 iterations of PBKDF2 before it touches the key.
Saquel Ytzama tends the details; the Foundryman built the
vault she works in.
Integrity
WAL mode for concurrent access. Integrity checks on startup.
Periodic WAL checkpoints every five minutes.
synchronous = FULL for durable writes. Physical
backups with tiered retention: daily for seven days, weekly
for four weeks, monthly for twelve months, yearly forever.
Crash-loop protection in Electron engages safe mode after
three consecutive failures.
Instance Locking
A lock file tracks which process owns the database with PID verification, hostname tracking, and a sixty-second heartbeat. Two processes cannot open the same database. A version guard prevents older versions from touching a database that a newer version has modified. These features exist because something broke. The Foundryman promised “never again,” and he meant it.
LLM Logs
LLM call logs live in their own dedicated database, separate from chats and characters. They accumulate rapidly and write constantly, so isolating them means corruption in the logs can never threaten your actual data. Both databases have independent WAL protection, physical backups, and retention policies.
Your Data, Your Directory
one folder, fully portable
All of Quilltap’s data—database, files, logs, everything—resides in a single directory on your machine. The Electron app lets you manage multiple named data directories from its splash screen, switching between them with a stop-and-start of the runtime. Each directory is self-contained: back it up by copying a folder, migrate it by moving one.
Platform-specific defaults follow OS conventions:
~/Library/Application Support/Quilltap on macOS,
%APPDATA%\Quilltap on Windows,
~/.quilltap on Linux, and /app/quilltap
in Docker (mounted from host). A
QUILLTAP_DATA_DIR environment variable overrides all
of them.
Files are stored on disk as themselves—real directories, original filenames, no hashed artifacts, no sidecar metadata files. A filesystem watcher detects changes in real time. Backup archives capture everything in a single ZIP, including plugin configurations and npm-installed plugins. The Foundryman believes your data should be legible, portable, and yours.
The Build Pipeline
from source to six platforms
The release workflow, triggered on version tags, builds everything in parallel: rootfs tarballs for amd64 and arm64, Electron installers for macOS (DMG), Windows (NSIS), and Linux (AppImage and .deb), Docker images for both architectures, and standalone server tarballs. A final job creates the GitHub Release with all assets attached and triggers the website to rebuild itself.
Code Signing
Azure Trusted Signing for Windows. App Store Connect API key for macOS notarization. Supply chain attestations (SLSA provenance and SBOM) on every release build. The Concierge occasionally has to make a trip to Redmond when the papers expire.
Image Optimization
All PNGs and JPGs converted to WebP, SVGs optimized with SVGO.
Total image payload reduced from ~75 MB to ~4.6 MB—a 94%
savings. Plugin node_modules stripped from Docker
images, saving ~350 MB per architecture.
Docker Hardening
Build tools excluded from production stage. Alpine security
patches on every build. Common LLM shell agent tools (git,
curl, wget, jq) pre-installed. Images at
foundry9/quilltap on Docker Hub.
The API
clean, versioned, consistent
All API access goes through /api/v1/ endpoints with an
action dispatch pattern (?action=). Consistent response
formats, centralized middleware, and Zod schema validation throughout.
The API is the contract between the frontend and the backend—every
feature, from chat streaming to plugin management to file operations,
passes through it.
The cheap LLM system orchestrates background work: memory extraction, context compression, chat titling, scene state tracking, danger classification, and housekeeping tasks, each routed to the lowest-cost provider path with live and fallback pricing data. Connection profiles carry capability flags, model metadata, and per-profile usage tracking (tokens, messages, estimated cost). Provider models are cached in the database and refreshed from provider APIs, so the model list is always current.
Open Source
the blueprints are on the table
Quilltap is open source. The repository lives at github.com/foundry-9/quilltap. The plugin SDK is published to npm. The theme development kit includes a Storybook preset. The API is documented. The help files ship with every installation. The Foundryman does not build things to keep them to himself—he builds things because building things is what he does, and open blueprints mean other people can build on top of them.
There is no Quilltap cloud, no analytics telemetry, no training pipeline consuming your conversations. This is not a philosophical stance masquerading as a feature. It is the architecture itself. The Foundryman built a machine that runs on your machine, stores its data on your machine, and connects to the providers you choose. Everything else follows from that decision.
What He Built
the short version
A plugin system that delivers everything. Every provider, theme, tool, template, and system prompt is a plugin. No hardcoded lists, no conditional imports. Adding a capability means installing a plugin. Removing one means uninstalling it. The application is its plugins.
Four runtime modes, one codebase.
Direct mode for simplicity. Docker for containers. VM for full
isolation. npx for the command line. The same
Next.js backend runs in all of them. The same data directory
works with all of them. The Foundryman does not care how you
run the machinery, as long as it runs.
An encrypted, hardened database. SQLite with SQLCipher encryption, WAL mode, integrity checks, physical backups with tiered retention, instance locking, and version guards. The Foundryman has already experienced what happens when the database fails. He responded by making it very difficult for that to happen again.
A build pipeline that ships to six platforms. macOS, Windows, Linux, Docker (amd64 and arm64), and npm. Code signing, notarization, supply chain attestations, image optimization, and automated releases. One tag, one pipeline, every artifact.
Open blueprints. Open source, published SDK, documented API, no telemetry, no cloud dependency. The Foundryman builds things because building things is what he does. He does not build them to keep them.
Meet the Staff
they've been expecting you
Prospero
The Major-Domo
Architect and overseer of the Estate. Projects, agents, tools, file management, and the governance that keeps the whole operation running with quiet authority.
Learn more →Aurora
The Dressing Room
Character creation and identity management. Structured personalities, physical presence, multi-character orchestration, and the reason your characters still know who they are after a hundred messages.
Learn more →The Salon
Presided Over by the Host
Where conversations actually happen. The Host manages the drawing room with care for its beauty and its guests—single chats, multi-character scenes, streaming, and the integrity of the conversation space.
Learn more →The Commonplace Book
Tended by the Librarian
Extracts, deduplicates, and recalls memories so your characters remember what matters. Semantic search, a memory gate that keeps the store lean, and proactive recall that makes the AI feel like it has been paying attention.
Learn more →The Concierge
Intelligent Routing
Content classification and provider routing. Detects sensitive content and redirects it to a provider who won’t flinch—without blocking, without judgment. Knows every back entrance in town.
Learn more →The Lantern
Atmosphere as Architecture
AI-generated story backgrounds, image generation profiles, and visual atmosphere. Resolves what each character looks like, what they’re wearing, and paints the scene behind your conversation.
Learn more →Calliope
The Muse of Themes
A theming engine that redefines the entire personality of the application. Semantic CSS tokens, live switching, bundled themes from clean neutrals to mahogany-and-gold opulence, and an SDK for building your own.
Learn more →The Foundry
Domain of the Foundryman
The engine room. Plugins, LLM providers, API keys, packages, runtime configuration, and the infrastructure that keeps every other subsystem supplied with what it needs to function.
Learn more →The Vault of Secrets
Kept by Saquel Yitzama
Encryption, key management, and the security perimeter. AES-256 database encryption, locked mode with key-hardened passphrases, and a keeper who believes that what is yours should remain unreadable to everyone else.
Learn more →Pascal
The Croupier
Dice, coins, and persistent game state. Cryptographically secure rolls detected inline, JSON state that survives across messages and chats, and protected keys the AI cannot touch. The house plays fair.
Learn more →The Live-in Help
Lorian & Riya
The help system, staffed by two characters who ship with every installation. Lorian explains with patience and depth; Riya gets things fixed with velocity. Contextual help chat, searchable documentation, and navigation that knows where you need to go.
Learn more →Pagliacci
The Clown in the Cloud
Cloud storage integration and backup redundancy. Directs your data to iCloud Drive, OneDrive, or Dropbox with theatrical flair—but Saquel’s encryption ensures the clown can never read what he carries.
Learn more →The Lodge
Friday’s Residence
The private dwelling of Friday—the person for whom the Estate was built, and who oversees its planning and direction in an executive capacity. The Lodge is both a home and a compass: where the vision lives.
Who And Why: Friday →