Chatbox User Guide

Chatbox (Community Edition) is a desktop and mobile client for talking to AI models. It runs on Windows, macOS, Linux, the web, iOS, and Android, connects to virtually any major AI provider (OpenAI, Claude, Google Gemini, Ollama, DeepSeek, and ~20 others), and keeps your conversations and API keys stored locally on your own device. On top of plain chat it adds image generation, document knowledge bases, web search, Model Context Protocol (MCP) tools, reusable assistants ("Copilots"), and team API-key sharing.

This guide shows you how to install Chatbox, connect a model, and use every feature. It is written for end users — if you want to build from source, deploy the web version, or understand the internals, see the companion Admin Guide.

Note

This is the Community Edition, open-sourced under GPLv3. It is functionally the same chat client that ships in the official downloads. "Chatbox AI" — the first‑party, paid cloud model and search service — is one of the providers you can optionally enable inside the app; you are never required to use it.

1. Quick Start

The fastest path to your first answer:

1. Install Chatbox for your platform (see Installation).
2. Launch it. On first run a short setup guide appears for new users.
3. Open Settings and pick how you want to get a model:
   • Easiest: open Settings → Chatbox AI, log in (or paste a license key), and claim a free plan. No API key of your own needed.
   • Bring your own key: open Settings → Model Provider, choose a provider (e.g. OpenAI), and paste your API key.
   • Fully local: install Ollama or LM Studio, then point Chatbox at it — no key, no cloud.
4. Return to the home screen, type a message in the input box, and press Enter.

What can I help you with today?

> Explain the difference between TCP and UDP in two sentences.

Tip

