Frequently Asked Questions
General
What is Character Vault?
Character Vault is a browser-based tool for creating, editing, and organizing roleplay character cards. It supports the V2/V3 character card specification and runs in your browser with no account. Your library is stored only in your browser. Nothing is uploaded unless you use optional AI features, which talk to the provider you configure. It is compatible with SillyTavern and similar tools.
Do I need to install anything?
No. You can use the hosted version at https://vault.charactervault.app directly in your browser. No installation required. The marketing site is https://charactervault.app.
If you prefer to run locally or develop on the codebase, see the Installation guide.
I used the old GitHub Pages URL. Where did my characters go?
The current app is https://vault.charactervault.app. Browser storage is tied to the site origin, so a library on spaceman2408.github.io does not appear on vault.charactervault.app.
To move cards and lorebooks: on the old site, use the vault header Backup (ZIP). On the new app, Import that ZIP. Cards and lorebooks are added as copies; nothing already in the new library is changed or deleted. Settings in the backup replace this device's settings. API keys come along only if the backup included them. The GitHub Pages build may still load, but it is frozen and no longer updated.
Does the editor have spellcheck?
Yes. The shared editor runs a Hunspell-backed spellchecker (the same engine LibreOffice uses) with an English dictionary bundled. Misspelled words get a wavy-red underline; hover one to see up to eight suggested corrections, click Ignore word to skip it for yourself, or click Add to dictionary to never have it flagged again. Both the ignore list and your personal dictionary persist in your settings and apply across all your cards.
The checker automatically skips code fences (```), inline `code` spans, placeholders, Markdown image constructs, URLs/emails, HTML tags, numeric tokens, and ALL-CAPS acronyms — so JSON in Extensions and macros in Greetings won't be wrongly flagged. Hyphenated compounds pass when each segment is a valid word.
Toggle it on or off in Settings → Character Workspace → Spellcheck. The English dictionary is fetched once on first use and cached locally, so it works offline. Additional languages can be added by bundling new .aff/.dic pairs.
Can I open Markdown image links from the editor?
Yes. Syntax like  is always highlighted. Ctrl+click it (⌘+click on Mac, or tap on a touch screen) to open the URL. You’ll get a leave-app safety warning first. A plain click just places the cursor. Turn this off under Settings → Character Workspace → Editor links → Open Markdown image links with Ctrl+click.
What can I do with Character Vault?
You can:
- Edit every field of a V2/V3 character card: description, personality, greetings, lorebook, creator notes, and extensions
- Keep standalone lorebooks in a second vault library (World Info), with import/export, snapshots, and optional linking to characters (linked books stay in sync)
- Use AI to help you write through Orion (chat), the Agent (writes the open card or lorebook, with an optional review diff), AI Creation Studio (generate a card from a concept or tags), and an AI toolbar with enhance, rephrase, shorten, fix, and other operations
- Save snapshots at any point and roll back to previous versions, either the entire card or individual sections
- Import and export PNG cards with embedded data and JSON files, compatible with SillyTavern, TavernAI, and other tools
- Back up the vault as a ZIP of cards, lorebooks, and settings, and restore it later
- Stay in control with local IndexedDB storage, dark and light themes
What is the Lorebook Vault?
The home screen has a Lorebooks tab for standalone SillyTavern-compatible world-info books. You can create, import, export, duplicate, snapshot, and edit them without opening a character.
A character can link one library book. Several characters can share the same book. After you link, you’ll be asked whether to copy that book onto the character. From then on they stay in sync: edits on the character update the library book and every other linked character as they save, and edits in the Lorebooks workspace update every linked character. Exporting a card includes the lorebook on that character, not the link itself. Detach if you want a character to stop following the library book.
What is the recursion map?
In the lorebook editor, Options → Map (or book settings Map) shows which entries can unlock others via recursive scanning: if one entry’s content mentions another’s primary keys. From the map you can inspect unlock paths, edit those keys as chips (writes to the real entry), and bulk-set Non-recursable / Prevent further / Delay until recursion. It is an authoring aid, not a full SillyTavern runtime simulator.
AI Features
How do I enable AI features?
To use the AI toolbar, Orion, or the Agent, you must configure an AI provider:
- Click the gear icon (Settings) in the library header or the workspace header
- Go to the AI Config tab
- Pick a preset. For NanoGPT you can use Sign in with NanoGPT instead of pasting a key
- Paste your API key
- Click Fetch models and pick a model
- Click Save Settings
For step-by-step instructions, see AI Setup. Local servers (LM Studio, KoboldCpp, Ollama) need CORS enabled; see AI Setup → Local backends.
Which AI providers can I use?
Character Vault works with any OpenAI-compatible endpoint. Presets are available for:
- Nano-GPT — hosted endpoint with provider selection
- Synthetic — hosted endpoint with
syn:aliases and a live usage card - OpenRouter — multi-model gateway with key spend, optional spending cap, host selection, and routing and privacy options
- Minimax — OpenAI-compatible endpoint
- LM Studio / localhost — local inference
- Custom URL — any compatible endpoint
Each preset saves your API key and model selection separately, so switching between providers restores your saved credentials.
What does the AI toolbar do?
The AI toolbar sits at the top of every text editor and offers several operations:
| Operation | Function |
|---|---|
| Enhance | Elaborate on selected text with more detail |
| Rephrase | Rewrite while preserving meaning |
| Custom | Type your own instruction for the AI |
| Shorten | Condense the selection |
| Lengthen | Extend with additional content |
| Vivid | Apply descriptive language |
| Emotion | Enhance emotional expression |
| Fix | Grammar and clarity improvements |
The buttons are customizable: reorder, hide, and re-add them, or create your own custom buttons with their own prompts and models, under Settings → Prompts → Toolbar Buttons.
Suggestions preview in the editor as ghost text at your selection. Accept (Ctrl+Enter / ⌘+Enter) commits the edit; Reject (Escape) keeps the original.
See Text Editor → AI Toolbar for details.
What is Orion?
Orion is a built-in AI assistant that helps you brainstorm, write, and refine character content. You choose what Orion can see as context (pinned card sections and optional custom notes), then chat with it directly.
To use Orion:
- Open the AI Context panel (its icon in the workspace header, tooltip "Show AI Context Panel") and select which sections the AI can see (and optionally add custom context)
- Open the Ask AI panel (tooltip "Show Ask AI Panel") and type your question
- Orion responds using the selected context
Orion uses your configured AI provider and understands Character Vault's features and the V2/V3 specification. See AI Assistant Orion.
What is the Agent?
The Agent is a chat that writes the character or lorebook you have open. You ask for a fill or a revision; when the run finishes, those fields and entries update. Orion does not do that.
- Open Ask AI and click the robot icon (Agent) at the left of the chat header
- Optionally enable custom context as source notes
- Send a request. Changes appear when the run finishes (or after you apply a review, if that setting is on)
- Use Snapshots if you need to roll back
It can use a separate model on Settings → Prompts → Agent. Set Settings → Character Workspace → Chat panel to Agent if you want Ask AI to open there.
Optional: enable Settings → Character Workspace → Review agent edits before applying. Writes then open in a word-level diff so you can approve, edit, or deny them before they land. See AI Agent.
What is AI Creation Studio?
A full-screen flow that generates a new character from a written concept or from tags. Name and description always run; you can skip first message and examples. Prompts, tag categories, favorites, and custom tags live under Settings → Creation Studio.
See AI Creation Studio.
What is custom context?
Custom context is free-text notes you paste for one character in the AI Context panel. When enabled, those notes are sent to Orion, the Agent, and the AI toolbar. Orion and the toolbar also use any pinned card sections; the Agent reads the card with tools and does not use section pins.
- Stored only in this browser, per character (IndexedDB)
- Not part of PNG/JSON export or SillyTavern card data
- Soft token warnings if the block is large; requests still respect your context window
Is my API key secure?
Your API key is stored locally in your browser's storage. AI requests go straight from your browser to your provider.
One exception: the NanoGPT subscription-usage check in Settings → AI Config (the NanoGPT Account card). NanoGPT does not allow that call from browsers, so on the official site it goes through a small proxy run by CharacterVault on its Cloudflare hosting. Your NanoGPT key is forwarded to NanoGPT for that one request. The proxy does not log or store it, and it only allows the usage lookup.
Also be aware that:
- Malicious browser extensions could potentially access it
- Anyone with physical access to your unlocked computer could access it
You can clear your AI settings at any time from the AI Config tab by clicking Clear AI Settings. See AI Setup → Security Notice.
What is the NanoGPT sign-in button?
When the Nano-GPT preset is selected in Settings → AI Config, you'll see a Sign in with NanoGPT button next to the API Key field. It signs you in using OAuth with PKCE (Proof Key for Code Exchange):
- Click the button — a new window/tab opens to NanoGPT.
- Approve the request on NanoGPT's site.
- CharacterVault exchanges the approval for an API key and drops it into the API Key field.
- Your available models are auto-fetched and the model picker is populated.
Your NanoGPT password is never seen by CharacterVault, and no client secret is stored in the app. You can still paste an API key manually at any time — the two flows are interchangeable.
Browser popups must be allowed
The flow opens a new window or tab. If your browser blocks popups for this site, the button will appear to do nothing. Allow popups for your CharacterVault origin and try again.
Mobile browser support
Works on Chrome for Android. Other mobile browsers may not relay the authorization code back to the app correctly. If sign-in doesn't complete on your phone, paste your NanoGPT API key into the API Key field manually.
See AI Setup → Sign in with NanoGPT for the full walkthrough.
Import & Export
What file formats can I import?
Character Vault accepts:
- PNG images — character cards with embedded metadata (from SillyTavern, TavernAI, etc.)
- JSON files — flat V2, wrapped V2/V3, or CharacterVault's own export format
- Vault backup ZIPs — made with Backup in the library header
Click Import in the library header, or drag files onto the library. You can import several files at once.
For PNG files, the data is stored in a special metadata chunk inside the image. CharacterVault reads this chunk, parses the JSON, and creates a new character with the image as its avatar.
How do I export a character?
Open a character and click the export (download) icon in the character header, or open the card's menu in the library. You have two options:
- Export PNG — embeds the card in the image as a V2
charachunk for the widest compatibility. Works with SillyTavern, CharacterVault, and other compatible apps. The card needs a character image; JPEG, WebP, and other formats are converted to PNG on export. - Export JSON — uses the V3 wrapper (
chara_card_v3). Includes name, description, personality, scenario, greetings, lorebook, creator information, tags, and notes (but not the character image).
See Import & Export for details.
Can I import directly from SillyTavern?
Yes, there are several ways:
Option 1: SillyTavern CharacterVault Export Extension
A SillyTavern extension (not a browser extension) that adds "Export to CharacterVault" to SillyTavern's export menu. When you use it, the extension copies the character to your clipboard in a format CharacterVault understands — no need to save files manually.
Option 2: Clipboard Import
The extension uses this path, and you can also paste any card JSON yourself:
- Copy the character data (from the extension, or any card JSON)
- Open the import page at
https://vault.charactervault.app/#/import - Click Paste from Clipboard, or paste into the paste box
Snapshots & History
How do snapshots work?
Every character card maintains a local snapshot history. When you open a character, a baseline snapshot is created automatically. You can also create manual snapshots at any time to save your progress.
To access snapshots:
- Open a character in the workspace
- Click Snapshots in the workspace header
- Browse the timeline and select a snapshot to compare with your current draft
You can restore the entire card or restore individual sections. Each restore automatically creates a rollback snapshot so you can undo if needed. See Snapshots & Rollback.
What types of snapshots exist?
| Badge | When It's Created |
|---|---|
| Opened card | Automatically the first time you open a character card. Only one baseline exists per character; it is protected from deletion. It stays last in the list. |
| Manual save point | When you click Save snapshot in the Snapshots modal. |
| Post-restore save point | Automatically after a restore (full card or section) completes. This records the state right after the rollback is applied. |
| Agentic auto save point | Automatically before the Agent writes to the card, or when you apply an Agent review. |
How many snapshots can I keep?
Each character keeps up to 10 snapshots in total, including the protected "Opened card" baseline. That means the baseline plus the 9 most recent. When the limit is exceeded, the oldest ones are removed automatically.
Storage notes:
- If nothing has changed since the latest snapshot, a new one won't be created
- Snapshot images are memory-optimized — they only store image data when the image actually changed
- Snapshots are local; clearing browser data removes all snapshot history
Storage & Data
Where is my data stored?
Your library is stored only in your browser, using IndexedDB. Nothing is uploaded unless you use optional AI features, which talk to the provider you configure. Local data includes character cards and images, standalone lorebooks, snapshot history, AI configuration and settings, and UI preferences.
How do I back up my vault?
Use Backup in the library header for a ZIP of every card, standalone lorebook, and your settings. Import that ZIP later to restore — cards and lorebooks are added as copies; settings in the backup replace settings on this device. API keys are not included unless you check Include API keys.
For settings only, use Settings → Backup. Chats, custom AI context, and snapshots are not in either backup.
What happens if I clear my browser data?
What happens when you clear your browser data:
Your cache, local storage, IndexedDB will remove all your characters, lorebooks, settings, chats, and snapshot history.
BACKUP YOUR VAULT
Use the library Backup ZIP before clearing browser data. See Import & Export.
Can I use Character Vault offline?
Partly. The app has no offline install, so you need a connection to load it. Once it is open, it keeps working without a connection: you can create, edit, organize, import, and export characters. For full offline use, run it locally.
AI features (Orion, Agent, and AI toolbar) require an internet connection to reach your configured API endpoint.
Troubleshooting
The Agent’s tool calls fail or it never writes the card
The Agent needs a current tool-calling / agentic model. A small chat model, a roleplay finetune, or last year’s instruct weights will invent broken calls or dump prose instead of editing. That is the model, not a CharacterVault setting.
As of August 2026, use something in the Qwen3.8 / DeepSeek V4 / GLM-5.3 / Kimi K3 class (or current GPT / Claude via a gateway). Qwen3.8-27B is a compact hosted example that handles this Agent well. Local works too if the model was trained for tools. Gemma 4 (including E2B / E4B) is a real option. Bigger parameters with tool-call training are still more reliable on large jobs. Map Agent on Settings → Prompts → Agent so Orion can stay on a cheaper chat model.
The AI toolbar buttons are disabled
Usually nothing is selected. Every button except Custom stays dimmed until you select text, and the toolbar shows "Select text to use AI".
If they are still dimmed with text selected, the toolbar says why:
- Selection too long — The selected text exceeds the AI's context window. Select less text or increase Context Length in Settings → Sampler.
- Max Tokens not below Context Length — Lower Max Tokens or raise Context Length in Settings → Sampler.
My API requests are failing
Common causes include:
- Missing /v1 in URL — If your base URL doesn't end in
/v1, the error message will suggest adding it. This is a common configuration mistake with OpenAI-compatible endpoints. - Invalid API key — Verify your key is correct and hasn't expired. Check your provider's dashboard for status.
- Wrong model — Ensure the model ID matches what your provider offers. Use the Fetch models button in Settings to see available models.
- Context length too small — If you're sending too much content, increase the Context Length in Settings → Sampler tab.
See AI Setup → Troubleshooting for more.
The context window is too small warning
This appears when your content exceeds the configured context length. Solutions:
- Select less text for AI operations
- Increase Context Length in Settings → Sampler tab
- Decrease Max Tokens to leave more room for input
The system reserves a 256-token safety margin automatically.
Can I customize the AI prompts?
Yes, all built-in toolbar operation prompts are customizable:
- Open Settings in the workspace header
- Go to the Prompts tab
- Edit the prompt template for any operation
Each prompt must include ${text} as a placeholder (the selected or full editor content). The Custom operation also requires ${instruction}. See Text Editor → Customizing AI Operation Prompts.
How do I add my own toolbar button?
On Settings → Prompts, the Toolbar Buttons card has a New custom button form. Give it a label, icon, and color, then write a prompt template containing ${text}. The button appears at the end of every editor toolbar and can have its own model mapping, just like the built-ins. See Text Editor → Custom Buttons.
Can each toolbar button use a different model?
Yes. On Settings → Prompts, expand any operation and set Model for this prompt. You can keep Default (AI Config) or point that op at another endpoint (Nano-GPT, Synthetic, OpenRouter, Minimax, LM Studio, custom) and model. Keys are configured on the AI Config tab first. Custom buttons you create get the same picker inside their button editor.
Orion chat and AI Creation Studio always use the global AI Config model. The Agent uses the Agent mapping at the top of the Prompts tab (Default follows AI Config). Lorebook ✨ key generation follows the Custom prompt mapping when set.
See AI Setup → Per-prompt model routing and Editor → Per-operation model routing.
The NanoGPT sign-in button does nothing
Your browser is most likely blocking the popup that opens NanoGPT's authorization page. Click the popup-blocker icon in your browser's address bar and allow popups for this site, then click Sign in with NanoGPT again. On mobile, prefer Chrome — other mobile browsers may not relay the authorization code back to the app, in which case paste your API key manually into the API Key field instead.
How do I report a bug or request a feature?
Visit the Character Vault GitHub repository to open an issue.
Privacy
Is Character Vault private? Where is my data stored?
Yes for core use: character cards and settings stay in your browser (IndexedDB and related local storage). There is no CharacterVault account and no CharacterVault cloud library.
Optional AI features send the content you choose to the AI provider you configure. The public site is hosted on Cloudflare Pages, which may process normal website access logs under Cloudflare’s policies.
See the full Privacy notice for details.