Press Alt+` (backtick) at any time — even when Chatbox is hidden — to instantly show or hide the window. This global hotkey makes Chatbox feel like a quick-access scratchpad.

2. Installation

Chatbox ships as a normal installable application. There is no server to set up and no command line required for everyday use.

2.1 Desktop

Windows

1. Download the Setup.exe installer from chatboxai.app or the GitHub Releases page.
2. Run the installer. You may choose the installation directory.
3. Launch Chatbox from the Start menu.

Both 64‑bit (x64) and ARM64 builds are provided.

macOS

1. Download the .dmg — pick Intel or Apple Silicon to match your Mac: Intel · Apple Silicon.
2. Open the .dmg and drag Chatbox into your Applications folder.
3. Launch it from Applications.

Linux

1. Download the .AppImage (or .deb) from chatboxai.app or GitHub Releases. x64 and ARM64 builds are available.
2. For the AppImage: chmod +x Chatbox-*.AppImage then run it.
3. For the .deb: sudo dpkg -i Chatbox-*.deb.

Note

Desktop builds support automatic updates. When a new version is downloaded in the background, Chatbox notifies you and lets you restart to apply it. You can turn this off in Settings → General.

2.2 Web

Don't want to install anything? Use the browser version at web.chatboxai.app. It runs entirely in your browser and stores data in the browser's local storage.

Important

The web version cannot run some desktop-only features (launch at startup, global hotkeys, stdio-based MCP servers, local document parsing). It is best for quick access from a shared or locked-down machine.

2.3 Mobile (iOS & Android)

• iOS / iPadOS: App Store
• Android: Google Play or download the APK directly.

2.4 Build from source

If you prefer to build the Community Edition yourself, you need Node.js ≥ 20 (< 23) and pnpm ≥ 10:

git clone https://github.com/chatboxai/chatbox.git
cd chatbox
pnpm install
pnpm dev            # run in development mode
pnpm package        # build an installer for your current platform

See the Admin Guide for the full build matrix (web, mobile, all-platform packaging).

3. Connecting an AI Model

Chatbox does not include a model of its own — you point it at one. There are three ways to get a working model, and you can mix them freely.

3.1 Option A — Use Chatbox AI (no key of your own)

Settings → Chatbox AI offers the first‑party cloud service. You can either:

• Log in with a Chatbox account, or
• paste a license key (switch to "License Key" view).

Once activated, Chatbox AI models (e.g. chatboxai-4) and the built‑in web search and document parsing become available. New users can often claim a free plan from the welcome card on the home screen.

Tip

Chatbox AI is the lowest-friction option: it is the default model for new conversations (chatboxai-4) and the default for image generation (DALL-E-3). If you'd rather not use it, just configure another provider and set a different default in Settings → Default Models.

3.2 Option B — Bring your own API key

Open Settings → Model Provider and select a built‑in provider. Chatbox ships with definitions for all of these:

For most providers you paste an API Key. You can optionally override the API Host and API Path (useful for proxies or self-hosted gateways), and toggle "Improve Network Compatibility" (useProxy) when a host is hard to reach.

Tip

Click Fetch Models on a provider page to pull its current model list. Curated "known-good" models are shown by default; newly discovered models appear separately. You can hide models you never use.

Custom providers

If your provider isn't listed, click Add Provider (or import a config) and choose the API style it speaks: OpenAI‑compatible, Claude‑compatible, Gemini‑compatible, or OpenAI Responses. Most third‑party gateways are OpenAI‑compatible.

Note

You can also import a provider configuration from a link of the form chatbox://provider/import?config=.... Chatbox opens the provider settings pre-filled so you only confirm.

3.3 Option C — Run models locally (Ollama / LM Studio)

For private, offline inference:

1. Install and start Ollama (default http://127.0.0.1:11434) or LM Studio (default http://127.0.0.1:1234/v1).
2. Pull a model in that tool (e.g. ollama pull llama3).
3. In Chatbox, open Settings → Model Provider → Ollama (or LM Studio) and confirm the host. Fetch models and pick one.

No API key is required and nothing leaves your machine.

4. Everyday Usage

4.1 Sending messages

Type in the input box and press Enter to send. Use the in-box controls to:

• Pick a model for this conversation (the model selector).
• Attach files (see Attachments).
• Toggle web browsing for this message.
• Attach a knowledge base.
• Open per-conversation settings (temperature, system prompt, etc.).

Note

mod means Cmd on macOS and Ctrl on Windows/Linux.

4.2 Conversations and threads

Each conversation appears in the left sidebar. Conversations come in two types: chat sessions and picture (image-generation) sessions.

Chatbox auto-names conversations using an AI model (configurable — see Default Models). You can rename, delete, and reorder conversations from the sidebar.

Tip

Long conversations are automatically compacted: when the context window fills past a threshold, older messages are summarized to save tokens while keeping key information. Tune this under Settings → Chat → Context Management (see §5.6).

4.3 Copilots (reusable assistants)

A Copilot is a saved assistant defined by a name, an avatar, and a system prompt — for example "Translator", "Code Reviewer", or "Marketing Writer".

• Browse and create them on the Copilots page, or pick one from the carousel on the home screen before starting a chat.
• "My Copilots" are yours; a gallery of community Copilots is also shown and can be copied into your own list.
• Selecting a Copilot starts a new conversation seeded with its system prompt.

4.4 Attaching files and images

Drag a file onto the input box or use the attach button. Chatbox extracts text locally (or via the cloud parser) so the model can read it.

Supported document types:

Warning

Audio, video, archives (.zip, .rar), executables, and design files (.psd, .fig, .heic, camera RAW) are not supported as attachments. Chatbox will tell you the file type is unsupported rather than fail silently.

Tip

Turn on "Paste long text as a file" (Settings → Chat) so that pasting a large block of text inserts it as an attachment instead of cluttering the message — this keeps chats clean and improves prompt caching.

OCR for non-vision models: if you send an image to a model that can't see images, Chatbox can OCR it first using a vision model you choose in Settings → Default Models → OCR Model, then send the extracted text.

4.5 Image generation

Start a picture conversation (mod+Shift+n) or use the Image Creator page. By default it uses Chatbox AI's DALL-E-3 with the "vivid" style and generates one image per prompt. Generated images are stored locally and can be previewed, zoomed, and saved.

4.6 Web search

Let the model look things up online. Toggle web browsing for a message (mod+e), then configure the provider under Settings → Web Search:

Each key field has a Check button to verify the key works before you rely on it.

Tip

Some providers also support Read Webpage (fetching and reading a specific URL), shown as a checkmark under "Provided tools". If a provider only supports search, that tool is greyed out.

4.7 Knowledge bases (chat with your documents)

A Knowledge Base lets the model answer from your own files using retrieval (RAG). Create one under Settings → Knowledge Base:

1. Create a knowledge base, choosing an embedding model (required) and optionally a rerank model and a vision model (for images in documents).
2. Upload files (up to 100 MB each). Chatbox parses, splits, and indexes them in the background.
3. Watch each file's status: pending → processing → done (or failed). You can pause, resume, retry, or delete individual files.
4. In a conversation, attach the knowledge base from the input box. The model will retrieve relevant passages when answering.

Note

Documents are parsed locally by default on desktop. If a file fails local parsing (or you're on mobile/web), you can Retry with server parsing, which uses the Chatbox AI cloud parser (requires a license; large files have a 50 MB server limit). A third option, MinerU, is available for advanced document parsing.

Tip

If processing was interrupted (e.g. you closed the app), files are set to paused on next launch — just click Resume. Indexing resumes from where it stopped, so you don't reprocess everything.

4.8 MCP tools

Chatbox is an MCP (Model Context Protocol) host, so models can use external tools. Configure servers under Settings → MCP:

• Built‑in servers — toggle the ones Chatbox provides.
• Custom servers — add your own. Desktop supports stdio servers (a local command Chatbox launches) as well as remote servers over HTTP/SSE.

Note

You can install an MCP server from a link of the form chatbox://mcp/install?server=.... Chatbox opens the MCP settings with the server config pre-filled for you to confirm.

Warning

A local (stdio) MCP server is a program that runs on your computer with your permissions. Only add servers you trust.

4.9 Rendering: Markdown, LaTeX, code, and diagrams

By default Chatbox renders assistant replies richly. Under Settings → Chat → Function you can toggle:

• Markdown Rendering (on by default)
• LaTeX Rendering for math (requires Markdown)
• Mermaid Diagrams & Charts
• Auto-collapse code blocks
• Auto-preview artifacts — automatically render generated HTML/CSS/JS (off by default)

5. Settings Reference

Open settings from the sidebar (desktop opens it as a dialog; mobile navigates to a full page). The panels are:

5.1 General

5.2 Chat

Avatars (user + default assistant), the default system prompt, default temperature and Top P, default max context message count, background image, stream output, plus display toggles (show avatar, word count, token usage, model name, timestamp, first‑token latency) and the rendering toggles from §4.9.

5.3 Default Models

Pick which model is used for each automatic job:

5.4 Web Search

See §4.6.

5.5 Keyboard Shortcuts

Customize every hotkey listed in this guide (desktop only). See §8.

5.6 Conversation context management

Under Settings → Chat → Context Management:

• Auto Compaction (on by default) — summarize old messages when context fills up.
• Compaction Threshold (40–90%, default 60%) — lower = cheaper (compacts earlier, may lose context); higher = preserves more context but uses more tokens.

6. Backing Up and Moving Your Data

All your data lives on your device. To move it to another machine or keep a backup:

Export (Settings → General → Data Backup):

• [x] Settings
• [x] Chat History
• [x] My Copilots
• [ ] API Key & License (only included if you tick it)

Click Export Selected Data to save a chatbox-exported-data-<date>.json file.

Caution

If you do not tick "API KEY & License", the export strips your API keys, license key, and cloud credentials. This is the safe default for sharing a backup — but remember those keys won't be present when you restore.

Restore (Settings → General → Data Restore): click Import and Restore and choose the JSON file.

Warning

Importing overwrites existing data and Chatbox restarts immediately to apply it. Export your current data first if you might want it back.

Tip

On desktop, Chatbox also keeps automatic rolling backups of its config file every 10 minutes and self-heals from the latest valid backup if the config ever becomes corrupted — so a crash won't normally lose your settings.

7. Languages

The interface is available in 14 languages: English, 简体中文 (Simplified Chinese), 繁體中文 (Traditional Chinese), 日本語, 한국어, Русский, Deutsch, Français, Português, Español, العربية (with right‑to‑left layout), Italiano, Svenska, and Norsk Bokmål. Change it under Settings → General → Language; Chatbox also picks a sensible default from your system language on first run.

8. Keyboard Shortcuts

Defaults (all customizable under Settings → Keyboard Shortcuts; mod = Cmd/Ctrl):

Note

On Windows and Linux the Alt-based global toggle can occasionally clash with other apps' Alt shortcuts. If that happens, change the quick toggle hotkey in Settings.

9. Team API-Key Sharing

Chatbox includes a small self-hostable proxy ("team-sharing") so a team can share one OpenAI-style API key without distributing the secret to everyone. Setting it up is an administrator task — see the Admin Guide and the project's team-sharing README. Once it's running, each member points their provider's API Host at the proxy URL and uses a shared access key.

10. Troubleshooting

Format: the exact symptom, the cause, and the fix.

The input box won't accept typing / is slow to respond

Cause: a transient renderer/IME issue, most often reported on some Windows setups and with certain input methods (community issues #3733, #3658). Solution: click directly inside the input box; if it persists, restart Chatbox. If right-click paste doesn't work in the box, use mod+V. Prevention: keep Chatbox updated.

Right-click menu in the message box closes instantly (macOS)

Cause: a known macOS context-menu timing issue (#3658). Solution: use keyboard shortcuts for copy/cut/paste (Cmd+C / X / V) instead of the right-click menu.

"Network Error" with a custom Claude/Anthropic host (mobile)

Cause: the "Improve Network Compatibility" (useProxy) toggle is not honored for custom Anthropic hosts on iOS/Android in some builds (#3739). Solution: verify the API Host is exact and reachable; try a different network. On desktop, set a Network Proxy in General settings if needed.

A model replies with an error about a missing reasoning_content field

Cause: certain DeepSeek/GLM reasoning models require a reasoning_content field, especially during tool-calling/web-search or multi-turn chats (#2762, #3676). Solution: update Chatbox, or switch to a non-reasoning variant of the model for that conversation.

A custom MCP tool call fails, or a remote HTTPS MCP server "cannot be used"

Cause: MCP server misconfiguration or an unsupported transport for that build (#3728, #3725). Solution: re-check the server command/URL under Settings → MCP. For remote servers confirm the transport (HTTP/SSE) and that the URL is reachable. On desktop, prefer a local stdio server if a remote one won't connect.

Knowledge-base file shows "failed"

Cause: the file couldn't be parsed locally, produced no extractable text, or timed out (processing has a 5‑minute per-file timeout). Solution: click Retry on the file; if it still fails, click Retry with server parsing (requires a Chatbox AI license; ≤ 50 MB). Confirm the file is a supported type and under 100 MB.

"No content extracted from file"

Cause: the document had no readable text (e.g. a scanned PDF with no text layer, or an empty EPUB). Solution: use server parsing (which can OCR), or supply a text-based version of the document.

Conversations are missing from the sidebar

Cause: the conversation list index lost track of stored sessions. Solution: Settings → General → Data Recovery → Recover Conversation List scans storage and rebuilds the list.

Chatbox AI says my license is invalid or expired

Cause: the license key is wrong, expired, or its device activation was revoked (error codes 20002/20004). Solution: re-enter the key under Settings → Chatbox AI, or log in again. Chatbox re-validates your license on every launch.

"Rate limit exceeded" from Chatbox AI

Cause: you've hit the Chatbox AI service rate limit (error 20005) or daily free quota. Solution: wait and retry, or upgrade your plan. Free web-search/AI quota refreshes daily.

Updates won't install (Linux AppImage / store builds)

Cause: AppImages and app-store builds rely on external update mechanisms. Solution: download the latest build manually from GitHub Releases. On Windows/macOS desktop, ensure Automatic updates is enabled in General settings.

Launching the AppImage breaks Alt shortcuts in other apps (Linux)

Cause: the global Alt+` quick-toggle hotkey is captured globally (#3719). Solution: change the quick-toggle shortcut under Settings → Keyboard Shortcuts.

11. FAQ

Q: Where is my data stored? Does Chatbox upload my chats? Your conversations, settings, API keys, and knowledge bases are stored locally on your device. Chats are sent only to the AI provider you chose. Optional, anonymous crash/event reporting can be turned off in Settings → General → Error Reporting.

Q: Do I have to pay or use Chatbox AI? No. Chatbox AI is one optional provider. You can use your own API keys, or run models entirely locally with Ollama/LM Studio at no cost.

Q: Which AI providers are supported? 20+ built-in providers (OpenAI, Claude, Gemini, Azure, DeepSeek, Qwen, MiniMax, Moonshot, SiliconFlow, OpenRouter, Groq, xAI, Mistral, Perplexity, Volcengine, ChatGLM, GitHub Copilot, Bedrock, Ollama, LM Studio) plus any custom OpenAI/Claude/Gemini‑compatible endpoint.

Q: Can I use Chatbox completely offline? Yes for inference — run a local model via Ollama or LM Studio. Note that web search, the Chatbox AI service, and downloading new models still need a network.

Q: How do I move everything to a new computer? Export your data (tick API Key & License if you want keys included) and import it on the new machine — see §6.

Q: Can the AI read my PDFs and Office files? Yes — attach them to a message, or build a Knowledge Base for larger document sets. Supported types are listed in §4.4.

Q: What's the difference between a chat session and a picture session? A chat session talks to a text/vision model; a picture session generates images (default DALL-E-3). Start a picture session with mod+Shift+n.

Q: What is a Copilot? A reusable assistant defined by a system prompt (e.g. "Translator"). Selecting one starts a chat pre-loaded with its instructions. See §4.3.

Q: How do I make long conversations cheaper? Leave Auto Compaction on and lower the Compaction Threshold; consider a smaller Max Context Message Count in Chat settings.

Q: Can I run models without exposing my main API key to my team? Yes — deploy the team-sharing proxy (admin task) and have everyone point their API Host at it. See §9.

Q: Is there a web version? Yes, at web.chatboxai.app, plus native iOS and Android apps.

Q: How do I report a bug or request a feature? Use Help → Search Issues (desktop menu) or open an issue on GitHub. Attach exported Diagnostic Logs if support asks.

Q: How do I check for updates manually? Settings → Chatbox AI/About → Check Update, or download the latest build from GitHub Releases.

Q: The app is using an old model after the provider released a new one. Open the provider page and click Fetch Models to refresh the list, then select the new model.