# Introduction AgentOne is a fully-featured AI agent desktop application. To learn more about what AgentOne is, [visit the website](https://www.agent-one.dev). ## Key Features [#key-features] * **8,500+ AI models** from [60+ providers](/docs/guides/providers) including OpenAI, Anthropic, Google, xAI, Mistral, Groq, Cerebras, and more * **19,000+ built-in extensions** connecting to apps like Gmail, Notion, Slack, GitHub, Google Calendar, and more * **Multiple agents** can work on different parts of a task (or different tasks) simultaneously * **[MCP server support](/docs/guides/custom-extensions)** allows you to extend AgentOne with [Model Context Protocol](https://modelcontextprotocol.io) servers * **Private by default**, as your data stays on your device * **Cross-device sync** for settings. Synchronization for chats and API keys (encrypted) are coming soon to the Pro plan. * **Bring your own key** allows you to use your own API keys directly with no price markup ## Getting Started [#getting-started] To get started, visit [www.agent-one.dev](https://www.agent-one.dev) or read the [Installation Guide](/docs/installation). ## Get Help from the Community [#get-help-from-the-community] If you encounter bugs, missing features, or just want to chat with the AgentOne community & team, check out the resources below: * [AgentOne Forum](https://forum.agent-one.dev) - Public forum for AgentOne. The forum is currently in beta. Expect occasional downtime. * [AgentOne Discord Community](https://www.agent-one.dev/discord) - Our public community on Discord. We recommend this server if you want to be notified for new releases, but the forum is the best place to make feature requests or report bugs. * [AgentOne Public GitHub Repo](https://github.com/AgentOne-Dev/agent-one-public) - The public-facing side of AgentOne desktop on GitHub. Source code and other miscellaneous information is shared there. # Desktop App AgentOne is a desktop-first AI agent app. You can connect cloud providers, run local models, install extensions, manage large chat histories, and tune how the app looks and behaves - all from one native desktop application. Full app window with the three main areas annotated - sidebar on the left, main chat area in the center, and composer at the bottom. ## In This Section [#in-this-section] These pages cover the desktop app's core interface and experience. Finish onboarding, set up your first provider, and send your first message. Manage chat history, attachments, search, branching, editing, and exports. Customize appearance, chat behavior, performance, and update preferences. Sign in, manage your plan, sync settings, and set AI instructions. Use keyboard shortcuts and deep links to move faster. Fix common setup, provider, extension, and notification problems. ## Providers, Models, and Extensions [#providers-models-and-extensions] Provider setup, model configuration, and extension management are covered in the Guides section because they involve concepts and step-by-step workflows that go beyond the desktop UI. Connect built-in cloud providers, use Ollama or LM Studio, add custom providers, and configure model parameters. Use built-in tools, install registry extensions, and add custom MCP servers. # Smithery Integration AgentOne supports Smithery extensions. When you install a Smithery server with AgentOne, the app opens the `Add Custom Extension` dialog and pre-fills the server details for review. You can browse servers on [Smithery](https://smithery.ai) and install compatible ones into AgentOne from their server pages. ## How Smithery Works with AgentOne [#how-smithery-works-with-agentone] AgentOne registers the `agent-one://` URL scheme and handles the Smithery-style `mcp/install` deep link. When AgentOne receives a link like this: ```text agent-one://mcp/install?v=1&name=Example%20Server&config=%7B...%7D ``` it will: * Open `Settings` -> `Extensions` * Launch the `Add Custom Extension` dialog * Pre-fill the extension name * Pre-fill either the local command or remote URL * Ask you to review the configuration before adding it AgentOne supports the two Smithery transport types documented by Smithery: * `stdio`: AgentOne combines `command` and `args` into the `Command` field * `http`: AgentOne fills the `URL` field for the remote MCP endpoint ## Supported Smithery Config Shapes [#supported-smithery-config-shapes] ### Local Stdio Server [#local-stdio-server] {/* cspell:disable */} ```json { "type": "stdio", "command": "npx", "args": [ "-y", "@smithery/cli@latest", "run", "@wonderwhy-er/desktop-commander" ] } ``` {/* cspell:enable */} ### Remote HTTP Server [#remote-http-server] ```json { "type": "http", "url": "https://exa.run.tools" } ``` ## Install Flow [#install-flow] 1. Open a supported MCP server page on [Smithery](https://smithery.ai). 2. Choose AgentOne as the client when Smithery offers installation options. 3. Allow the `agent-one://` link to open AgentOne. 4. Review the pre-filled extension details in AgentOne. 5. Add any extra environment variables or HTTP headers the server needs. 6. Click `Add Custom`. AgentOne does not silently install Smithery extensions. The deep link only pre-fills the form so you can verify the settings first. ## Notes [#notes] * The optional `v=1` version parameter is supported. * AgentOne reads Smithery's `name` and `config` query parameters. * The `config` payload should be URL-encoded JSON. * If a server requires additional secrets, environment variables, or headers, add them in AgentOne before completing the install. ## Explore More Servers [#explore-more-servers] Explore more MCP servers on [the Smithery servers page](https://smithery.ai/servers). # Installation AgentOne is available on Windows, macOS, and Linux. Click on your OS below to read its installation guide. ## Select Your Platform [#select-your-platform] Install AgentOne on Windows Install AgentOne on macOS Install AgentOne on Linux ## System Requirements [#system-requirements] * A 64-bit processor * Preferably at least 4 gigabytes of RAM * Preferably at least 500 megabytes of available storage space * Access to the internet # macOS Setup Guide ## Install AgentOne on macOS [#install-agentone-on-macos] {/* prettier-ignore */} ### Download the desktop app [#download-the-desktop-app] Head to: [https://www.agent-one.dev/download](https://www.agent-one.dev/download) You'll be redirected to a download page, which will attempt to automatically detect your operating system. Make sure the `macOS` tab at the top of the page is selected: AgentOne download page showing macOS tab You'll see two download options: * **Download Apple Silicon (.dmg):** for Macs with Apple Silicon chips (M1, M2, M3, M4, or newer). * **Download Intel (.dmg):** for older Macs with Intel processors. Click the button that matches your Mac. Click the Apple menu in the top-left corner of your screen and select `About This Mac`. Look at the `Chip` or `Processor` field: * If it says something like `Apple M1`, `Apple M2`, `Apple M3`, `Apple M4`, or newer, choose **Apple Silicon**. * If it says something like `Intel Core i5` or `Intel Core i7`, choose **Intel**. If you pick the wrong one, AgentOne may not open correctly or may run more slowly than it should. To learn more, read [Apple's support article.](https://support.apple.com/en-us/116943) If macOS or your browser warns you about the download or blocks the app from opening, see the [Troubleshooting](#troubleshooting) section below. ### Open the `dmg` file [#open-the-dmg-file] When the download finishes, open the `.dmg` file from your browser or from the `Downloads` folder in Finder. ### Move AgentOne to Applications [#move-agentone-to-applications] In the installer window, drag `AgentOne.app` into the `Applications` folder. ### Open AgentOne [#open-agentone] Open the `Applications` folder and double-click `AgentOne`. The first time you launch the app, macOS may ask you to confirm that you want to open something downloaded from the internet. Click `Open` to continue. ## Troubleshooting [#troubleshooting] ### "AgentOne.app" is damaged and can't be opened [#agentoneapp-is-damaged-and-cant-be-opened] This is a common macOS Gatekeeper message for apps downloaded outside the App Store. To fix this, first try to go to System Settings > Privacy & Security and click 'Open Anyway' next to the security warning. If that doesn't work or you don't see a warning, try these steps. 1. Delete the old `.dmg` file and delete `AgentOne.app` from your `Applications` folder if it is already there. 2. Download a fresh copy for the correct macOS version. 3. Open the new `.dmg` file. 4. Drag `AgentOne.app` into the `Applications` folder. 5. Open the `Applications` folder, but do not open AgentOne yet. 6. Open the `Terminal` app on your Mac. You can do this by pressing `Command` + `Space`, typing `Terminal`, and pressing `Return`. 7. Copy and paste this command into Terminal: ```bash xattr -cr /Applications/AgentOne.app ``` 8. Press `Return` on your keyboard to run the command. 9. Close Terminal. 10. Go back to `Applications` and open `AgentOne` again. What this command does: it removes the macOS quarantine flag from the app so macOS will re-check it normally. Only do this if you downloaded AgentOne from `agent-one.dev` or the official GitHub releases page. If you still see the same message after doing this, [join our Discord server for live support](https://www.agent-one.dev/discord). ### "AgentOne.app" was downloaded from the internet [#agentoneapp-was-downloaded-from-the-internet] This is a normal macOS warning shown the first time you open many apps downloaded outside the App Store. If you downloaded AgentOne from `agent-one.dev` or the official GitHub releases page, click `Open`. ### "AgentOne.app" cannot be opened because the developer cannot be verified [#agentoneapp-cannot-be-opened-because-the-developer-cannot-be-verified] macOS Gatekeeper may block new or newly updated apps until you explicitly allow them. To resolve the issue, follow these steps: 1. Double-click `AgentOne.app` once so macOS shows the warning. 2. Open `System Settings`. 3. Go to `Privacy & Security`. 4. Scroll down to the `Security` section. 5. Click `Open Anyway` for AgentOne. 6. Confirm by clicking `Open`. Apple notes that the `Open Anyway` button is only available for about one hour after you try opening the app. If none of this works, you could also try the steps in the ["AgentOne.app" is damaged and can't be opened](#agentoneapp-is-damaged-and-cant-be-opened) section. ### "Apple could not verify "AgentOne.app" is free of malware" [#apple-could-not-verify-agentoneapp-is-free-of-malware] This is another version of the same Gatekeeper warning. Follow the steps in ["AgentOne.app" cannot be opened because the developer cannot be verified](#agentoneapp-cannot-be-opened-because-the-developer-cannot-be-verified). ### The app says it is from an unidentified developer or an unknown developer [#the-app-says-it-is-from-an-unidentified-developer-or-an-unknown-developer] This is another version of the same Gatekeeper warning. Follow the steps in ["AgentOne.app" cannot be opened because the developer cannot be verified](#agentoneapp-cannot-be-opened-because-the-developer-cannot-be-verified). ### Other Problems [#other-problems] Having a different issue? [Join our Discord server for live support!](https://www.agent-one.dev/discord) # Windows Setup Guide ## Get AgentOne from the Microsoft Store [#get-agentone-from-the-microsoft-store] Installing AgentOne from the Microsoft Store is the recommended method for Windows users. It's easy! Just open this link, or search "AgentOne" in the Microsoft Store: [https://apps.microsoft.com/detail/9NR1TW9NZZBW?hl=en-us\&gl=US\&ocid=pdpshare](https://apps.microsoft.com/detail/9NR1TW9NZZBW?hl=en-us\&gl=US\&ocid=pdpshare) Then click `Download` or `View in Microsoft Store` and follow the instructions. ## Manually Install AgentOne on Windows [#manually-install-agentone-on-windows] The Microsoft Store provides a more secure and reliable installation experience. You can read the instructions for installing from the Microsoft Store [above](#get-agentone-from-the-microsoft-store). {/* prettier-ignore */} ### Download the desktop app installer [#download-the-desktop-app-installer] Head to: [https://www.agent-one.dev/download](https://www.agent-one.dev/download) You'll be redirected to a download page, which will attempt to automatically detect your operating system. Make sure the `Windows` tab at the top of the page is selected: AgentOne download page showing Windows tab Now click `Download Installer (.exe)`. If you see a warning from Windows or your browser, or you are unable to download the file, reference the [Download Blocked by Windows](#download-blocked-by-windows) troubleshooting section. ### Run the installer [#run-the-installer] You're almost done! After downloading the installer, open it (click or double-click the `.exe` file) and follow the prompts to install AgentOne on your system. If you get stuck, refer to the [Windows Installer](#windows-installer) troubleshooting section below. ## Troubleshooting [#troubleshooting] ### Windows Protected Your PC [#windows-protected-your-pc] Because AgentOne is relatively new software, Windows SmartScreen may block it by default. If you see a message like `Windows Protected Your PC`, look for a button or link such as `Learn more` or `Advanced`, click it, and then click `Run anyway`. ### Download Blocked by Windows [#download-blocked-by-windows] If your system is equipped with Windows Defender SmartScreen or similar security features, you may encounter warnings when attempting to download or run the installer. This is not a problem with AgentOne or Windows, it's a feature built-in to your computer. Windows Defender SmartScreen warning If you see a SmartScreen warning, look for an option like `Advanced`, `Proceed anyway`, or similar. In Microsoft Edge, click the three dots next to the download and select `Keep`. You may see an additional screen warning you that AgentOne isn't commonly downloaded. Next to the `Delete` button, click the dropdown arrow and select `Keep anyway`. Keep anyway option The file should then begin downloading. Once it finishes, you can click "Open file" to run the installer and follow the prompts to complete the AgentOne installation. If you encounter any issues while running the installer, see the [Windows Installer](#windows-installer) troubleshooting section. File downloaded successfully in Microsoft Edge ### Windows Installer [#windows-installer] If you get stuck or are unsure what option to select while running the AgentOne installer, reference this section. It will walk you through running the Windows installer `exe` that you downloaded in either of the previous sections. #### Run the installer [#run-the-installer-1] After downloading the installer, try opening it from your browser. It's probably listed in the top-right corner of your browser window under a `Downloads` icon. If you can't find the file, try this: * Open your File Explorer and navigate to the `Downloads` folder. * Look for the `AgentOne_x.x.x_x64-setup.exe` file and double-click it to start the installation. * If you saved the file to a different location, navigate to that folder and double-click the installer file. #### Choose an install location [#choose-an-install-location] The installer window should prompt you for an installation. If you see a screen like this one first, simply click `Next`: AgentOne installer initial screen showing Next button The installer should automatically detect the correct location to install AgentOne. Click `Next` to continue. If it doesn't choose a location for you, a good default location is `C:\Users\\AppData\Local\AgentOne` (replacing `` with your username). AgentOne install location selection screen #### Finish the installation [#finish-the-installation] The installer should continue installing AgentOne. After each step completes, simply click `Next`. When the installer is finished, you'll see a `Finish` button and two options: * Create desktop shortcut * Launch AgentOne We recommend leaving both boxes checked and clicking `Finish`. ### Other Problems [#other-problems] Having a different issue? [Join our Discord server for live support!](https://www.agent-one.dev/discord) # Account and Sync The `Account` settings section covers signing in, managing your plan, syncing settings, and personalizing your experience with your name, AI instructions, and memory. ## Topics [#topics] Sign in, view plan information, and manage billing. Understand what sync does and how to enable it. Set your name and add AI instructions. # Profile and Instructions The **Profile & Instructions** card in `Settings` -> `Account` lets you personalize how AgentOne addresses you and how the AI responds across all your chats. ## Your Name [#your-name] The **Your Name** field sets the name AgentOne uses when it refers to you in conversation. This is the same name you set during [onboarding](/docs/desktop-app/getting-started/onboarding) and can be updated here at any time. The name is stored locally and, if [sync is enabled](/docs/desktop-app/account-and-sync/sync-settings), synchronized across your signed-in devices. ## AI Instructions [#ai-instructions] The **AI Instructions** field lets you add a persistent system-level instruction that AgentOne prepends to every conversation. Think of it as a standing note to the AI about how you want it to behave. Useful things to put here: * **Tone preferences**: "Respond concisely. Avoid unnecessary preamble." * **Language preferences**: "Use British English spelling." * **Formatting preferences**: "Always use fenced code blocks for code. Never use inline code for multi-line snippets." * **Domain context**: "I am a backend developer working primarily in Go and PostgreSQL." * **Response style**: "When I ask for an explanation, assume I have intermediate knowledge - no need to explain basic concepts." These instructions apply globally to every new chat. For one-off instructions that only apply to a specific conversation, put them in the message or the chat itself rather than here. ### Character Limit [#character-limit] The instructions field has a character limit. A live character count is shown below the field so you can see how much space you have used. Keep instructions focused - longer is not always better, since overly long system prompts can sometimes reduce model effectiveness. ## Memory [#memory] The **Memory** section lets you store persistent facts about yourself that the AI remembers across every conversation. Unlike AI Instructions, which are fixed, memories can be added, removed, or updated by the AI automatically during chats. Each memory entry is a short text string (up to 500 characters), and you can have up to 100 entries total. Memories sync across your devices when settings sync is enabled. See [Memory](/docs/desktop-app/chats/memory) for full details. ## Related [#related] * [Sign In and Plan](/docs/desktop-app/account-and-sync/sign-in-and-plan) - account status and plan details. * [Sync Settings](/docs/desktop-app/account-and-sync/sync-settings) - sync your settings including name across devices. * [Memory](/docs/desktop-app/chats/memory) - persistent facts the AI remembers across conversations. * [Onboarding](/docs/desktop-app/getting-started/onboarding) - where your name is first set. # Sign In and Plan The `Account` section in `Settings` shows your sign-in status, plan information, and access controls. If you skipped signing in during [onboarding](/docs/desktop-app/getting-started/onboarding), you can sign in from here at any time. ## Signing In [#signing-in] Click **Sign In** in the Account section. AgentOne opens the sign-in flow in a browser window. After completing it, the app refreshes and loads your account information. If you do not have an AgentOne account yet, you can create one during the sign-in flow. ## Plan and Usage [#plan-and-usage] Once signed in, the **Plan & Usage** card shows: * Your current plan name: Free, Pro, Ultra, or Hyper. * Renewal date for active subscriptions. * Credit usage progress for the current billing period. * Remaining credits. This is especially useful for understanding how much of your AgentOne-hosted model quota remains. If you are exclusively using [your own API keys with built-in or custom providers](/docs/guides/providers/built-in-providers), this section is less relevant since your usage is tracked directly by those providers. ## Account Actions [#account-actions] Depending on your account and plan state, AgentOne may show buttons for: * **Change plan** - opens the billing portal for Free accounts. * **Manage subscription** - opens the billing portal for paid accounts. * **Pricing Details** - opens the current plan comparison. * **Account Dashboard** - opens your account overview. Current monthly credit allowances are 100 on Free, 1,000 on Pro, 5,000 on Ultra, and 75,000 on Hyper. Plan prices and included beta features can change; use **Pricing Details** for the current comparison before upgrading. ## Hiding AgentOne Models [#hiding-agentone-models] In the **Sync & Access** card, signed-in users can toggle **Hide AgentOne models** to remove AgentOne-hosted models from the [model selector](/docs/guides/providers/model-selector). This is useful if you prefer to work exclusively with providers you manage yourself and want to keep the model list clean. ## Signing Out [#signing-out] Signing out removes your account session from the app. Your locally stored providers, API keys, and chats are not affected - they stay on your device. ## Related [#related] * [Sync Settings](/docs/desktop-app/account-and-sync/sync-settings) - what gets synced when you are signed in. * [Profile and Instructions](/docs/desktop-app/account-and-sync/profile-and-instructions) - set your name and AI instructions. * [Onboarding](/docs/desktop-app/getting-started/onboarding) - how the sign-in choice works during first run. # Sync Settings AgentOne can synchronize your app settings across multiple devices when you are signed in. This means the appearance, chat behavior, and performance preferences you configure on one machine are reflected on others. ## Enabling Sync [#enabling-sync] 1. Sign in to your AgentOne account. See [Sign In and Plan](/docs/desktop-app/account-and-sync/sign-in-and-plan) if you have not done this yet. 2. Open `Settings` -> `Account`. 3. In the **Sync & Access** card, toggle **Synchronize my settings** on. If you are not signed in, the toggle is disabled and greyed out. ## What Sync Covers [#what-sync-covers] Settings sync currently covers **app preferences** - things like your [appearance settings](/docs/desktop-app/settings/appearance), [chat settings](/docs/desktop-app/settings/chat-settings), [performance settings](/docs/desktop-app/settings/performance), and similar options. ## What Sync Does Not Cover [#what-sync-does-not-cover] * **Chat history** - your conversations are stored locally and are not synced between devices. Sync for chats is a planned future feature. * **API keys** - locally stored provider API keys are not synced to keep them on your device only. Encrypted key sync is a planned future feature. * **Extension configurations** - installed extensions and their settings are not currently synced. This means if you set up providers on one machine, you will need to set them up again on a second machine even with sync enabled. ## Sync Across Devices [#sync-across-devices] To benefit from sync, sign in on each device with the same AgentOne account and enable the **Synchronize my settings** toggle on each one. Changes to synced settings on any device will propagate to others. The desktop app refreshes synchronized settings about once per hour. A change made on another device may therefore take time to appear automatically. ## Related [#related] * [Sign In and Plan](/docs/desktop-app/account-and-sync/sign-in-and-plan) - sign in to unlock sync. * [Profile and Instructions](/docs/desktop-app/account-and-sync/profile-and-instructions) - your name and AI instructions. * [Appearance](/docs/desktop-app/settings/appearance) - the settings that sync covers. # Attachments AgentOne lets you attach files directly from the composer. ## Ways To Add Files [#ways-to-add-files] * click the paperclip button * drag files into the composer * paste files from your clipboard ## Supported File Types [#supported-file-types] AgentOne accepts many common file types, including: * images * text files * PDFs * videos * common code files such as `js`, `ts`, `tsx`, `py`, `rs`, `go`, `java`, and more ## Remove An Attachment [#remove-an-attachment] Attached files appear above the composer. Remove one before sending if needed. ## Drag A Chat Into Another Chat [#drag-a-chat-into-another-chat] You can drag a chat from the sidebar into the composer. When you do, AgentOne exports that chat into a file-like attachment and adds it to the current draft. This is useful when you want one conversation to reference another. ## Drag-And-Drop Overlay [#drag-and-drop-overlay] When you drag a file or chat over the composer, AgentOne shows a drop target that says `Drop files or chats to attach`. ## When Attachments Are Disabled [#when-attachments-are-disabled] The attach button is unavailable when: * no model is available * a response is already in progress * tool approval is blocking message submission Composer showing several attached files and the drag-and-drop overlay that says Drop files or chats to attach. # Branch Conversations Branching lets you fork a conversation from a specific point. The original chat stays exactly as it was - you get a new, independent chat that starts with the same context up to and including the message you branched from. ## How to Branch [#how-to-branch] 1. Hover over any message in the chat to reveal the [message action row](/docs/desktop-app/chats/message-actions). 2. Click **Branch conversation**. AgentOne creates a new chat containing all messages up to and including the one you branched from, opens it, and adds a branch icon to the new chat in the sidebar. Sidebar showing an original chat and a branched chat below it with a branch icon, both visible in the recent chats list. ## Why Branch Instead of Edit? [#why-branch-instead-of-edit] Branching and editing both let you explore alternate paths, but they serve different purposes: * **Edit a message** when you want to correct something and continue in the same chat thread. The edit replaces the original message in place. * **Branch** when you want to try a completely different direction while keeping the original thread intact and unmodified. After branching you have two separate chats, and you can freely continue both. Branching is especially useful when you have invested significant context in a long conversation and want to test an alternate prompt, a different framing of a question, or a different model without risking the original work. ## Finding Branched Chats [#finding-branched-chats] Branched chats appear in the sidebar with a branch icon next to their title. They are otherwise full chats - you can rename them, export them, delete them, and continue the conversation just like any other chat. ## Related [#related] * [Message Actions](/docs/desktop-app/chats/message-actions) - the full set of per-message actions. * [Edit Messages](/docs/desktop-app/chats/editing-messages) - modify messages in place with optional regeneration. * [Chat Sidebar](/docs/desktop-app/chats/chat-sidebar) - navigate between chats including branched ones. # Chat Sidebar The sidebar is the navigation hub on the left side of the [desktop layout](/docs/desktop-app/getting-started/desktop-layout). Every chat you have ever started lives here, organized with the most recent at the top. Sidebar showing a list of recent chats with titles, one selected chat highlighted, and the New Chat button and Settings button visible. ## Creating Chats [#creating-chats] Click **New Chat** at the top of the sidebar, or press `Ctrl+N` from anywhere in the app, to open a fresh conversation. The new chat becomes active immediately. ## Browsing Chat History [#browsing-chat-history] The sidebar lists your chats in reverse chronological order. Each row shows: * The **chat title** (auto-generated from the conversation, or set manually). * A **status indicator** while a response is in progress. * A **branch icon** if the chat was created by branching from another conversation. See [Branch Conversations](/docs/desktop-app/chats/branching-conversations). * A **search snippet** when you are viewing content search results. Clicking a chat opens it in the main area. ## Per-Chat Actions [#per-chat-actions] Every chat row has a `...` menu (also accessible by right-clicking the row). The menu includes: * **Change Title** - rename the chat to whatever you want. * **Export Chat** - download the chat as a JSON file. See [Exports and Deletion](/docs/desktop-app/chats/exports-and-deletion). * **Delete Chat** - permanently remove the chat. * **Select Chat** - enter selection mode for this chat. ## Selection Mode [#selection-mode] Selection mode lets you manage multiple chats at once. Enter it by choosing **Select Chat** from the `...` menu, or by Shift-clicking any chat row. While in selection mode you can: * **Select All** or **Deselect All** with one click. * **Bulk export** - download all selected chats as a single JSON file. * **Bulk delete** - delete all selected chats at once (with a confirmation prompt). Exit selection mode by clicking the cancel button or pressing Escape. Sidebar in selection mode showing several selected chats with check marks, the Select All button, bulk export, and bulk delete controls at the bottom. ## Collapsing the Sidebar [#collapsing-the-sidebar] Press `Ctrl+B` to collapse the sidebar. When collapsed, AgentOne shows a compact strip of icon buttons - enough to open the sidebar, search, or start a new chat without needing the full sidebar open. Whether those buttons appear in a **Row** or **Column** layout is configurable in `Settings` -> `Appearance` -> `Collapsed Sidebar Layout`. On narrower windows, the sidebar becomes a drawer instead of a pinned panel, so it does not crowd the chat area. ## Opening Settings [#opening-settings] The **Settings** button at the bottom of the sidebar opens the settings view. You can also reach it with `Ctrl+,`. ## Related [#related] * [Search Chats](/docs/desktop-app/chats/searching-chats) - find chats by title or message content. * [Exports and Deletion](/docs/desktop-app/chats/exports-and-deletion) - export and delete chats individually or in bulk. * [Keyboard Shortcuts](/docs/desktop-app/shortcuts-and-links/keyboard-shortcuts) - all sidebar-relevant shortcuts. # Edit Messages AgentOne lets you edit any message in the conversation - both user messages and assistant messages - directly from the chat view. This is useful for correcting a prompt, adjusting phrasing, or manually fixing an assistant response. ## Editing a User Message [#editing-a-user-message] 1. Hover over a user message to reveal the [message action row](/docs/desktop-app/chats/message-actions). 2. Click **Edit message** (pencil icon). 3. Modify the text in the inline editor. 4. Choose whether to enable **Regenerate when Saved**. 5. Click **Save** to apply, or **Cancel** to discard. ### Regenerate when Saved [#regenerate-when-saved] When this toggle is on, AgentOne discards all messages after the edited message and generates a fresh response from the updated context. This is the most common use case - you changed your prompt and want a new answer. When it is off, the edit is saved as-is without triggering a new response. The conversation history reflects your change, but the subsequent messages are left in place. This can be useful for manually correcting a typo in your own message without invalidating a useful answer. The default state of this toggle is controlled by `Settings` -> `Chats` -> `Regenerate on Save`. ## Editing an Assistant Message [#editing-an-assistant-message] Assistant messages can also be edited. Open the editor the same way - hover to see the action row, then click the edit icon. Editing an assistant message and saving **without** regeneration replaces the stored content with whatever you typed. This is useful if you want to clean up or annotate the response for your own reference. If you save **with** regeneration, AgentOne discards the assistant message and asks the model for a new one. ## Canceling [#canceling] Click **Cancel** at any point in the editor to discard your changes. The original message is preserved unchanged. ## Related [#related] * [Message Actions](/docs/desktop-app/chats/message-actions) - all per-message actions including regenerate and branch. * [Branch Conversations](/docs/desktop-app/chats/branching-conversations) - fork the chat instead of editing in place. * [Chat Settings](/docs/desktop-app/settings/chat-settings) - set the default for Regenerate on Save. # Exports and Deletion AgentOne gives you both single-chat and bulk management actions. ## Export A Single Chat [#export-a-single-chat] 1. Open the chat menu. 2. Click `Export Chat`. 3. Choose `Download as JSON`. AgentOne prompts you to choose where to save the exported file. ## Bulk Export [#bulk-export] 1. Enter selection mode. 2. Select one or more chats. 3. Click the bulk export button. 4. Save the combined JSON export file. ## Delete A Single Chat [#delete-a-single-chat] 1. Open the chat menu. 2. Click `Delete Chat`. 3. Confirm deletion. If you delete the currently open chat, AgentOne returns you to a blank chat view. ## Bulk Delete [#bulk-delete] 1. Enter selection mode. 2. Select the chats you want to remove. 3. Click the bulk delete button. 4. Confirm deletion. Chat deletion cannot be undone from the app. # Chats AgentOne organizes your work into chats. Each chat can have its own model, model configuration, title, and message history. ## Topics [#topics] Browse chats, create new ones, and use selection mode. Search titles or message content, including raw FTS5 syntax. Add files and drag existing chats into the composer. Copy, edit, regenerate, and branch from messages. Export chats, bulk export, delete chats, and bulk delete. Store persistent facts the AI remembers across conversations. Have AgentOne read messages out loud with text-to-speech. # Memory AgentOne can remember things about you across chat sessions. Memories are short, concise facts that the AI sees as context in every conversation - so you do not have to repeat yourself. ## How Memory Works [#how-memory-works] Memories are stored as a list of short text entries. Each entry is a single fact or preference, like "I prefer concise technical answers" or "I work primarily in Go and PostgreSQL." When you start a new chat, the AI reads your current memories and takes them into account when responding. You never have to re-explain the same preferences. ## Managing Memories [#managing-memories] You can view and edit memories in `Settings` -> `Account` -> **Profile & Instructions** -> **Memory**. From there you can: * **Add** a new memory entry by clicking the `+` button. * **Edit** any existing memory entry by typing in its field. * **Delete** a memory entry by clicking the `x` button next to it. ### Limits [#limits] * **100 entries maximum** across all memories. * **500 characters per entry**. A character counter shows how much space you have left. ## The Memory AI Tool [#the-memory-ai-tool] The AI can also manage memories automatically. When the **Memory** built-in tool is enabled (it is on by default), the model can add, remove, or replace memory entries during a conversation. For example, if you say "I prefer British English spelling," the model can store that as a memory entry so it remembers in future chats. You can disable or require approval for this tool in `Settings` -> `Extensions` -> **Built-in extensions**. ## Sync [#sync] If you have [settings sync](/docs/desktop-app/account-and-sync/sync-settings) enabled, your memories are synchronized across all your signed-in devices. ## Related [#related] * [Profile & Instructions](/docs/desktop-app/account-and-sync/profile-and-instructions) - manage memory alongside your name and AI instructions. * [Built-in Tools](/docs/guides/extensions/built-in-tools) - the Memory tool and other built-in tools. * [Sync Settings](/docs/desktop-app/account-and-sync/sync-settings) - sync memories across devices. # Message Actions Every message in a chat - both yours and the model's - can be acted on directly. The **message action row** appears on hover (or always, depending on your settings) and gives you a set of quick actions without needing to navigate away. A chat with a user message and an assistant message, both showing the action row with Copy, Edit, Branch, and Regenerate buttons. ## Showing the Action Row [#showing-the-action-row] By default, the action row appears when you hover over a message. You can change this behavior in `Settings` -> `Chats` -> `Message Action Row`: * **Show on hover** (default) - the row appears when the mouse is over the message. * **Always show** - the row is permanently visible for every message. * **Never show** - the row is hidden. The underlying actions still work where the UI exposes them in other ways (for example, the edit pencil icon still appears on focus for some message types). ## Available Actions [#available-actions] ### Copy Message [#copy-message] Copies the full text of the message to your clipboard. For assistant messages, this copies the raw markdown content. ### Edit Message [#edit-message] Opens the message text in an inline editor. You can change the content and then: * Click **Save** to apply the change. * Toggle **Regenerate when Saved** to control whether AgentOne regenerates the conversation from that point after saving. * Click **Cancel** to discard changes. Whether **Regenerate when Saved** is on or off by default is controlled by `Settings` -> `Chats` -> `Regenerate on Save`. See [Edit Messages](/docs/desktop-app/chats/editing-messages) for more. Both user messages and assistant messages can be edited. Editing an assistant message and saving without regeneration replaces the stored content but does not send anything new to the model. ### Regenerate Response [#regenerate-response] Available on assistant messages. Sends the current conversation state back to the model and asks for a new response from that point, discarding the previous assistant message. Useful when you are unhappy with an answer and want a fresh attempt. ### Branch Conversation [#branch-conversation] Creates a new chat that starts from this message's context. The original chat is unchanged. See [Branch Conversations](/docs/desktop-app/chats/branching-conversations) for the full explanation of when and why to branch. ### Read Aloud [#read-aloud] Appears on assistant messages only. Plays the message through your speakers using a text-to-speech provider you configure in `Settings` -> `Providers`. Click the speaker icon to start, click again or tap the stop button to interrupt. Only shows up when a [text-to-speech provider](/docs/desktop-app/chats/reading-aloud) is set up with an API key. ## Related [#related] * [Reading Aloud](/docs/desktop-app/chats/reading-aloud) - configure text-to-speech providers. * [Editing Messages](/docs/desktop-app/chats/editing-messages) - full detail on the edit flow and the regenerate-on-save setting. * [Branch Conversations](/docs/desktop-app/chats/branching-conversations) - fork a chat to explore a different direction. * [Chat Settings](/docs/desktop-app/settings/chat-settings) - configure action row visibility and default regenerate behavior. # Reading Aloud AgentOne can read assistant messages out loud. You pick a voice provider, configure how it sounds, then tap the speaker icon on any response to hear it. ## How It Works [#how-it-works] The read aloud button appears on every assistant message when a text-to-speech provider is configured. Click it and AgentOne streams the message through your speakers. Click it again or tap the stop button to interrupt. Reading aloud uses its own API keys and provider selection - it's separate from the provider you use for chat. ## Setting It Up [#setting-it-up] 1. Open `Settings` -> `Providers`. 2. Scroll to the `Text-to-Speech Providers` card. 3. Choose a provider from the dropdown. 4. Pick a voice model. 5. Enter the provider's API key. 6. Adjust the voice settings to your liking. Once a provider and API key are saved, the speaker icon shows up on assistant messages. ### Supported Providers [#supported-providers] | Provider | What You Get | | ------------- | ---------------------------------------------------------------------------------------------------------------------- | | OpenAI | TTS models (`tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`). 13 voices, speech rate, and instructions for how it should sound. | | Google Gemini | Gemini TTS preview models, 30 preset voices, and speech rate. The default voice is `Kore`. | | ElevenLabs | ElevenLabs voice models. Voice ID, speech rate, language code, stability, style, and speaker boost. | | LMNT | Lightning-fast speech models (`aurora`, `blizzard`). Voice, language, speed, and conversational mode. | | Hume | Expressive speech with a single model. Voice ID, speed, and instructions for how it should sound. | Each provider needs its own API key, stored the same way as chat provider keys. ### Voice Settings [#voice-settings] The options available depend on which provider you pick: * **Speech Rate** - how fast the voice reads. Available on all providers. * **Voice** - which voice to use. OpenAI and Google Gemini have preset lists; ElevenLabs, LMNT, and Hume use voice IDs from their platforms. * **Instructions** (OpenAI, Hume) - tell the voice how to sound, like "Speak casually" or "Emphasize technical terms." * **Stability / Style / Voice Match** (ElevenLabs) - fine-tune the delivery. ## Using It [#using-it] Once configured, hover over any assistant message and click the speaker icon. The icon changes to a stop button while audio is playing. Click it again to stop. Reading aloud stops automatically when the message finishes. You can start reading a different message while another is playing - it stops the first one and starts the new one. ## Related [#related] * [Message Actions](/docs/desktop-app/chats/message-actions) - the full set of per-message actions. * [Built-in Providers](/docs/guides/providers/built-in-providers) - how chat provider keys work the same way. # Search Chats AgentOne includes chat search in both the sidebar and the chat search dialog. ## Open Search [#open-search] You can search by: * clicking the search button in the sidebar * using `Ctrl+K` If the sidebar is collapsed, `Ctrl+K` opens the search dialog. ## Search Modes [#search-modes] The search controls let you switch between: * title search * content search with `Search content` When content search is enabled, AgentOne searches your chat messages instead of only chat titles. ## Raw FTS5 Syntax [#raw-fts5-syntax] When `Search content` is enabled, you can also enable `Raw FTS5 syntax`. This is meant for advanced search queries when you want more direct control over the underlying full-text search behavior. If you do not need advanced operators, leave this off and use normal search phrases. ## Search Results [#search-results] Content search results can show a snippet from the matching message with highlighted text. If nothing matches, AgentOne shows a `No results for ...` message. ## Tips [#tips] * Use title search when you already know roughly what the chat was called * Use content search when you remember something inside the conversation * If a raw query is not working the way you expect, turn off `Raw FTS5 syntax` and retry with plain language Search UI showing the search field, Search content enabled, Raw FTS5 syntax option, and result snippets with highlighted matches. # Desktop Layout The AgentOne desktop app has three main areas: the **sidebar**, the **main chat area**, and the **composer**. Understanding where everything lives makes navigating the app much faster. Full app window with the three main areas annotated - sidebar on the left, main chat area in the center, and composer at the bottom. ## Sidebar [#sidebar] The sidebar runs along the left side of the app. It is your navigation hub for everything chat-related. From the sidebar you can: * Click **New Chat** (or press `Ctrl+N`) to start a fresh conversation. * Browse your recent chat history, organized by recency. * Search chats by title or message content with the search button or `Ctrl+K`. * Open the **Settings** panel from the bottom of the sidebar. Each chat row shows its title and, when applicable, a status indicator or branch icon. Right-clicking a chat (or clicking its `...` menu) gives you actions like rename, export, and delete. For full details on working with the sidebar and managing chats, see [Chat Sidebar](/docs/desktop-app/chats/chat-sidebar). ### Collapsing the Sidebar [#collapsing-the-sidebar] Press `Ctrl+B` to collapse the sidebar. When collapsed, a small set of icon buttons stays visible so you can still create new chats and search without opening the sidebar. You can choose whether these buttons appear in a row or column in `Settings` -> `Appearance` -> `Collapsed Sidebar Layout`. On narrower windows, the sidebar becomes a drawer that slides in when needed rather than staying pinned. ## Main Chat Area [#main-chat-area] The center of the app is where your conversation lives. It shows: * The full message history for the current chat, scrollable from top to bottom. * **Streaming responses** as the model generates them, with a stop button to interrupt. * **Tool activity** - when an [extension](/docs/guides/extensions) runs during a response, its actions appear inline as collapsible items so you can see exactly what the model did. * **Message action rows** - hover over a message (or always show them, depending on your settings) to access copy, edit, branch, and regenerate actions. See [Message Actions](/docs/desktop-app/chats/message-actions). * **Message Navigation Rail** - on medium and larger layouts, previews messages on the right and lets you jump through the conversation. It can be hidden in `Settings` -> `Chats`. ## Composer [#composer] The composer sits at the bottom of the chat area. It is where you type messages and configure the current chat. It contains: * **Message input** - type your message here. The placeholder says `Ask anything...`. Press your configured submit key (`Enter` or `Ctrl+Enter`) to send. * **Attachment button** - click the paperclip icon to attach files, or drag files directly into the composer. See [Attachments](/docs/desktop-app/chats/attachments). * **Model selector** - the pill-shaped button showing the current provider and model name. Click it to switch models. See [Model Selector](/docs/guides/providers/model-selector). * **Model config button** - next to the model selector. Click it to adjust temperature, max tokens, and other per-chat parameters. See [Model Config](/docs/guides/providers/model-config). * **Tool Behavior** - inside Model Config, choose whether tools use their normal approvals, always ask, run without approval, or stay disabled. * **Send / Stop button** - sends your message when idle; turns into a stop button during generation. ## Settings [#settings] Clicking **Settings** in the sidebar opens the settings view. It is organized into sections: | Section | What it controls | | -------------------- | ------------------------------------------------------------- | | `Account` | Sign-in, plan, sync, name, AI instructions, memory | | `Appearance` | Theme, colors, font, input style, sidebar layout | | `Chats` | Notifications, submit key, streaming, chat titles, sort order | | `Extensions` | Built-in tools and MCP server management | | `Keyboard Shortcuts` | Customize keybindings for common actions | | `Performance` | Rendering limits and virtualization | | `Providers` | Cloud, local, and custom provider setup, plus text-to-speech | | `Help & Updates` | App version, updates, release notes, analytics | See [Settings](/docs/desktop-app/settings) for the full breakdown of each section. ## Keyboard Shortcuts [#keyboard-shortcuts] You can navigate the entire app without touching the mouse. See [Keyboard Shortcuts](/docs/desktop-app/shortcuts-and-links/keyboard-shortcuts) for the full list. # Connect Your First Provider AgentOne needs at least one enabled model provider before it can answer messages. If you already [signed in with your AgentOne account](/docs/desktop-app/account-and-sync/sign-in-and-plan), you can skip this tutorial entirely and use AgentOne right away. ## Your Options [#your-options] You can start with any of these: * A built-in cloud provider such as OpenAI, Anthropic, Google, Groq, or Mistral * A built-in local provider such as Ollama or LM Studio * A custom OpenAI-compatible provider ## Quickest Setup Paths [#quickest-setup-paths] ### Option 1: Use a built-in cloud provider [#option-1-use-a-built-in-cloud-provider] 1. Open `Settings`. 2. Click `Providers`. 3. Expand a provider under `Built-in Providers`. 4. Toggle it on. 5. Paste your API key. 6. Save the key. ### Option 2: Use Ollama or LM Studio [#option-2-use-ollama-or-lm-studio] 1. Make sure the local runtime is already installed and running. 2. Open `Settings` -> `Providers`. 3. Find the provider under `Local Providers`. 4. Keep it enabled. 5. Confirm the `Base URL` is correct. 6. Wait for models to auto-detect, or click `Auto` in the Models section. ### Option 3: Add a custom provider [#option-3-add-a-custom-provider] 1. Open `Settings` -> `Providers`. 2. In `Custom Providers`, click `Add Provider`. 3. Choose `OpenAI Compatible`. 4. Enter a name, base URL, optional API key, and one or more models. 5. Click `Add Provider`. ## How To Tell It Worked [#how-to-tell-it-worked] After setup: * the provider stays enabled * at least one model appears in the model selector in chat * the composer no longer shows the no-model warning For full provider setup details, continue to [Providers and Models troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # Getting Started If you have already installed AgentOne, the fastest path is: 1. Open the app. 2. Finish onboarding. 3. Sign in or continue without an account. 4. Enable at least one provider. 5. Start a chat and send your first message. ## Start Here [#start-here] See every first-run step and what each choice means. Connect a model provider so the app can answer messages. Start chatting, attach files, choose a model, and stop a response. Learn what is in the sidebar, main chat area, and settings pages. ## Before You Begin [#before-you-begin] 1. Install AgentOne from the [Installation Guide](/docs/installation) 2. Make sure you have either: * an AgentOne account, or * an API key for at least one provider, or * a local model runtime such as Ollama or LM Studio AgentOne can open without any providers configured, but it will not be able to answer messages until at least one model is available. # Onboarding The first time you open AgentOne, you go through a short onboarding flow. It takes under two minutes and sets up the two things the app needs to function: your name and at least one model provider. ## Step 1: Splash Screen [#step-1-splash-screen] AgentOne opens with a splash screen and a **Get Started** button. Click it to begin. ## Step 2: Choose Your Name [#step-2-choose-your-name] AgentOne asks **"What should I call you?"** Enter the name you want AgentOne to use when it addresses you. This is stored locally and can be changed later in `Settings` -> `Account` -> `Profile & Instructions`. It is also used as the default display name when you sign in. ## Step 3: Account or API Keys [#step-3-account-or-api-keys] This is the most important choice in onboarding. You have two paths: ### Sign in with an AgentOne account [#sign-in-with-an-agentone-account] Signing in gives you access to account-based features: * **AgentOne models** - hosted models you can use without managing API keys yourself. * **Settings sync** - keep your preferences in sync across multiple devices. * **Billing and plan management** - view your usage and manage your subscription from inside the app. If you choose this path, the app walks you through sign-in or account creation before continuing. ### Continue without an account [#continue-without-an-account] If you prefer to bring your own API keys, choose **"Or continue without an account"**. AgentOne takes you directly to the provider setup step so you can enable your own providers. In this mode, your API keys are stored encrypted on your device only - they are never sent to AgentOne's servers. You can still sign in later from `Settings` -> `Account` if you change your mind. ## Step 4: Provider Setup [#step-4-provider-setup] If you chose the bring-your-own-key path (or if your account does not include hosted models), onboarding shows you the same provider controls that live in `Settings` -> `Providers`. You can enable a built-in cloud provider, configure a local provider like Ollama, or add a custom provider. You need at least one enabled provider with at least one model before onboarding lets you continue. For a detailed guide to each provider type, see: * [Built-in Providers](/docs/guides/providers/built-in-providers) - OpenAI, Anthropic, Google, and more. * [Local Providers](/docs/guides/providers/local-providers) - Ollama and LM Studio. * [Custom Providers](/docs/guides/providers/custom) - any OpenAI-compatible endpoint. ## Step 5: Welcome Screen [#step-5-welcome-screen] The final screen confirms setup is complete and offers three options: * **Launch AgentOne** - go to the main chat screen. * **Browse Documentation** - open the docs site (you are here!). * **Take the Tutorial** - marked as coming soon. Click **Launch AgentOne** to open the app. ## After Onboarding [#after-onboarding] Onboarding only runs once. After you complete it, you go directly to the main chat interface on every subsequent launch. You can revisit and change any of the settings from onboarding at any time: * **Name**: `Settings` -> `Account` -> `Profile & Instructions` * **Providers**: `Settings` -> `Providers` * **Account**: `Settings` -> `Account` # Your First Chat Once a [provider is set up](/docs/desktop-app/getting-started/first-provider) and at least one model is available, you are ready to chat. ## Start a New Chat [#start-a-new-chat] Click **New Chat** in the sidebar or press `Ctrl+N`. AgentOne opens a fresh conversation with an empty-state greeting such as `What's on your mind?` or `Ask me anything.` ## Pick a Model [#pick-a-model] At the bottom of the chat window, the [model selector](/docs/guides/providers/model-selector) shows the currently active provider and model. Click it to open the full model list, which is grouped by provider. Type in the search field to filter quickly. The model you choose applies to this chat. You can switch models at any point in the conversation - changes take effect on the next message you send. ## Write and Send Your Message [#write-and-send-your-message] Type in the `Ask anything...` input field. By default, pressing `Enter` sends the message. If you prefer `Ctrl+Enter`, change this in `Settings` -> `Chats` -> `Submit Key`. AgentOne streams the response token by token so you can start reading immediately. A stop button appears in the composer while the model is generating - click it to interrupt the response at any time. ## Attach Files [#attach-files] The composer supports several ways to add files to your message: * **Paperclip button** - click it to open a file picker. * **Drag and drop** - drag files from your file manager directly onto the composer. A drop target labeled `Drop files or chats to attach` appears when you hover. * **Paste** - paste an image or file from your clipboard. You can also drag an existing chat from the sidebar into the composer. AgentOne exports that chat into an attachment so the current conversation can reference it - useful when you want context from a previous conversation without switching away. For more detail on supported file types and attachment behavior, see [Attachments](/docs/desktop-app/chats/attachments). ## Tune the Chat [#tune-the-chat] Next to the model selector is the **model config button**. Click it to open the [Model Config](/docs/guides/providers/model-config) panel where you can adjust: * **Temperature** - randomness of the output. * **Max Tokens** - cap on response length. * **Top P, Top K** - alternative sampling controls. * **Max Steps** - relevant for [extension](/docs/guides/extensions)-heavy workflows. * And more. These settings apply only to the current chat and do not affect other conversations unless you change them on the `New Chat` screen. ## Message Actions [#message-actions] After the model responds, hover over any message to see the action row: * **Copy message** - copies the message content. * **Regenerate response** - generates a fresh answer from the same conversation state. * **Edit message** - edit any message, including assistant messages, and optionally regenerate from that point. If you don't want the assistant messages to be regenerated when you edit your message, click the dropdown arrow next to the `Save` button and ensure `Regenerate when saved` is not checked. * **Branch conversation** - fork the chat at that message into a new conversation. When a [text-to-speech provider](/docs/desktop-app/chats/reading-aloud) is set up, a speaker icon also appears on assistant messages for reading them out loud. See [Message Actions](/docs/desktop-app/chats/message-actions) for full details. ## What Comes Next [#what-comes-next] * [Search Chats](/docs/desktop-app/chats/searching-chats) - find any past conversation. * [Extensions](/docs/guides/extensions) - give the model tools like web search, file editing, and command execution. * [Reading Aloud](/docs/desktop-app/chats/reading-aloud) - listen to messages with text-to-speech. * [Settings](/docs/desktop-app/settings) - customize how the app looks and behaves. # Appearance The `Appearance` section in `Settings` controls the visual presentation of the entire app. Changes take effect immediately - there is no save button needed. Appearance settings page showing the theme picker, primary color swatches, font selector, and input style options side by side. ## General Look and Feel [#general-look-and-feel] ### Theme [#theme] Choose between **Light**, **Dark**, or your system's default (**System**). The system option follows your OS-level dark/light mode preference and switches automatically when you change it. ### Primary Color [#primary-color] Sets the accent color used for highlights, buttons, and active states throughout the app. Several preset colors are available, plus the ability to enter a custom hex value. ### Tint [#tint] Adds a subtle color tint to the app's background surfaces. Useful when you want a warmer or cooler overall feel without changing the primary color. ### Tint Strength [#tint-strength] Controls how strong the tint effect is, from barely visible to quite pronounced. Set it to zero to remove the tint entirely. ### Font [#font] Choose from several bundled font options for the app's text. The font affects the entire interface, not just the chat area. ### Roundness [#roundness] Adjusts the border radius of UI elements from sharp corners to very rounded ones. A matter of personal preference. ### Text Scale [#text-scale] Scales the base font size up or down. Useful for accessibility or when running AgentOne on a high-density display. ## Chat Background [#chat-background] Add a background image behind the main chat area. Pick from built-in presets or use your own image for a more personalized workspace. ### Preset Images [#preset-images] Choose from several built-in images: **Abstract**, **Morning Mist**, **Night Sky**, **Island**, **Aurora**, **Valley**, **Forest**, **Ocean**, **Mountain**, and **Sunset**. You can also select **None** to remove the background entirely. ### Custom Images [#custom-images] Click **Add Custom** to select an image from your computer. Supported formats include PNG, JPG, JPEG, WebP, GIF, BMP, and AVIF. Custom images are stored locally and can be removed from the custom list at any time. ### Effects [#effects] Fine-tune how the background image appears behind your chat content: * **Opacity** - controls the tint overlay strength from transparent (0%) to heavily tinted (70%). * **Blur** - applies a smooth blur to the image from none (0px) up to a strong blur (20px). * **Dim** - darkens the image from none (0%) to significantly dimmed (70%). ### Position & Zoom [#position--zoom] Adjust where and how the image is displayed: * **X** - horizontal offset of the image from left (0%) to right (100%). * **Y** - vertical offset from top (0%) to bottom (100%). * **Zoom** - scales the image from its original size (100%) up to 200%. ### Background Shade [#background-shade] When a chat is open, a semi-transparent overlay sits between the background image and the chat content to keep text readable. The **Shade Opacity** slider controls how visible this overlay is, from completely transparent (0%) to fully opaque (100%). ## Chat Appearance [#chat-appearance] ### Markdown Highlighting [#markdown-highlighting] Controls whether code blocks in chat messages have syntax highlighting. If you chat primarily about non-code topics, turning this off can improve rendering performance on long chats. ### Input Style [#input-style] Two options for how the composer sits at the bottom of the chat: * **Docked** - the composer is flush with the bottom edge of the window, extending the full width. * **Floating** - the composer appears as a rounded panel floating above the bottom of the window, with space around it. ### Collapsed Sidebar Layout [#collapsed-sidebar-layout] When the sidebar is collapsed, a small set of quick-access buttons remains visible. This setting controls whether they appear in a horizontal **Row** or a vertical **Column**. ## Resets [#resets] Most individual appearance settings have a small reset button next to them that restores just that setting to its default value without touching the rest. ## Related [#related] * [Desktop Layout](/docs/desktop-app/getting-started/desktop-layout) - understand where the sidebar, chat area, and composer are. * [Chat Settings](/docs/desktop-app/settings/chat-settings) - markdown rendering, submit key, and streaming behavior. # Chat Settings The `Chats` section in `Settings` controls how conversations behave from input to output. These are global defaults - some can be overridden per-chat (like the submit key) while others affect all chats. ## Chat Behavior [#chat-behavior] ### Markdown Rendering [#markdown-rendering] Controls which messages render markdown formatting: * **All messages** - both your messages and assistant responses use markdown rendering. * **User messages only** - only your messages are rendered as markdown. * **Assistant messages only** - only assistant responses render markdown. * **No messages** - all messages display as plain text. Turn off markdown rendering for assistant messages if you are working with a model that produces a lot of raw text and the formatting feels distracting. ### Fix Streaming Markdown [#fix-streaming-markdown] When enabled (default), AgentOne repairs incomplete formatting while a response is still streaming. Disable it if you prefer to see the provider's raw partial markdown or want to remove its small rendering overhead. ### Completion Notification [#completion-notification] Choose when AgentOne shows a desktop notification when a response finishes: * **Always** - notify on every completed response. * **When window unfocused** - notify only when AgentOne is not the active window. This is useful when you submit a long task and switch to another app while waiting. * **Never** - no notifications. Note that OS-level notification permissions must be granted for notifications to appear. See [Notifications and Updates Troubleshooting](/docs/desktop-app/troubleshooting/notifications-and-updates) if notifications are not appearing. ### Message Action Row [#message-action-row] Controls when the per-message action buttons (copy, edit, regenerate, branch) are visible: * **Show on hover** - appears when you mouse over a message. * **Always show** - permanently visible on every message. * **Never show** - hidden from the normal row. See [Message Actions](/docs/desktop-app/chats/message-actions) for what each action does. ### Submit Key [#submit-key] Choose how you send messages: * **Enter** - press Enter to send, Shift+Enter for a newline. * **Ctrl+Enter** - press Ctrl+Enter to send, Enter for a newline. If you often write multi-line prompts, `Ctrl+Enter` prevents accidental sends. ### Regenerate on Save [#regenerate-on-save] Sets the default state of the **Regenerate when Saved** toggle that appears when editing a message. When this is on, saving a message edit automatically triggers a new response from that point in the conversation. See [Edit Messages](/docs/desktop-app/chats/editing-messages). ### Always Show Stop Button [#always-show-stop-button] When enabled, the stop button appears in the composer immediately after you submit a message - even during the brief moment before the model starts streaming. Useful if you frequently want to cancel responses right away. ### Chat Scroll to Bottom Button [#chat-scroll-to-bottom-button] Shows a button that quickly returns you to the latest message when you have scrolled up. It is enabled by default. ### Message Navigation Rail [#message-navigation-rail] Shows message previews on the right side of chats and lets you jump directly to a message. The rail marks messages currently in view, is enabled by default, and stays hidden in the compact layout. ### Chat Status Indicators [#chat-status-indicators] Shows or hides the small status indicator icons on chat rows in the sidebar while a response is generating. ### Chat Sort Order [#chat-sort-order] Controls how chats are ordered in the sidebar: * **Newest chats first** (default) - sorted by creation date. * **Recently updated first** - sorted by last activity. Useful when you revisit older chats and want the most recently active ones at the top. ## Streaming [#streaming] ### Extract Reasoning from Think Tags [#extract-reasoning-from-think-tags] When enabled (default), `...` blocks emitted by reasoning models like DeepSeek are automatically stripped from the response text and displayed as a collapsible reasoning section in the chat UI. This keeps the main response clean while still letting you inspect the model's chain of thought. This setting does not apply to past messages or models that do not emit reasoning tags. ### Smooth Stream [#smooth-stream] Enables a smoother, more fluid text streaming animation. If disabled, text appears in larger chunks as it arrives. ### Experimental Throttle [#experimental-throttle] Adds a configurable delay between streaming updates. Enable this if streaming feels too fast to read or causes high CPU usage on your machine. When enabled, a **Throttle Value** field appears where you can set the delay in milliseconds. ## Chat Titles [#chat-titles] Controls how AgentOne names new chats automatically. ### Generation Method [#generation-method] * **AI generated** - the model summarizes the first exchange and generates a title. Produces the most descriptive titles but requires a model call. * **First user message** - uses the text of your first message as the title, truncated to the character limit. * **First assistant message** - uses the beginning of the model's first response. * **Custom phrase** - uses a fixed phrase you specify for every new chat. ### Character Limit [#character-limit] Applies to AI-generated and message-based title methods. Titles longer than this limit are truncated. ### Max Tokens for AI Generation [#max-tokens-for-ai-generation] When using **AI generated** titles, this controls the maximum number of tokens the model can use for the title. Lower values produce shorter titles; higher values allow more descriptive ones. The default works well for most use cases. ### Custom Phrase and Fallback Phrase [#custom-phrase-and-fallback-phrase] When using `Custom phrase`, the **Custom Phrase** field sets the title for every new chat. The **Fallback Phrase** is used when the primary method fails (for example, if the AI title generation call times out). ## Related [#related] * [Appearance](/docs/desktop-app/settings/appearance) - visual customization including markdown highlighting. * [Message Actions](/docs/desktop-app/chats/message-actions) - the action row this section configures. * [Edit Messages](/docs/desktop-app/chats/editing-messages) - how Regenerate on Save works. # Help and Updates Open `Settings` -> `Help & Updates` for app version, updates, help links, and analytics controls. ## Updates [#updates] This page shows: * current version * update status * download progress when applicable Possible update states include: * `Check for updates` * `Checking for updates...` * `Automatic updates disabled` * `You're up to date` * `Update available` * `Downloading update...` * `Installing update...` * `Update failed` ## Update Actions [#update-actions] Depending on state, AgentOne can show: * `Check Now` * `Download & Install` * `Try Again` On platforms managed by an external package manager, the app may show `Automatic updates disabled` and tell you to update AgentOne through your software manager instead. ## Release Notes [#release-notes] AgentOne shows a `What's New in v...` dialog automatically when the app updates to a new version. You can also browse release notes from any previous version at any time. In the **Updates** card, expand the **Release notes** accordion and pick a version from the dropdown to read what changed in that release. ## Model List Updates [#model-list-updates] AgentOne's [AI Model Directory](https://models.agent-one.dev) can update independently of the desktop app, so newly released models do not require a full app update. AgentOne checks for a newer list at most once every 24 hours and saves the downloaded list locally. Use the **Model List Updates** section on this page to: * manually download the latest list * see how many providers and models were loaded * reset to the model list bundled with your installed app Resetting does not remove your provider keys or custom model overrides. ## Help Links [#help-links] The page includes links for: * bug reports * Discord help * the documentation site ## Usage Analytics [#usage-analytics] You can control whether AgentOne sends usage analytics from the desktop app. There are two related settings: * `Allow usage analytics` * `Associate analytics with my signed-in account` If analytics are fully off, the second setting is unavailable. # Settings Open `Settings` from the bottom of the sidebar. The settings view contains these sections: * `Account` * `Appearance` * `Chats` * `Extensions` * `Keyboard Shortcuts` * `Performance` * `Providers` * `Help & Updates` This part of the docs focuses on the settings that affect the app experience directly. Text-to-speech is configured through the `Providers` section - see [Reading Aloud](/docs/desktop-app/chats/reading-aloud) for details. ## Topics [#topics] Theme, primary color, tint, font, roundness, input style, and more. Notifications, action rows, submit key, streaming, and chat title behavior. Rendering limits, virtualization, and extension runtime controls. Customize keybindings for common actions. App updates, help links, and analytics preferences. # Keyboard Shortcuts The `Keyboard Shortcuts` section in `Settings` lets you rebind, disable, or tweak every keyboard shortcut in AgentOne. ## Customizing a Shortcut [#customizing-a-shortcut] Each shortcut shows its current keybinding and has two buttons: * **Edit** (pencil icon) - opens the shortcut editor where you can press a new key combination to rebind it. * **Reset** (restore icon) - restores the shortcut to its default binding. Greyed out when already using the default. ### Shortcut Editor [#shortcut-editor] When editing a shortcut, the dialog captures the next key combination you press. You can set any single modifier+key combination (for example, `Ctrl+Shift+M`). The editor also lets you toggle: * **Activate in input fields** - when on, this shortcut works even when you are typing in a text field. Off by default. * **Prevent default browser behavior** - when on, AgentOne intercepts the key combination before the desktop app performs the default action. On by default. ### Conflicts [#conflicts] If you set a shortcut that another action already uses, a warning appears in the editor. You can still save the new binding - the conflict is a reminder, not a blocker. The most recently saved binding wins. ## The Shortcuts [#the-shortcuts] | Action | Default | Description | | --------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | | Open Settings | `Ctrl+,` | Opens the settings panel from anywhere in the app. | | New Chat | `Ctrl+N` | Creates a new empty chat and focuses the input. | | Focus Chat Search | `Ctrl+K` | Focuses the sidebar search when open; opens the full-screen search dialog when sidebar is collapsed. | | Toggle Sidebar | `Ctrl+B` | Collapses or expands the sidebar. | | Focus Main Chat Input | `Ctrl+L` | Moves keyboard focus to the chat composer. | | Stop Response | `Shift+Esc` | Stops the current AI response. | ## Activate Shortcuts in Input Fields [#activate-shortcuts-in-input-fields] A global toggle at the top of the section controls whether shortcuts fire when you are typing in any text field. When enabled, you can use `Ctrl+N` to start a new chat even while composing a message. Each shortcut also has its own per-shortcut override. This is separate from the **Submit Key** setting in [Chat Settings](/docs/desktop-app/settings/chat-settings), which controls how Enter and Ctrl+Enter behave in the chat composer. ## Related [#related] * [Keyboard Shortcuts (Overview)](/docs/desktop-app/shortcuts-and-links/keyboard-shortcuts) - the full list of default shortcuts. * [Deep Links](/docs/desktop-app/shortcuts-and-links/deep-links) - open chats and extension installs from URLs. * [Chat Settings](/docs/desktop-app/settings/chat-settings) - configure the submit key behavior. # Performance The `Performance` section in `Settings` gives you controls for managing AgentOne's behavior when working with large chats or many extensions. Most users will never need to change these defaults, but they are useful when you notice slow rendering or high memory use. ## Rendering Limits [#rendering-limits] AgentOne switches to a more performance-friendly rendering mode for content that exceeds these limits. Reducing the limits makes the app faster in long conversations with large outputs; increasing them lets you see more content before truncation. ### Max Message Length [#max-message-length] The maximum number of characters AgentOne renders in a single message before applying truncation or lazy loading. Very long assistant responses (for example, generated code files) can cause layout slowdowns without this limit. ### Max Codeblock Characters [#max-codeblock-characters] The maximum number of characters rendered inside a single code block. Large code outputs in long chats are the most common cause of sluggishness, and this setting is the most impactful for rendering performance. ### Max Tool Result Characters [#max-tool-result-characters] The maximum number of characters rendered in a tool result (the output of an [extension](/docs/guides/extensions) tool call). Tool calls that return large data - for example, a file view or a web page fetch - can produce very long outputs. Reducing this limit keeps those inline without affecting the model's actual context. ## Chat Virtualization [#chat-virtualization] ### Virtualize Chat Messages [#virtualize-chat-messages] AgentOne can render only the messages around the visible viewport instead of keeping every message mounted. This dramatically reduces memory use and improves scroll performance in long chats. The default mode enables virtualization after a message-count threshold. You can change the mode if you prefer to always or never virtualize chats. ### Message Count Threshold [#message-count-threshold] The number of messages a chat must have before virtualization activates in threshold mode. The default is `20`, so shorter chats render normally while longer chats switch automatically. ## Extension Runtime [#extension-runtime] ### MCP Parallel Load Limit [#mcp-parallel-load-limit] Controls how many MCP servers AgentOne starts simultaneously at launch. If you have many [extensions](/docs/guides/extensions) installed, a higher limit means faster overall startup but more CPU and memory usage during the load phase. A lower limit staggers the startup at the cost of some extensions taking longer to become available. The default is a moderate value suitable for most setups with a handful of extensions. Raise it if you have many extensions and your hardware can handle the burst; lower it if you notice high CPU spikes when the app opens. ## Related [#related] * [Extensions](/docs/guides/extensions) - manage installed MCP servers. * [Chat Settings](/docs/desktop-app/settings/chat-settings) - streaming throttle and other chat behavior tuning. # Deep Links AgentOne registers the `agent-one://` URL scheme on your system. This means any application - a browser, a README file, a script, or another app - can open AgentOne and pre-fill specific flows by constructing the right URL. ## Supported Deep Links [#supported-deep-links] ### New Chat [#new-chat] Opens AgentOne and starts a new chat, optionally with a pre-filled message in the composer. ```text agent-one://new-chat?v=1&message=Your%20message%20here ``` Parameters: | Parameter | Required | Description | | --------- | -------- | --------------------------------------------- | | `v` | Yes | Link version. Must be `1`. | | `message` | No | URL-encoded text to pre-fill in the composer. | When AgentOne receives this link, it creates a new chat and populates the composer input with the decoded message. The message is not sent automatically - you still press send. ### MCP Install [#mcp-install] Opens the custom extension install dialog with fields pre-filled from the link. ```text agent-one://mcp/install?v=1&name=My%20Server&config=%7B...%7D ``` Parameters: | Parameter | Required | Description | | --------- | -------- | ----------------------------------------------------- | | `v` | Yes | Link version. Must be `1`. | | `name` | Yes | URL-encoded display name for the extension. | | `config` | Yes | URL-encoded JSON configuration object for the server. | When AgentOne receives this link, it opens `Settings` -> `Extensions` and pre-fills the **Add Custom** dialog. A warning banner appears reminding you to review the details before installing. ## The `v` Parameter [#the-v-parameter] Both link types require a `v` (version) parameter. This lets AgentOne validate that the link format is one it understands. Currently the only supported value is `1`. ## Safety [#safety] AgentOne never installs extensions or sends messages automatically from deep links. Every deep link that triggers an install opens a review dialog, and new-chat links pre-fill but do not auto-send. You are always in control of the final action. ## Creating Deep Links [#creating-deep-links] If you are a developer or tool author and want to generate links that open AgentOne, construct the URL following the patterns above. URL-encode all parameter values, especially the `message` and `config` fields. Example in JavaScript: ```js const message = encodeURIComponent("Summarize this project for me"); const link = `agent-one://new-chat?v=1&message=${message}`; ``` ## Related [#related] * [Custom MCP Servers](/docs/guides/custom-extensions) - the install dialog that MCP deep links open. * [Keyboard Shortcuts](/docs/desktop-app/shortcuts-and-links/keyboard-shortcuts) - for in-app navigation shortcuts. # Shortcuts and Links AgentOne supports both keyboard shortcuts and app deep links. ## Topics [#topics] Navigate the app and work faster. All shortcuts are customizable. Open chats or extension installs through the `agent-one://` URL scheme. # Keyboard Shortcuts AgentOne includes a set of app-level keyboard shortcuts for the most common actions. All shortcuts are fully customizable in `Settings` -> `Keyboard Shortcuts`. ## Default Shortcuts [#default-shortcuts] | Action | Default Shortcut | | --------------------- | ---------------- | | Open Settings | `Ctrl+,` | | New Chat | `Ctrl+N` | | Focus Chat Search | `Ctrl+K` | | Toggle Sidebar | `Ctrl+B` | | Focus Main Chat Input | `Ctrl+L` | | Stop Response | `Shift+Esc` | ## Details [#details] ### `Ctrl+,` - Open Settings [#ctrl---open-settings] Opens the Settings panel from anywhere in the app, equivalent to clicking the Settings button at the bottom of the sidebar. Press Escape to close. ### `Ctrl+N` - New Chat [#ctrln---new-chat] Creates a new empty chat and focuses the composer input, ready for you to type. Works from anywhere in the app including while Settings is open. ### `Ctrl+K` - Focus Chat Search [#ctrlk---focus-chat-search] When the sidebar is open, `Ctrl+K` focuses the search field inside the sidebar. When the sidebar is collapsed, it opens the full-screen chat search dialog instead. Either way, you can start typing a search query immediately. For more about what you can search, see [Search Chats](/docs/desktop-app/chats/searching-chats). ### `Ctrl+B` - Toggle Sidebar [#ctrlb---toggle-sidebar] Collapses or expands the sidebar. When collapsed, a compact strip of icon buttons stays visible so you can still navigate. The layout of those buttons (row vs. column) is configurable in `Settings` -> `Appearance`. See [Chat Sidebar](/docs/desktop-app/chats/chat-sidebar#collapsing-the-sidebar). ### `Ctrl+L` - Focus Main Chat Input [#ctrll---focus-main-chat-input] Moves keyboard focus to the main chat composer input. Useful after reading a long response when you want to type your next message without reaching for the mouse. ### `Shift+Esc` - Stop Response [#shiftesc---stop-response] Stops the AI response currently generating in the active chat. This is the keyboard equivalent of pressing the stop button in the composer. ## Customizing Shortcuts [#customizing-shortcuts] All shortcuts can be rebound to any key combination. You can also disable individual shortcuts or make them work while typing in input fields. See [Keyboard Shortcuts Settings](/docs/desktop-app/settings/keyboard-shortcuts) for the full customization guide. ## Related [#related] * [Keyboard Shortcuts Settings](/docs/desktop-app/settings/keyboard-shortcuts) - customize keybindings. * [Deep Links](/docs/desktop-app/shortcuts-and-links/deep-links) - open chats and extension installs from URLs. * [Chat Sidebar](/docs/desktop-app/chats/chat-sidebar) - sidebar navigation. * [Search Chats](/docs/desktop-app/chats/searching-chats) - what `Ctrl+K` opens. # Extensions Troubleshooting ## Extension Does Not Load [#extension-does-not-load] * make sure it is enabled * open `Advanced` and check the status line * click `Restart` if the extension was connected but stopped responding * review command, URL, headers, or environment variables * increase timeout if startup is slow ## Extension Shows Auth Problems [#extension-shows-auth-problems] If the status suggests authentication is required: * open `Advanced` * click `Connect` * complete the sign-in flow ## Extension Installs But No Tools Appear [#extension-installs-but-no-tools-appear] * wait for loading to finish * confirm the extension really exposes tools * check `Per-tool approvals` after the tool list loads * resolve any server error shown in the status area ## Custom STDIO Server Does Not Start [#custom-stdio-server-does-not-start] * verify the command is valid * confirm required dependencies are installed on your system * add required environment variables if the server expects them ## Too Many Old Or Broken Entries [#too-many-old-or-broken-entries] Use `Find dangling extensions` from the filter menu to remove stale entries. # Troubleshooting Use the pages in this section when something in the desktop app is not behaving the way you expect. ## Topics [#topics] Fix missing models, API key issues, and local provider problems. Troubleshoot install, load, approval, and auth issues. Fix completion notifications and update-related issues. # Notifications and Updates Troubleshooting ## Completion Notifications Are Not Appearing [#completion-notifications-are-not-appearing] Check these things: * `Settings` -> `Chats` -> `Completion Notification` is not set to `Never` * your operating system has allowed notifications for AgentOne * if you chose `When window unfocused`, the app window is actually unfocused when the response finishes AgentOne requests notification permission when needed, but OS-level settings can still block notifications. ## Update Check Says Automatic Updates Are Disabled [#update-check-says-automatic-updates-are-disabled] Some installs are managed by an external software manager. In that case, update AgentOne using that external system instead of the in-app updater. ## Update Download Or Install Fails [#update-download-or-install-fails] * click `Try Again` * confirm you have network access * if your platform is externally managed, use your package manager instead ## No Release Notes Dialog Appeared [#no-release-notes-dialog-appeared] The `What's New` dialog only appears when the app has release notes for the current version and the version is newer than the last one you dismissed. # Providers and Models Troubleshooting ## No Model Selected Or No Models Available [#no-model-selected-or-no-models-available] Check these first: * at least one provider is enabled * the provider actually has one or more configured models * your API key has been saved if the provider needs one * local runtimes such as Ollama or LM Studio are running if you are using local providers ## Built-In Provider Is Enabled But Still Not Working [#built-in-provider-is-enabled-but-still-not-working] * verify the API key is correct * save the key again if you are not sure it was stored * check whether you added custom headers that may be interfering ## Local Provider Models Are Missing [#local-provider-models-are-missing] * confirm the local runtime is running * confirm the `Base URL` is correct * click `Auto` in the provider's model list * add a model manually if auto-detection fails ## Custom Provider Auto-Detection Fails [#custom-provider-auto-detection-fails] * verify the base URL includes the correct `/v1` path if required * verify the endpoint really exposes a compatible `/v1/models` route * check API key and custom headers * add models manually as a fallback # Use Canva with AgentOne [Canva](https://canva.com) is a popular online graphic design platform that enables users to create professional-looking visuals easily without advanced technical skills. Using a drag-and-drop interface, it allows for the creation of social media graphics, presentations, videos, websites, and print products. It is available for free or through paid Pro/Enterprise plans. Since Canva now has an [MCP server](/docs/guides/custom-extensions#what-is-an-mcp-server), you can connect your Canva account to AgentOne and use AI to help you create better designs faster. ### Open AgentOne [#open-agentone] If you haven't downloaded AgentOne yet, please check the [Installation Guide](/docs/installation). ### Navigate to Custom Extension Settings [#navigate-to-custom-extension-settings] First click `Settings` in the bottom right of the sidebar. If the sidebar is not expanded, click the "Open Sidebar" button in the top left of the app. Screenshot showing the settings button in the bottom right of the sidebar Next, click `Extensions` in the settings sidebar, then choose the `Custom` tab. If you don't see the settings sidebar, click the list icon in the top right. Screenshot showing the custom extensions section ### Add the official Canva extension [#add-the-official-canva-extension] Click the `Add Custom` button, then fill in the details for the `Canva` extension. * **Type:** HTTP (Remote). * **Name:** `Canva`. * **URL:** `https://mcp.canva.com/mcp`. Screenshot showing MCP server details filled out Leave other settings unchanged. Click the `Add Custom` button at the bottom of the dialog to complete the installation. Screenshot showing custom MCP servers list with Canva on the list ### Connect your Canva Account [#connect-your-canva-account] Click the `Connect` button that appears after installing the Canva extension and follow the steps to connect your account. You may have to reconnect Canva occasionally. Screenshot showing connect button on Canva extension notification ### That's it! [#thats-it] You've now added the `Canva` Extension. Try it out by asking AgentOne a question about Canva. Screenshot showing a chat with AgentOne where it searches Canva designs # Connect AgentOne to fast-filesystem-mcp **[`fast-filesystem-mcp`](https://github.com/efforthye/fast-filesystem-mcp)** is a performant, feature-rich MCP server that gives AI agents access to filesystems on your device. You can use `fast-filesystem-mcp` with AgentOne by adding it as a custom extension. Follow the directions below. ### Open AgentOne [#open-agentone] If you haven't downloaded AgentOne yet, please check the [Installation Guide](/docs/installation). ### Navigate to Custom Extension Settings [#navigate-to-custom-extension-settings] First click `Settings` in the bottom right of the sidebar. If the sidebar is not expanded, click the "Open Sidebar" button in the top left of the app. Screenshot showing the settings button in the bottom right of the sidebar Next, click `Extensions` in the settings sidebar, then choose the `Custom` tab. If you don't see the settings sidebar, click the list icon in the top right. Screenshot showing the custom extensions section ### Add the `fast-filesystem-mcp` MCP Server [#add-the-fast-filesystem-mcp-mcp-server] Click the `Add Custom` button, then fill in the details for the `fast-filesystem-mcp` server. * **Type:** STDIO (Local). * **Name:** `Fast Filesystem`. * **Command:** `npx -y fast-filesystem-mcp@latest`. Screenshot showing MCP server details filled out Leave other settings unchanged. Click the `Add Custom` button at the bottom of the dialog to complete the installation. Screenshot showing custom MCP servers list with fast filesystem MCP on the list ### That's it! [#thats-it] You've now added the `fast-filesystem-mcp` MCP server. Ask AgentOne to find and edit files on your computer. # Using Custom MCP Servers (Extensions) in AgentOne AgentOne has over 19,000 **built-in** extensions which allow you to connect to thousands of apps, services, and more. However, this vast library of extensions is not *comprehensive*. You may wish to connect AgentOne to an app or service that's not yet on the built-in list. You're in luck! AgentOne supports this and it's pretty easy to do. ## What is an MCP Server? [#what-is-an-mcp-server] MCP stands for **[Model Context Protocol](https://modelcontextprotocol.io)**. It's a standard that [Anthropic](https://anthropic.com) developed for connecting AI applications (e.g. AgentOne) to external systems (e.g. Gmail, Canva, etc.). Think of it like USB-C for AI agents... just like USB-C is standardizing the way we connect and charge devices, MCP is standardizing the way we connect AI to tools. AgentOne supports two types of MCP servers: * STDIO servers, which run locally on your device. These are typically less secure than HTTP (remote) servers, as they have access to your system. * HTTP servers, which run remotely on another server. Typically, these require a consistent internet connection. While much more secure than STDIO (local) servers, they can still be malicious. * **SSE servers are not supported.** If you need to use an SSE HTTP server with AgentOne, please request this feature on the [AgentOne Forum](https://forum.agent-one.dev). ## How to Install a Custom MCP Server [#how-to-install-a-custom-mcp-server] You should never install an MCP server that you don't trust. We recommend installing MCP servers only from reputable sources. Also verify that MCP servers you install are *official*, meaning they are developed by the service you are trying to connect to, not a third party. To install a custom MCP server, you'll need to determine what type of server it is. If you have a "Command" beginning with something like `npx`, `docker`, or `uvx`, it's probably an [STDIO MCP server](#stdio-server). If you have a connection URL beginning with something like `https://`, it's almost certainly an [HTTP MCP server](#http-server). Once you've figured this out, you can read the instructions for that type of server below. ### STDIO Server [#stdio-server] #### Install Required Tools [#install-required-tools] If you're not a developer, there's a high chance you'll need to install additional tools on your system to use STDIO MCP servers. Here's a guide to what you may need to install, based on what the `Command` for the MCP server you want to add begins with. If you're not sure what the `Command` is, it looks something like this: ```bash npx -y xyz ``` * Begins with `npx`: Install [Node.js](https://nodejs.org/en/download/). * Begins with `uvx`: Install [uv](https://docs.astral.sh/uv/getting-started/installation/). * Begins with `docker`: Install [Docker](https://www.docker.com/get-started/). #### Navigate to Extension Settings [#navigate-to-extension-settings] If you haven't downloaded AgentOne yet, please check the [Installation Guide](/docs/installation). Open the AgentOne desktop app, expand the sidebar and click `Settings` in the bottom left, then click `Extensions` in the sidebar. #### Add a Custom Extension [#add-a-custom-extension] Next to the search bar, click `Add Custom`. Select `STDIO (Local)` as the server type, give your server a name, and paste the command for your server in the `Command` field. Install custom extension modal with STDIO selected If the instructions for the server you're adding mentions environment variables, you can add those too in the `Environment Variables` section. That's it! Click `Add Custom` to install the extension, then start a chat with AgentOne. It will have access to the new extension you added. ### HTTP Server [#http-server] #### Navigate to Extension Settings [#navigate-to-extension-settings-1] If you haven't downloaded AgentOne yet, please check the [Installation Guide](/docs/installation). Open the AgentOne desktop app, expand the sidebar and click `Settings` in the bottom left, then click `Extensions` in the sidebar. #### Add a Custom Extension [#add-a-custom-extension-1] Next to the search bar, click `Add Custom`. Select `HTTP (Remote)` as the server type, give your server a name, and paste the connection URL for your server in the `URL` field. Install custom extension modal with HTTP selected If the instructions for the server you're adding mentions HTTP headers, you can add those too in the `HTTP Headers` section. Click `Add Custom` to install the extension. #### Sign In if Necessary [#sign-in-if-necessary] The extension may prompt you to sign in. In this case, simply click the `Login` button and follow the instructions. Login prompt for Canva extension That's it! Start a chat with AgentOne. It will have access to the new extension you added. # Approval and Authentication AgentOne gives you granular control over when tools run automatically versus when you need to explicitly approve them. This is especially important for tools that make changes to your files, run commands, or interact with external services. ## Default Approval for an Extension [#default-approval-for-an-extension] Every installed extension - whether from the registry or added as a custom server - has a **Require Approval By Default** toggle. When enabled, AgentOne pauses before running any tool from that extension and asks you to confirm. This setting is the top-level switch for the extension. You can set it: * During installation (registry extensions and custom extensions both offer this in the install/add dialog). * After installation, from the extension's **Advanced** panel. ## Per-Tool Approval Overrides [#per-tool-approval-overrides] The per-extension toggle controls the default, but you can override it for individual tools using **Per-tool approvals** in the Advanced panel. This means you can: * Approve by default for the whole extension, but skip approval for one low-risk tool (such as `read-only` operations). * Not require approval by default, but require it for one specific high-risk tool (such as one that deletes data). Per-tool settings take precedence over the extension-level default. The per-chat [Tool Behavior](/docs/guides/providers/model-config#tool-behavior) can temporarily override these rules. `Ask` requires approval for every tool, while `YOLO` bypasses every approval check. ## How Approval Works in a Chat [#how-approval-works-in-a-chat] When a tool requires approval and the model tries to call it, AgentOne pauses the response and shows an approval prompt inline in the chat. The prompt shows the tool name and the arguments the model wants to pass. You can: * **Approve** - the tool runs and the model continues from the result. * **Reject** - the model is told the tool call was rejected and may try a different approach. The conversation does not proceed past the approval point until you respond. ## Extension Status Indicators [#extension-status-indicators] Installed extensions can show these status states in the Extensions settings page: | Status | Meaning | | ------------- | ---------------------------------------------------- | | Loading | The server is starting up. | | Enabled | Connected and tools are available. | | Disabled | Manually turned off. | | Error | Failed to start or connect. | | Auth required | The server needs sign-in before tools are available. | ## Connect and Disconnect (HTTP Extensions) [#connect-and-disconnect-http-extensions] Some HTTP extensions - typically those that connect to external services like GitHub, Notion, or Google Drive - require authentication before their tools are available. These show a **Connect** button in the Advanced panel. To authenticate: 1. Open `Settings` -> `Extensions`. 2. Find the extension and click **Advanced**. 3. Click **Connect**. 4. Complete the sign-in flow in the browser window that opens. After connecting, the status changes to **Connected** and the extension's tools become available in chat. You can disconnect at any time by clicking **Disconnect** in the same panel. Extensions that do not need authentication show **No authorization required** in the Advanced panel. ## Saving Advanced Changes [#saving-advanced-changes] Changes in an extension's **Advanced** panel are kept as a draft. Click **Save** to apply them, or **Cancel** to discard them. Changing or disabling an extension also dismisses login prompts for that server. ## Restarting an Extension [#restarting-an-extension] An installed, enabled extension shows a **Restart** action when it is connected and not already starting. Use it after changing external credentials or when the server is running but no longer responding. Restarting reconnects the server without uninstalling it. ## Debug Info [#debug-info] Some registry-installed extensions expose a **Debug info** section in the Advanced panel. This shows raw information about what the server reported during connection - useful when troubleshooting a broken install or comparing the registry metadata with what the app detected. ## Related [#related] * [Built-in Tools](/docs/guides/extensions/built-in-tools) - approval controls for the tools that ship with AgentOne. * [Install Extensions](/docs/guides/extensions/install-extension) - set approval defaults at install time. * [Custom MCP Servers](/docs/guides/custom-extensions) - approval options when adding a server manually. * [Extensions Troubleshooting](/docs/desktop-app/troubleshooting/extensions) - fix auth and approval issues. # Built-in Tools AgentOne ships with a set of built-in tools that appear under the `Built-in extensions` card in `Settings` -> `Extensions`. These tools are always available - no install or registry access needed - and most are enabled by default. ## The Built-in Tools [#the-built-in-tools] ### Current date and time [#current-date-and-time] Gives the model access to the current date and time. Useful for any task where the model needs to be aware of when "today" is - generating reports, scheduling suggestions, or time-aware summaries. You can configure whether it reports in **UTC** or local time. ### Pause [#pause] Inserts a deliberate pause into the model's execution. Useful in long agentic workflows when you want the model to stop and wait rather than continue immediately. You can set minimum and maximum pause duration values. ### Browse [#browse] Opens one or more URLs and returns their content to the model. Useful when you want the model to read specific pages rather than search for them. Its chat activity shows each URL's loading status and result. If you cancel the operation, you can still expand it to see which URLs the model intended to browse. You can configure the maximum number of URLs the tool fetches in a single call and the default maximum content length returned. ### Search the web [#search-the-web] Performs a web search and returns results to the model. The model can use this to find current information, look up documentation, or research a topic. Configurable options include concurrency, maximum results per query, and maximum pages fetched. ### Edit file [#edit-file] Reads and modifies a file on disk. The model can use this to apply targeted edits to code or text files during agentic workflows. ### Create file [#create-file] Creates a new file at a specified path with provided content. Often used alongside other file tools in coding or writing workflows. ### Delete file [#delete-file] Deletes a file at a specified path. Because this is irreversible, you may want to enable `Require Approval` for this tool. ### View file [#view-file] Reads a file and returns its contents to the model. You can configure the default maximum number of characters returned to keep responses manageable. ### Run command [#run-command] Executes a shell command on your machine and returns the output to the model. This is a powerful tool - use `Require Approval` to be prompted before any command runs. You can configure the default timeout for command execution. ### Spawn subagent [#spawn-subagent] Delegates a focused task to a subagent with its own context window. Useful for long-form or multi-step work where separating concerns into parallel or sequential sub-tasks improves results. Subagents cannot spawn their own subagents. ### Memory [#memory] Manages long-term memory entries that persist across chat sessions. The model can add, remove, or replace memory entries automatically. When enabled (default), the model can remember facts about you between conversations without you repeating yourself. See [Memory](/docs/desktop-app/chats/memory) for more. ### Wikipedia [#wikipedia] Searches and reads Wikipedia directly. This built-in extension is currently beta and is useful for encyclopedia-style lookups without a general web search. ### Settings tools [#settings-tools] The `List settings`, `Get setting`, and `Update setting` tools let AgentOne inspect supported app preferences and, with approval, change them for you. Listing and reading settings do not require approval by default; updating a setting does. For example, you could ask AgentOne to change its theme color, improve its performance, and more. ## Per-Tool Controls [#per-tool-controls] For every built-in tool you can: * **Enable or disable** it - disabled tools are never offered to the model. * **Set Require Approval** - when on, AgentOne shows a confirmation dialog before running the tool, letting you review what it is about to do. * **Adjust tool-specific configuration** - each tool with configurable options exposes those settings inline. ## Resetting to Defaults [#resetting-to-defaults] A reset button at the bottom of the built-in tools card restores all built-in tool settings to their defaults. This does not affect installed MCP extensions. ## Safety Recommendations [#safety-recommendations] For tools that make irreversible changes - `Delete file`, `Run command`, `Edit file`, `Create file`, and `Update setting` - consider enabling `Require Approval` so you can review each action before it happens. `Memory` can also benefit from approval if you want to review what the model wants to remember. For read-only tools like `View file`, `Browse`, `Wikipedia`, and `Search the web`, approval is usually not necessary. See [Approval and Auth](/docs/guides/extensions/approval-and-auth) for more on how approvals work across both built-in tools and installed extensions. {/* Screenshot placeholder: Built-in extensions card expanded with Run command tool showing Require Approval toggle enabled, and the tool-specific timeout configuration visible. */} # Dangling Extensions Over time, especially if you have installed and uninstalled registry extensions across multiple app versions, you may end up with **dangling extensions** - entries in AgentOne's extension list that no longer cleanly correspond to a current registry record. This can happen when: * A registry extension was renamed or re-identified between versions. * An extension was partially uninstalled or its registry entry was removed. * You migrated settings from an older version of AgentOne. Dangling entries are harmless in most cases, but they can clutter your extensions list and occasionally cause confusing load errors. ## Finding Dangling Extensions [#finding-dangling-extensions] 1. Open `Settings` -> `Extensions`. 2. Click the filter menu (the funnel icon). 3. Choose **Find dangling extensions**. AgentOne scans your installed extensions and highlights any entries that do not match a known registry record. ## Cleaning Them Up [#cleaning-them-up] From the dangling extensions view, you can: * **Remove one at a time** - useful if you want to inspect each entry before deleting. * **Remove all** - clears every dangling entry in one action. Removing a dangling entry deletes AgentOne's configuration record for it. It does not uninstall any underlying tool or package from your system. ## Related [#related] * [Extension Registry](/docs/guides/extensions/extension-registry) - browse current registry entries. * [Extensions Troubleshooting](/docs/desktop-app/troubleshooting/extensions) - fix other common extension issues. # Extension Registry The extension registry is a curated catalogue of MCP servers that AgentOne knows how to install and configure. You access it from `Settings` -> `Extensions`. ## Browsing the Registry [#browsing-the-registry] The registry page lists available extensions with the following information for each: * **Name and description** - what the extension does. * **Version** - the version AgentOne will install. * **Icon and category badges** - a quick visual indicator of the extension's purpose. * **Connection type** - whether the server runs on your device (STDIO) or connects to a remote service (HTTP). * **Website link** - a link to the extension's own documentation or homepage. Without any filters applied, the list is sorted to show built-in extensions first, then installed extensions, then everything else. ## Search and Filters [#search-and-filters] Use the search field to filter by name or keywords. The filter menu adds: * **Show only installed** - narrows the list to extensions you have already installed. * **Connection type filter** - `Runs on this device` (STDIO) or `Connects online` (HTTP). These filters can be combined with a search query. ## Install Status [#install-status] Each extension row shows its current status: * No badge - not installed. * Installed and showing a status indicator - enabled, loading, disabled, or error. If an extension shows `Unsupported`, AgentOne cannot install it from the available registry data. This typically means the server requires a transport type or configuration format that AgentOne does not yet support. ## Advanced View [#advanced-view] Installed extensions gain an **Advanced** button. The advanced panel exposes: * Current load status and any error messages. * [Per-tool approval overrides](/docs/guides/extensions/approval-and-auth#per-tool-approval-overrides). * [Auth connection controls](/docs/guides/extensions/approval-and-auth#connect-and-disconnect-http-extensions) for HTTP extensions that require sign-in. * A **Restart** action for an enabled extension that is no longer responding. * Debug information for some registry extensions, useful when troubleshooting. Edits in this view are drafts until you click **Save** in the footer. Click **Cancel** to leave the installed configuration unchanged. ## Related [#related] * [Install Extensions](/docs/guides/extensions/install-extension) - step-by-step installation flow. * [Approval and Auth](/docs/guides/extensions/approval-and-auth) - how approval and authentication work. * [Dangling Extensions](/docs/guides/extensions/dangling-extensions) - cleaning up stale registry entries. # Extensions AgentOne uses the term **extensions** for two distinct things that both add capabilities to the AI: * **Built-in tools** - a curated set of tools that ship with the app (file operations, web search, command execution, and more). * **MCP servers** - external Model Context Protocol servers you install from the registry or add yourself. Both types are managed from `Settings` -> `Extensions`. The app labels extensions as beta. Some behavior may still change between releases. ## Topics [#topics] Enable built-in tools and configure how each one behaves. Search, filter, and browse installable extensions from the registry. Install registry extensions and review their configuration before enabling. Add your own STDIO or HTTP MCP servers. Control per-tool approvals and connect HTTP extensions that require sign-in. Find and remove extensions that no longer map to registry entries. ## How Extensions Appear in a Chat [#how-extensions-appear-in-a-chat] When a model that [supports tools](/docs/guides/providers/model-metadata#supports-tools) is selected, enabled extensions offer their tools to the model during the conversation. The model can then call those tools as part of its response - for example, searching the web, reading a file, or running a shell command. Tool calls appear inline in the chat as collapsible activity items so you can see exactly what the model did. If [approval is required](/docs/guides/extensions/approval-and-auth) for a tool, AgentOne pauses and asks before running it. ## MCP Apps (Beta) [#mcp-apps-beta] Extensions that support MCP Apps can render interactive interfaces directly in a chat. An app may appear: * **inline** with the extension's tool activity * in an **Expanded extension view** * in a **picture-in-picture** window Expanded and picture-in-picture views can be closed to return to the conversation. AgentOne passes the current light or dark theme, locale, platform, available display modes, and container size to compatible apps so they can fit the desktop UI. MCP Apps run in a sandboxed frame. ## Related Guides [#related-guides] For specific real-world MCP server examples, see the [Custom Extensions guides](/docs/guides/custom-extensions) which walk through installing Smithery, Canva, and filesystem servers step by step. # Install Extensions Registry extensions are MCP servers curated by AgentOne and available directly from `Settings` -> `Extensions`. Installing from the registry is the easiest path - AgentOne detects the server's command, transport type, and required configuration for you. ## Installation Steps [#installation-steps] ### Find the Extension [#find-the-extension] Open `Settings` -> `Extensions`. Use the search field to find the extension by name or keywords. Browse the [registry](/docs/guides/extensions/extension-registry) to discover what is available. ### Click Install [#click-install] Click the **Install** button on the extension row. AgentOne opens the install dialog. ### Review the Configuration [#review-the-configuration] The install dialog shows everything AgentOne has detected for this extension: * **Transport type** - `STDIO (Local)` or `HTTP (Remote)`. * **Command or URL** - the command AgentOne will run, or the remote URL it will connect to. * **Timeout** - how long AgentOne waits for the server to start or respond before marking it as failed. * **Approval default** - whether tool calls from this extension require your confirmation before running. * **Detected configuration fields** - any inputs the extension requires, such as API keys or directory paths. Review these carefully, especially if the extension requires an API key or access to sensitive paths on your machine. ### Fill in Required Fields [#fill-in-required-fields] If the dialog shows required configuration fields (common for extensions that connect to external services), fill them in. For example, a GitHub extension would need your GitHub personal access token. ### Confirm Installation [#confirm-installation] Click **Install** to finish. The extension is added, enabled, and starts loading immediately. You always see the install dialog before an extension is added. This is true both for manual registry installs and for installs triggered by a [deep link](/docs/desktop-app/shortcuts-and-links/deep-links). ## After Installation [#after-installation] Once installed, the extension row shows a status indicator (loading, enabled, or error) and gains an **Advanced** button. If you need to change any configuration, open Advanced to edit timeout, approval defaults, or per-tool overrides. If the extension requires authentication (common for HTTP extensions that connect to external services), open Advanced and click **Connect**. See [Approval and Auth](/docs/guides/extensions/approval-and-auth) for details. ## Uninstalling [#uninstalling] Click the **Uninstall** button on the extension row, or open Advanced and use the remove option there. Uninstalling removes the extension entry but does not uninstall the underlying tool from your system (for example, an `npx`-based STDIO server). ## Related [#related] * [Extension Registry](/docs/guides/extensions/extension-registry) - browse and filter available extensions. * [Custom MCP Servers](/docs/guides/custom-extensions) - add servers that are not in the registry. * [Approval and Auth](/docs/guides/extensions/approval-and-auth) - manage approvals and connect authenticated extensions. # Anthropic Anthropic makes the Claude family of models. AgentOne includes Anthropic as a built-in provider. ## Getting an Anthropic API Key [#getting-an-anthropic-api-key] ### Sign in to Anthropic Console [#sign-in-to-anthropic-console] Go to [console.anthropic.com](https://console.anthropic.com) and sign in or create an account. ### Open API Keys [#open-api-keys] In the left sidebar, click **API Keys**, then click **Create Key**. Give it a name such as "AgentOne". ### Copy the Key [#copy-the-key] Copy the key immediately. Anthropic only shows the full key value once. Anthropic requires a funded account to use the API beyond the free tier. Add credits at [console.anthropic.com/settings/billing](https://console.anthropic.com/settings/billing). ## Connecting Anthropic in AgentOne [#connecting-anthropic-in-agentone] ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` -> `Providers`. ### Find and Enable Anthropic [#find-and-enable-anthropic] Under `Built-in Providers`, locate **Anthropic**, expand it, and toggle the enable switch on. ### Paste Your Key [#paste-your-key] Paste your API key into the `API Key` field and click save. Claude models appear in the [model selector](/docs/guides/providers/model-selector) immediately after saving. ## Available Models [#available-models] AgentOne's built-in list covers the major Claude 3 and Claude 4 series models. If Anthropic releases a new model before AgentOne's list is updated, you can register it via `Add Model Override` in the provider settings. See [Built-in Providers](/docs/guides/providers/built-in-providers#model-overrides). ## Troubleshooting [#troubleshooting] * **401 error**: double-check your API key and save again. * **Credit balance errors**: top up your Anthropic balance at the console. * **Tool calls failing**: verify the selected Claude model supports tools. See [Model Metadata](/docs/guides/providers/model-metadata#supports-tools). For more, see [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # Automatic Model Detection ## What is Automatic Model Detection? [#what-is-automatic-model-detection] **Automatic model detection** discovers available models from your custom provider by querying its API. Instead of manually adding each model, you can click the `Auto` button and AgentOne will fetch and add them for you. This is especially useful if your provider has many models or you're unsure what's available. ## How to Use It [#how-to-use-it] When setting up a custom provider, navigate to the **Models** section and click the `Auto` button. AgentOne will: 1. Query your provider's `/v1/models` endpoint 2. Retrieve the available models 3. Add any new ones to your list (skipping duplicates) If successful, you'll see a checkmark. If it fails, you'll see an error indicator. In that case, you can manually add models by clicking `Add Model`. Currently, automatic model detection is only available for custom providers. In a future update, this feature will be expanded to built-in providers with additional options like auto-updating on app startup and periodically in the background. ## When Automatic Detection Fails [#when-automatic-detection-fails] Common reasons: * **Invalid base URL**: Make sure it includes `/v1` at the end (e.g., `https://api.example.com/v1`) * **Wrong API key**: Verify it's correct for your provider * **Provider offline or unsupported**: Your service may be down or doesn't support the OpenAI-compatible `/v1/models` endpoint Check your provider's documentation to confirm the correct base URL and that it supports the `/v1/models` endpoint. ## Manual Fallback [#manual-fallback] If automatic detection doesn't work, click `Add Model` and enter the model name manually. You can retry the `Auto` button anytime... it won't create duplicates. For help, reach out on the [AgentOne Forum](https://forum.agent-one.dev) or [Discord](https://www.agent-one.dev/discord). # Built-in Providers AgentOne ships with over 60 cloud providers already configured. You only need to enable the ones you want and supply your API keys - there is no URL to configure or custom JSON to write. ## What Counts as a Built-in Provider? [#what-counts-as-a-built-in-provider] Built-in providers are the cloud AI services that AgentOne has first-class support for. They appear under the `Built-in Providers` heading in `Settings` -> `Providers`. Each one has a known base URL and a set of bundled model definitions, so the only thing you supply is an API key. Common examples include OpenAI, Anthropic, Google, Groq, and Mistral. The full list is visible in the app by scrolling through the Built-in Providers section. ## Enabling a Provider [#enabling-a-provider] ### Open Provider Settings [#open-provider-settings] In the sidebar, click `Settings`, then choose `Providers`. ### Find the Provider [#find-the-provider] Scroll through the `Built-in Providers` list or use the search field to find your provider by name. ### Expand and Enable [#expand-and-enable] Click the provider to expand it, then toggle the enable switch on. ### Enter Your API Key [#enter-your-api-key] Paste your API key into the `API Key` field. The field masks the value with dots once saved. Click the save button. If you skip saving, the key is not stored and the provider will fail to authenticate. Once saved, the provider's models immediately appear in the [model selector](/docs/guides/providers/model-selector) in any open chat. ## Environment Variables [#environment-variables] Some providers also read an API key from an environment variable. When AgentOne detects a key this way, it shows a hint like `Using environment variable. Override below if needed.` You can still paste a manual key to override it. ## Extra HTTP Headers [#extra-http-headers] Every built-in provider has an HTTP headers editor. This is an advanced feature - most users never need it. It is useful when your organization routes traffic through a proxy that requires a specific header, or when a provider expects a non-standard header alongside the API key. ## Model Overrides [#model-overrides] Built-in providers come with a curated list of models. You can layer overrides on top of them using `Add Model Override`. Two reasons to do this: * **Correct metadata**: if a model's reported context window or capability flags are wrong in the app, you can override just those fields. * **Register a new model**: if the provider has released a model that is not yet in AgentOne's built-in list, add it here with the exact model ID the provider uses. Overrides do not replace the built-in model list - they supplement it. See [Model Metadata](/docs/guides/providers/model-metadata) for a full explanation of each field. ## Per-Provider Guides [#per-provider-guides] For step-by-step API key instructions for specific providers, see: * [OpenAI](/docs/guides/providers/openai) * [Anthropic](/docs/guides/providers/anthropic) * [Google Gemini](/docs/guides/providers/google) * [Groq](/docs/guides/providers/groq) * [Mistral](/docs/guides/providers/mistral) Providers settings page with a built-in provider expanded, the enable toggle on, the API key field masked, and the Add Model Override button visible. # Custom Providers ## What is a Custom Provider? [#what-is-a-custom-provider] A **custom [provider](/docs/guides/providers#what-is-a-provider)** lets you connect AgentOne to an AI model service that isn't on our built-in list. This is useful if you're running a local LLM, using a smaller API service, or have a private inference server. Currently, AgentOne supports custom providers that use the **OpenAI API format**. If your service has an API that's compatible with OpenAI's format (meaning it accepts the same requests and returns the same responses), you can connect it as a custom provider. If you find an OpenAI compatible provider that doesn't work with AgentOne, we consider it a bug. Please report it to us on [the Forum](https://forum.agent-one.dev). Examples of services you can connect: * **Local LLMs** like Ollama, LM Studio, or GPT4All running on your computer * **Public API providers** that offer OpenAI-compatible endpoints * **Private inference servers** you've deployed yourself * **Self-hosted services** like vLLM or text-generation-webui Right now, custom providers must use the OpenAI API format. If you need support for other formats, let us know on the [AgentOne Forum](https://forum.agent-one.dev). ## Understanding the Setup [#understanding-the-setup] Before adding a custom provider, you need to know three things: ### 1. The Base URL [#1-the-base-url] This is the address where your service is running. Examples: * Local Ollama: `http://localhost:11434/v1` * LM Studio: `http://localhost:1234/v1` * Remote server: `https://api.example.com/v1` (this will be different for different servers) ### 2. The Model Name [#2-the-model-name] This is the exact name of the model you want to use. It depends on what your service has available. For example: * With Ollama: `gemma`, `mistral`, `qwen`, etc. * With a custom server: whatever models you've deployed It's important to know these in case [detecting models automatically](/docs/guides/providers/automatic-model-detection) fails so that you can enter them manually. ### 3. Optional: API Key and Headers [#3-optional-api-key-and-headers] If your service requires authentication, you may need: * An **API key** (similar to [built-in providers](/docs/guides/providers)) * Custom **HTTP headers** (for more complex authentication) Most local services don't require these, but remote or private services usually do. ## Adding a Custom Provider [#adding-a-custom-provider] ### Open Provider Settings [#open-provider-settings] Open the AgentOne desktop app. Click `Settings` in the bottom left of the sidebar, then click `Providers`. ### Click Add Provider [#click-add-provider] Click the `Add Provider` button. You'll see a dropdown with the option `OpenAI Compatible`. Add Provider dropdown ### Fill in the Name [#fill-in-the-name] Give your custom provider a name. This is just for display in AgentOne so you know which provider it is. Examples: "My Ollama", "Local LM Studio", "Company Server", etc. ### Enter the Base URL [#enter-the-base-url] Paste the base URL where your service is running. This should include the `/v1` path at the end for most services. Custom provider form with Base URL Common examples: * Ollama: `http://localhost:11434/v1` * LM Studio: `http://localhost:1234/v1` * Remote: `https://api.example.com/v1` (find this in your provider's documentation) ### Add Your API Key (if needed) [#add-your-api-key-if-needed] If your service requires authentication, paste your API key in the `API Key` field. If it's a local service like Ollama or LM Studio, you can leave this blank. ### Add Custom Headers (optional) [#add-custom-headers-optional] If your service needs special headers for authentication (like custom authorization schemes), you can add them here. Most services don't need this. Click `Add Header` if needed, but this is optional. ### Add Your Models [#add-your-models] This is the important part. You need to tell AgentOne which models are available at your service. First, try to automatically detect what models are available. **If this succeeds, you can skip the next step!** Simply click the `Auto` button in the `Models` section. If automatic model detection succeeds, new models will be added to the list. *** If automatic model detection did not succeed, you need to add models manually. Click `Add Model` and enter: * **Model ID**: The exact name your service uses (e.g., `gpt-5`, `mistral`) * **Display Name**: What you want to see in AgentOne (e.g., "GPT 5", "Mistral 7B") * Toggle the `Supports Tools` and `Supports Images` buttons if the model doesn't support tools or images. If you're not sure, leave these options alone. You can add multiple models if your service has several. Adding models to custom provider If you're not sure what models are available, check your service's documentation or admin panel. ### Save the Provider [#save-the-provider] Click `Add Provider` to save your custom provider. It will now appear in your providers list along with your built-in providers. ## Using Your Custom Provider [#using-your-custom-provider] Once you've added a custom provider, it will appear in the providers list and can be toggled on/off like built-in providers. When it's enabled, its models will show up in AgentOne's model selector. You can: * **Toggle it on/off** with the switch to control if it's available * **Edit it** by clicking on it in the list (change URL, models, API key, etc.) * **Delete it** by clicking `Delete Provider` at the bottom of the expanded section ## Having Trouble? [#having-trouble] Ask on the [AgentOne Forum](https://forum.agent-one.dev) or [our Discord server](https://www.agent-one.dev/discord) for help. Include your provider type (Ollama, LM Studio, etc.) and the error message you're seeing. # Google Gemini Google makes the Gemini family of models. AgentOne includes Google as a built-in provider. ## Getting a Google AI API Key [#getting-a-google-ai-api-key] ### Open Google AI Studio [#open-google-ai-studio] Go to [aistudio.google.com](https://aistudio.google.com) and sign in with a Google account. ### Create an API Key [#create-an-api-key] Click **Get API key** in the left sidebar, then click **Create API key**. You can create the key in a new or existing Google Cloud project. ### Copy the Key [#copy-the-key] Copy the API key from the dialog. Google AI Studio offers a free tier for the Gemini API. Check [ai.google.dev/pricing](https://ai.google.dev/pricing) for current limits and paid tier pricing. ## Connecting Google in AgentOne [#connecting-google-in-agentone] ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` -> `Providers`. ### Find and Enable Google [#find-and-enable-google] Under `Built-in Providers`, locate **Google**, expand it, and toggle the enable switch on. ### Paste Your Key [#paste-your-key] Paste your API key and click save. Gemini models appear in the [model selector](/docs/guides/providers/model-selector) after saving. ## Available Models [#available-models] AgentOne includes the major Gemini 1.5 and Gemini 2.x models. For models released after the app's built-in list, use `Add Model Override`. See [Built-in Providers](/docs/guides/providers/built-in-providers#model-overrides). ## Troubleshooting [#troubleshooting] * **API key not valid**: confirm you copied the full key from AI Studio. * **Model not found**: some Gemini models have regional restrictions. Check the model's availability in your region at [ai.google.dev](https://ai.google.dev). * **Image not working**: confirm the selected Gemini model supports images. See [Model Metadata](/docs/guides/providers/model-metadata#supports-images). For more, see [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # Groq Groq offers extremely fast inference for open-source models using custom LPU hardware. AgentOne includes Groq as a built-in provider. ## Getting a Groq API Key [#getting-a-groq-api-key] ### Sign in to GroqCloud [#sign-in-to-groqcloud] Go to [console.groq.com](https://console.groq.com) and sign in or create a free account. ### Create an API Key [#create-an-api-key] In the sidebar, click **API Keys**, then click **Create API Key**. Give it a name and copy the key. Groq offers a free tier with rate limits. Check [console.groq.com/docs/rate-limits](https://console.groq.com/docs/rate-limits) for current limits. ## Connecting Groq in AgentOne [#connecting-groq-in-agentone] ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` -> `Providers`. ### Find and Enable Groq [#find-and-enable-groq] Under `Built-in Providers`, locate **Groq**, expand it, and toggle the enable switch on. ### Paste Your Key [#paste-your-key] Paste your API key and click save. Groq models (Llama, Mistral, Gemma, and others) appear in the [model selector](/docs/guides/providers/model-selector) after saving. ## Troubleshooting [#troubleshooting] * **Rate limit errors**: Groq's free tier has strict per-minute limits. Wait a moment and retry, or check your usage at the console. * **Model unavailable**: Groq's available model list changes as they update their hardware. Check [console.groq.com/docs/models](https://console.groq.com/docs/models) for the current list. For more, see [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # Providers ## What is a Provider? [#what-is-a-provider] A **provider** is a company that builds and hosts AI models. Think of them as the source of the AI itself. For example: * **OpenAI** makes GPT-5, Codex models, and other models * **Anthropic** makes Claude * **Google** makes Gemini * **Groq** makes very fast models AgentOne supports over 60 different providers out of the box. This means you have choices... different models have different strengths (speed, quality, cost, reasoning ability, etc.), so you can pick what works best for your needs. ## What is an API Key? [#what-is-an-api-key] An **API key** is like a password that lets AgentOne talk to a provider's servers. When you use a model from OpenAI or Anthropic for example, AgentOne needs permission to access it, and the API key is what grants that permission. Think of it like a car key: * The provider (e.g., OpenAI) is the car * The API key is your key to use it * Without the key, you can't access it Your API keys are encrypted and stored locally on your device only. AgentOne never sends them to our servers or any third party. ## Getting an API Key [#getting-an-api-key] Each provider has their own website where you can create an API key. Try searching the web or asking AgentOne for help, for example "how to get an OpenAI API key". There's no standard process to obtain an API key across all providers, so you'll want to find a specific guide for your provider. Once you have your API key, follow the steps below to connect it to AgentOne. ## Connecting a Built-in Provider [#connecting-a-built-in-provider] ### Open Provider Settings [#open-provider-settings] Open the AgentOne desktop app. Click `Settings` in the bottom left of the sidebar, then click `Providers`. Provider Settings location ### Find Your Provider [#find-your-provider] You'll see a list of all supported providers. Scroll through to find the one you want to connect (e.g., OpenAI, Anthropic, Google, Groq). You can also search by name, as shown in the image below. List of available providers ### Enable the Provider [#enable-the-provider] Click on your provider to expand it. Toggle the switch on the right to enable this provider. Provider accordion expanded ### Paste Your API Key [#paste-your-api-key] In the `API Key` field, paste the API key you created from the provider's website. The field will hide your key for privacy (you'll see dots instead of the actual text). API key field with masked input Importantly, **click the save button** after pasting your API key or it will not be saved! ### Done! [#done] That's it! The provider is now connected. All of its available models will appear in AgentOne's model selector. You can now chat with AgentOne and choose models from this provider. If you ever want to disable the provider or use a different API key, you can come back to this screen and toggle it off or update the key. ## Custom Providers [#custom-providers] If AgentOne doesn't support a provider you need, you can add a custom one. To learn more about this, check out the [Custom Providers](/docs/guides/providers/custom) documentation. ## More Provider Guides [#more-provider-guides] Enable cloud providers and manage API keys and model overrides. Use Ollama or LM Studio for private, on-device inference. Switch models mid-conversation and understand what makes a model visible. Tune temperature, top-p, max tokens, and other per-chat parameters. Understand context window, output limits, and capability flags. Get an OpenAI API key and connect GPT models. Get an Anthropic API key and connect Claude models. Get a Google AI API key and connect Gemini models. Get a Groq API key and connect fast open-source models. Get a Mistral API key and connect Mistral models. Run local LLMs with Ollama. Run local models with LM Studio's GUI. AgentOne can read messages out loud using its own providers and API keys. # LM Studio LM Studio is a desktop app that lets you download and run open-source models locally. AgentOne includes LM Studio as a built-in [local provider](/docs/guides/providers/local-providers), so you can use it without any API key or internet connection during inference. ## Prerequisites [#prerequisites] * LM Studio installed on your machine. Download it from [lmstudio.ai](https://lmstudio.ai). * At least one model downloaded inside LM Studio. ## Setup [#setup] ### Download a Model in LM Studio [#download-a-model-in-lm-studio] Open LM Studio, go to the **Discover** tab, search for a model (for example `llama` or `mistral`), and download it. Wait for the download to finish before proceeding. ### Start the Local Server [#start-the-local-server] In LM Studio, go to the **Local Server** tab (the `<->` icon in the sidebar). Load the model you want to use and click **Start Server**. The server defaults to port `1234`. You should see a green status indicator and a URL like `http://localhost:1234`. Stuck? Read the [LM Studio docs](https://lmstudio.ai/docs/developer/openai-compat) or [join our Discord](https://www.agent-one.dev/discord) for free, live support. ### Open AgentOne Provider Settings [#open-agentone-provider-settings] In AgentOne, click `Settings` -> `Providers` and locate **LM Studio** under `Local Providers`. ### Confirm the Base URL [#confirm-the-base-url] The default base URL is `http://127.0.0.1:1234/v1`. If you changed LM Studio's port, update this field to match. ### Detect Models [#detect-models] Click `Auto` in the Models section. AgentOne queries LM Studio's `/v1/models` endpoint and adds the model currently loaded in the server. The detected model appears in the [model selector](/docs/guides/providers/model-selector) in chat. LM Studio local server tab with a model loaded and the server running, showing the port number and a green active status. ## Switching Models [#switching-models] LM Studio's local server serves one model at a time. To use a different model, go back to LM Studio, stop the server, load the new model, and restart the server. Then click `Auto` again in AgentOne (or add the new model manually) so it appears in the selector. ## Manual Model Entry [#manual-model-entry] If auto-detection does not work, add the model by hand: 1. In LM Studio, check the model identifier shown in the server tab. 2. In AgentOne, click `Add Model` inside the LM Studio provider. 3. Enter the model ID exactly as LM Studio reports it. ## Why LM Studio? [#why-lm-studio] * GUI-based model management - no command line needed. * Supports a wide range of GGUF-format models from Hugging Face. * Models run entirely on your hardware with no data leaving your machine. * Free to use with no API billing. For a comparison with Ollama, see [Local Providers](/docs/guides/providers/local-providers). For Ollama-specific setup, see [Local LLMs with Ollama](/docs/guides/providers/ollama-local-llms). ## Troubleshooting [#troubleshooting] * **Models not detected**: make sure the LM Studio server is running and the model is loaded before clicking `Auto`. * **Connection refused**: confirm the base URL port matches LM Studio's configured port. * **Server stops**: LM Studio may stop the server when the app is minimized on some systems. Keep it open while using AgentOne. See also [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # Local Providers AgentOne includes two local providers out of the box: **Ollama** and **LM Studio**. Both run on your own machine, so no API key or internet connection is needed for inference once the local runtime is running. They appear in `Settings` -> `Providers` under the `Local Providers` heading - separate from both [built-in cloud providers](/docs/guides/providers/built-in-providers) and [custom providers](/docs/guides/providers/custom). ## Default Base URLs [#default-base-urls] | Provider | Default Base URL | | --------- | --------------------------- | | Ollama | `http://127.0.0.1:11434/v1` | | LM Studio | `http://127.0.0.1:1234/v1` | These match the defaults used by each runtime when run locally. If you have changed the port on your installation, update the base URL in the provider settings to match. ## Quick Start [#quick-start] ### Install and Start the Runtime [#install-and-start-the-runtime] For Ollama, [install it](https://ollama.com) and run a model with `ollama run ` or start the Ollama service. For LM Studio, [install it](https://lmstudio.ai) and start the local server from inside the app. The runtime must be running before AgentOne can connect to it. ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` -> `Providers` and locate the provider under `Local Providers`. ### Confirm the Base URL [#confirm-the-base-url] Check that the base URL shown matches where your runtime is listening. If you are using the default port, no changes are needed. ### Let AgentOne Detect Models [#let-agentone-detect-models] AgentOne queries the runtime automatically on startup. If models are found, they appear in the provider's model list and in the [model selector](/docs/guides/providers/model-selector) in chat. If they do not appear, click `Auto` in the Models section to trigger detection manually. ## Ollama-Specific Notes [#ollama-specific-notes] The built-in Ollama provider sends an `Origin: http://localhost` header with every request. This is required because Ollama's default configuration rejects requests that do not include a recognized origin. You do not need to add this header yourself. If you are running Ollama somewhere other than `127.0.0.1` - for example, in a Docker container or on a remote machine - update the base URL accordingly and check whether Ollama's `OLLAMA_ORIGINS` setting needs to allow the new origin. For a full Ollama walkthrough, see [Local LLMs with Ollama](/docs/guides/providers/ollama-local-llms). ## LM Studio Notes [#lm-studio-notes] LM Studio's local server defaults to port `1234`. Make sure the server is started inside LM Studio before opening AgentOne, as the app cannot connect until the server is listening. LM Studio does not require an API key for local connections. For a full LM Studio walkthrough, see [Local LLMs with LM Studio](/docs/guides/providers/lm-studio). ## Manual Model Entry [#manual-model-entry] If automatic detection fails, you can still add models by hand. Click `Add Model` inside the provider and enter the model ID exactly as the runtime reports it (for example `llama3.2` or `mistral`). You can retry `Auto` at any time - it will not create duplicates. ## Why Use a Local Provider? [#why-use-a-local-provider] * **Privacy**: prompts never leave your machine. * **No usage costs**: you pay for hardware, not per-token API fees. * **Offline use**: once the model is downloaded, no internet connection is needed. * **Experimentation**: quickly try new open-source models without account setup. Providers settings page with Local Providers expanded and Ollama visible, showing the built-in Ollama entry and its base URL. # Mistral Mistral AI makes efficient open-weight models available through their API. AgentOne includes Mistral as a built-in provider. ## Getting a Mistral API Key [#getting-a-mistral-api-key] ### Sign in to La Plateforme [#sign-in-to-la-plateforme] Go to [console.mistral.ai](https://console.mistral.ai) and sign in or create an account. ### Create an API Key [#create-an-api-key] In the left sidebar, click **API Keys**, then click **Create new key**. Copy the key - it is only shown once. Mistral's API requires a paid account. Add billing at [console.mistral.ai/billing](https://console.mistral.ai/billing). ## Connecting Mistral in AgentOne [#connecting-mistral-in-agentone] ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` -> `Providers`. ### Find and Enable Mistral [#find-and-enable-mistral] Under `Built-in Providers`, locate **Mistral**, expand it, and toggle the enable switch on. ### Paste Your Key [#paste-your-key] Paste your API key and click save. Mistral models appear in the [model selector](/docs/guides/providers/model-selector) after saving. ## Troubleshooting [#troubleshooting] * **401 error**: re-paste and save the key. * **Model not available**: confirm the model name against [docs.mistral.ai/getting-started/models/models\_overview](https://docs.mistral.ai/getting-started/models/models_overview/). For more, see [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # Model Config The `Model Config` panel lets you fine-tune how the active model behaves for the current chat. You open it by clicking the config button next to the [model selector](/docs/guides/providers/model-selector) in the composer. Changes made here are **per-chat** - they do not affect other conversations or global defaults. ## Tool Behavior [#tool-behavior] `Tool Behavior` controls which tools the active chat can use and when AgentOne asks for approval: | Mode | Behavior | | ----------- | -------------------------------------------------------------------------------- | | **Default** | Uses enabled tools and asks only when a tool's approval setting requires it. | | **Ask** | Asks for your approval before every tool call. | | **YOLO** | Runs tools without approval. Use with caution, especially with write operations. | | **Disable** | Makes no tools available to the model. | `Default` remains the default mode. Select `Disable` when you want a tool-free chat or need to use a model that does not support tool calling. Tool-dependent controls become unavailable in that mode. YOLO runs tools without showing the approval checks configured for built-in or installed extensions. Only use it when you trust the model, prompt, and tools available to the chat. ## Available Parameters [#available-parameters] ### Temperature [#temperature] Controls how random or deterministic the model's output is. Lower values (closer to 0) make responses more focused and predictable. Higher values make them more varied and creative. A value around `0.7` is a common starting point for general conversation; lower values like `0.2` suit factual or code tasks. ### Top P [#top-p] An alternative sampling strategy to temperature, sometimes called nucleus sampling. The model considers only the smallest set of tokens whose cumulative probability adds up to `Top P`. Setting it to `0.9` means the model samples from the top 90% of likely tokens. Most providers recommend adjusting either temperature or Top P, not both at once. ### Top K [#top-k] Limits sampling to the top K most likely tokens at each step. Useful on providers and models that support it. A value of `40` is a common default. ### Frequency Penalty [#frequency-penalty] Discourages the model from repeating the same tokens that have already appeared in the output. A small positive value (e.g., `0.1`–`0.5`) reduces repetitive phrasing. Set to `0` to disable. ### Presence Penalty [#presence-penalty] Encourages the model to introduce new topics by penalizing tokens that have already appeared at all, regardless of frequency. Useful when you want more varied, exploratory answers. ### Max Steps [#max-steps] The maximum number of tool-use steps the model is allowed to take before the response ends. This is most relevant for [extension](/docs/guides/extensions)-heavy workflows where the model loops through multiple tool calls. Raising it allows longer agentic runs; lowering it keeps things tighter. ### Max Tokens [#max-tokens] Sets a hard cap on the number of tokens the model generates in a single response. Leave it empty to use the model's default. Set it explicitly when you want to prevent very long responses or stay within a cost budget. ### Seed [#seed] A fixed seed makes generation deterministic - the same prompt with the same seed should produce the same output. Useful for debugging or reproducibility testing. Not all providers honor this parameter. ## The Indicator Dot [#the-indicator-dot] When any parameter has been changed from its default, a small indicator dot appears on the config button. This is a visual reminder that the current chat has non-default settings. To reset everything back to defaults, open the panel and click the reset button. ## Leaving Fields Empty [#leaving-fields-empty] Leaving a field blank tells AgentOne to defer to the model or provider default for that parameter. This is the recommended approach unless you have a specific reason to change a value - provider-side defaults are usually tuned well for each model. ## Related [#related] * [Model Selector](/docs/guides/providers/model-selector) - switch the active model for this chat. * [Model Metadata](/docs/guides/providers/model-metadata) - understand context window, output limits, and capability flags. * [Chat Settings](/docs/desktop-app/settings/chat-settings) - global chat behavior like streaming and submit key. # Model Metadata Every model in AgentOne - whether from a built-in provider, a local provider, or a custom provider - has a set of metadata fields. These fields control how the model appears in the UI and which features are offered when it is selected. You edit or override these fields when adding a custom model or using `Add Model Override` on a built-in provider. See [Built-in Providers](/docs/guides/providers/built-in-providers) and [Custom Providers](/docs/guides/providers/custom) for where to find those controls. ## Fields [#fields] ### Model ID [#model-id] The exact identifier the provider uses for this model in API requests. This must match what the provider's API expects - for example `gpt-4o`, `claude-opus-4-5`, or `gemma3:12b`. Getting this wrong causes API errors. ### Display Name [#display-name] The human-readable label shown in the [model selector](/docs/guides/providers/model-selector) and throughout the app. This can be anything you find useful - it is never sent to the provider. If left blank, AgentOne falls back to the Model ID. ### Context Window [#context-window] The total number of tokens the model can consider in a single request, counting both the prompt (including message history and system instructions) and the response. AgentOne displays this value in informational UI. It does not enforce truncation on your behalf - that is the provider's responsibility - but having accurate metadata helps you understand the model's limits. ### Max Output Tokens [#max-output-tokens] The maximum number of tokens the model can generate in a single response. This is informational metadata separate from the [Max Tokens setting in Model Config](/docs/guides/providers/model-config#max-tokens), which is a per-request cap you set yourself. ### Supports Text [#supports-text] Whether this model should be treated as capable of normal text conversation. Disabling this would hide the model from text chat contexts. Nearly all models should have this enabled. ### Supports Tools [#supports-tools] Whether this model should be treated as tool-capable. When enabled, AgentOne allows [extensions](/docs/guides/extensions) to offer tools to this model during a chat. Disable it for models you know do not support function calling, so AgentOne does not send a tool schema that the model would ignore or mishandle. ### Supports Images [#supports-images] Whether this model should be treated as capable of processing image attachments. When enabled, users can attach images in chats using this model and the image data is included in the request. Disable it for text-only models. ### Supports Attachments [#supports-attachments] Whether the model accepts non-image file attachments. This controls the **Attachments** badge and filter in the model selector. ### Supports Reasoning [#supports-reasoning] Whether the model offers reasoning capabilities. This controls the **Reasoning** badge and filter in the model selector. ## Why Accurate Metadata Matters [#why-accurate-metadata-matters] AgentOne uses these flags to decide what to offer in the UI. If `Supports Tools` is off, select `Disable` under [Tool Behavior](/docs/guides/providers/model-config#tool-behavior) to use the model without injecting extensions. If `Supports Images` or `Supports Attachments` is off, the corresponding attachment pathway is not used. Incorrect metadata can cause subtle misbehavior - either features being silently hidden or the API receiving parameters it cannot handle. For built-in models, AgentOne maintains metadata based on publicly available information. If a model's capabilities change (for example, a previously text-only model gains tool support in an update), you can add a model override to correct the flags without waiting for an app update. See [Built-in Providers](/docs/guides/providers/built-in-providers#model-overrides). ## Related [#related] * [Model Config](/docs/guides/providers/model-config) - per-chat inference parameters like temperature and max tokens. * [Model Selector](/docs/guides/providers/model-selector) - where display names and grouping are visible to users. * [Extensions](/docs/guides/extensions) - tools that require `Supports Tools` to be enabled. # Model Selector The model selector lives at the bottom of every chat window, in the [composer](/docs/desktop-app/getting-started/desktop-layout#composer). It shows the currently active provider and model name, and lets you switch models at any point in the conversation - even mid-thread. ## Opening the Selector [#opening-the-selector] Click the model name in the composer bar. A panel opens showing every model available to you, grouped by provider. On narrower windows, the same panel opens as a drawer instead of a popover, keeping the interface usable at any window size. ## Searching for a Model [#searching-for-a-model] Type in the search field at the top of the selector to filter models by name or ID. This is the fastest way to jump to a specific model when you have many providers configured. ## Filtering by Capability [#filtering-by-capability] Open the filter menu beside the search field to show only models with particular capabilities: * **Images** * **Tools** * **Attachments** * **Reasoning** When you select more than one filter, a model must support all selected capabilities to remain visible. Capability badges beside each model show what it supports. ## How Models Are Grouped [#how-models-are-grouped] Models are organized under their provider's heading. The order follows roughly: AgentOne models (when signed in), then built-in cloud providers in alphabetical order, then local providers, then custom providers. Disabled providers do not appear. ## What Makes a Model Visible? [#what-makes-a-model-visible] A model appears in the selector only when all of these are true: * Its parent provider is enabled in `Settings` -> `Providers`. * At least one model has been configured for that provider (either discovered automatically or added manually). * For local providers, the runtime is reachable and has models loaded. * You have not hidden AgentOne models via `Settings` -> `Account` -> `Hide AgentOne models` (applies to AgentOne-hosted models only). If you expect a model to appear but it does not, the most common fixes are enabling its provider and checking that the provider has at least one model entry. See [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models) for more detail. ## Switching Models in an Existing Chat [#switching-models-in-an-existing-chat] You can switch models at any point in a conversation. The new model takes effect for the next message you send. Earlier messages in the thread are not affected - they remain attributed to the model that generated them. This makes it easy to start a conversation with one model and continue with another without losing the context already in the thread. ## Related [#related] * [Model Config](/docs/guides/providers/model-config) - adjust temperature, top-p, max tokens, and other settings for the active chat. * [Built-in Providers](/docs/guides/providers/built-in-providers) - enable cloud providers so their models appear here. * [Local Providers](/docs/guides/providers/local-providers) - connect Ollama or LM Studio. * [Custom Providers](/docs/guides/providers/custom) - add OpenAI-compatible endpoints with your own models. Model selector open showing grouped providers and models, with the search field filtering the list to show results matching a query. # Local LLMs with Ollama ## What is Ollama? [#what-is-ollama] [Ollama](https://ollama.com) is a tool that lets you run open-source AI models on your computer. This is useful if you want to: * **Use models offline** without internet or API keys * **Keep data private** (nothing leaves your machine) * **Avoid API costs** from cloud providers * **Experiment with different models** easily AgentOne includes a built-in Ollama provider, so you can chat with models like Gemma, Mistral, Llama, and Qwen right from the app without setting up a custom provider first. ## Install Ollama and Download a Model [#install-ollama-and-download-a-model] First, let's install Ollama and download a model to use locally. ### Download and Install Ollama [#download-and-install-ollama] Visit [ollama.com](https://ollama.com) and download Ollama for your operating system (macOS, Linux, or Windows). Follow the installation instructions for your OS. Once installed, Ollama will run as a background service. To verify the installation, open a terminal and run: ```bash ollama --version ``` If it shows a version number, you're good to go! ### Download a Model [#download-a-model] Ollama comes with access to many open-source models. Let's download **Gemma 4 4B** - a lightweight, fast model that's perfect for local use. Open your terminal or command prompt. Run: ```bash ollama pull gemma4:e4b ``` This downloads the model (about 9.6GB). Depending on your internet speed, this may take a while! Once complete, list your installed models to make sure everything is there: ```bash ollama list ``` You should see `gemma4:e4b` in the list. ### Ensure the Server is running [#ensure-the-server-is-running] On macOS and Linux, the server should be running by default. Try opening [http://localhost:11434/v1/models](http://localhost:11434/v1/models) in your browser to see if it is (you should see some formatted data). If the server is not running, you may need to run `ollama serve` first or download the Ollama desktop app and open it. You can browse [ollama.com/library](https://ollama.com/library) to see all available models. Just replace `gemma4:e4b` with any model name (e.g., `mistral`, `qwen`). ## Use the Built-in Ollama Provider in AgentOne [#use-the-built-in-ollama-provider-in-agentone] Now let's enable Ollama in AgentOne. ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` in the bottom left of the sidebar, then click `Providers`. ### Find Ollama Under Local Providers [#find-ollama-under-local-providers] Scroll to the `Local Providers` section and expand `Ollama`. ### Confirm the Base URL [#confirm-the-base-url] By default, Ollama uses: * **Base URL**: `http://127.0.0.1:11434/v1` AgentOne already creates this built-in provider for you, so you do not need to add it manually. Providers settings page with Local Providers expanded and Ollama visible, showing the built-in Ollama entry and its base URL. #### Auto-Detect Models [#auto-detect-models] In the `Models` section, click the `Auto` button. AgentOne will query your Ollama server and find available models. If auto-detection succeeds, you'll see `gemma4:e4b` in your model list. Done! #### Manual Fallback [#manual-fallback] If auto-detection fails, click `Add Model` and enter: * **Model ID**: `gemma4:e4b` * **Display Name**: `Gemma 4 (4B)` (or whatever you prefer) Leave the capability toggles at their defaults unless you know the model should behave differently. #### Keep Ollama Enabled [#keep-ollama-enabled] Make sure the Ollama provider's switch is enabled. Once a model is listed there, it becomes available in AgentOne's model selector. ## Use Gemma in AgentOne [#use-gemma-in-agentone] Your Ollama provider is ready. You can now: * **Toggle it on/off** with the provider switch * **Switch to Gemma 4** in the model selector * **Chat normally** just like you would with a cloud provider, but locally. The first time you chat with Gemma, it may take a few seconds to load into memory. Subsequent messages will be faster. ## Tips & Troubleshooting [#tips--troubleshooting] ### Ollama isn't responding [#ollama-isnt-responding] * Make sure Ollama is running (check System Preferences on macOS or Services on Windows/Linux) * Verify the base URL is `http://127.0.0.1:11434/v1` with `/v1` at the end and `http` instead of `https` ### Model loading is slow [#model-loading-is-slow] * Gemma 4 (4B) is lightweight, but still takes a moment to load. Stick with it... it gets faster after the first use. * If you want a faster experience, try a smaller model from the model library ### Want to try other models? [#want-to-try-other-models] Visit the [Ollama library](https://ollama.com/library), run `ollama pull `, then click `Auto` again or add the model manually in the built-in Ollama provider. For help, reach out on the [AgentOne Forum](https://forum.agent-one.dev) or [Discord](https://www.agent-one.dev/discord). # OpenAI OpenAI is the maker of the GPT model family. AgentOne includes OpenAI as a built-in provider, so all you need is an API key. ## Getting an OpenAI API Key [#getting-an-openai-api-key] ### Sign in to OpenAI [#sign-in-to-openai] Go to [platform.openai.com](https://platform.openai.com) and sign in or create an account. ### Open the API Keys page [#open-the-api-keys-page] In the left sidebar, click **API keys**, then click **Create new secret key**. Give it a name you will recognize (for example, "AgentOne"). ### Copy the Key [#copy-the-key] OpenAI shows the key only once. Copy it immediately and keep it somewhere safe - you cannot view it again after closing the dialog. OpenAI requires a funded account or active subscription to use API keys. The playground and API are separate from a ChatGPT subscription - you may need to add credits at [platform.openai.com/settings/organization/billing](https://platform.openai.com/settings/organization/billing). ## Connecting OpenAI in AgentOne [#connecting-openai-in-agentone] ### Open Provider Settings [#open-provider-settings] In AgentOne, click `Settings` -> `Providers`. ### Find and Enable OpenAI [#find-and-enable-openai] Under `Built-in Providers`, locate **OpenAI**, expand it, and toggle the enable switch on. ### Paste Your Key [#paste-your-key] Paste your API key into the `API Key` field and click the save button. Once saved, OpenAI models such as GPT-4o appear in the [model selector](/docs/guides/providers/model-selector) in chat. ## Available Models [#available-models] AgentOne's built-in model list includes the major GPT-4o and o-series models. If OpenAI releases a new model that is not yet in the list, you can add it manually using `Add Model Override`. See [Built-in Providers](/docs/guides/providers/built-in-providers#model-overrides) for how. ## Troubleshooting [#troubleshooting] * **401 Unauthorized**: the API key is wrong or was not saved. Re-paste and save again. * **429 Too Many Requests / quota error**: you have hit your usage limit. Check billing at platform.openai.com. * **Model not showing**: confirm the provider is enabled and has at least one model entry. For more help, see [Providers and Models Troubleshooting](/docs/desktop-app/troubleshooting/providers-and-models). # AppImage Need help? [Join our Discord server.](https://www.agent-one.dev/discord) The AppImage is the primary download option on the AgentOne website and works on virtually any Linux distribution without installation. ## Download from agent-one.dev [#download-from-agent-onedev] ### Download the AppImage [#download-the-appimage] Navigate to [https://www.agent-one.dev/download](https://www.agent-one.dev/download) in your browser. Make sure the `Linux` tab is selected, then download the `.AppImage` file. ### Make it executable [#make-it-executable] Open a terminal and navigate to the directory where the file was downloaded (usually `~/Downloads`). Then run: ```bash chmod +x AgentOne_*.AppImage ``` ### Run AgentOne [#run-agentone] Double-click the AppImage file in your file manager, or run it from the terminal: ```bash ./AgentOne_*.AppImage ``` ## Download from GitHub Releases [#download-from-github-releases] If you followed the steps in the [Download from agent-one.dev](#download-from-agent-onedev) section, you can skip this section. ### Find AgentOne on GitHub Releases [#find-agentone-on-github-releases] Open [https://github.com/AgentOne-Dev/agent-one-public/releases](https://github.com/AgentOne-Dev/agent-one-public/releases). ### Select the latest release [#select-the-latest-release] Usually, the latest release is the first release on the list. You'll see a green `Latest` badge next to the latest stable release. If the release has a `Pre-release` badge or title, don't use it unless you're a developer. GitHub Releases page showing the latest release with a green "Latest" badge Once you've found the latest release, click on its title (for example, `AgentOne 1.0.0`) to navigate to that release. ### Download the AppImage [#download-the-appimage-1] Scroll to the bottom of the release page and expand the `Assets` accordion. Look for a file named `AgentOne_x.x.x_amd64.AppImage` and click on it to download it. ### Make it executable and run [#make-it-executable-and-run] Open a terminal, navigate to the directory where the file was downloaded, then run: ```bash chmod +x AgentOne_*.AppImage ./AgentOne_*.AppImage ``` # Arch Linux Need help? [Join our Discord server.](https://www.agent-one.dev/discord) ## Install from the AUR [#install-from-the-aur] The easiest way to install AgentOne on Arch Linux is through the AUR package [`agent-one-bin`](https://aur.archlinux.org/packages/agent-one-bin). ### Install with an AUR helper [#install-with-an-aur-helper] If you have `yay` installed, run: ```bash yay -S agent-one-bin ``` You can also use other AUR helpers like `paru`: ```bash paru -S agent-one-bin ``` ### Launch AgentOne [#launch-agentone] Once the installation is complete, you can launch AgentOne from your application menu or by running `agent-one` in your terminal. # Debian & Ubuntu Need help? [Join our Discord server.](https://www.agent-one.dev/discord) There are several ways to install AgentOne on Debian and Ubuntu. We recommend installing from agent-one.dev. ## Install from agent-one.dev [#install-from-agent-onedev] ### Download the .deb file [#download-the-deb-file] Navigate to [https://www.agent-one.dev/download](https://www.agent-one.dev/download) in your browser. Make sure the `Linux` tab is selected, then download the `.deb` file. ### Install the package [#install-the-package] Open a terminal and navigate to the directory where the file was downloaded (usually `~/Downloads`). Then run: ```bash sudo dpkg -i AgentOne_*.deb sudo apt-get install -f ``` The second command resolves any missing dependencies. ### Launch AgentOne [#launch-agentone] Once the installation is complete, you can launch AgentOne from your application menu or by running `agent-one` in your terminal. ## Install from GitHub Releases [#install-from-github-releases] If you followed the steps in the [Install from agent-one.dev](#install-from-agent-onedev) section, you can skip this section. ### Find AgentOne on GitHub Releases [#find-agentone-on-github-releases] Open [https://github.com/AgentOne-Dev/agent-one-public/releases](https://github.com/AgentOne-Dev/agent-one-public/releases). ### Select the latest release [#select-the-latest-release] Usually, the latest release is the first release on the list. You'll see a green `Latest` badge next to the latest stable release. If the release has a `Pre-release` badge or title, don't use it unless you're a developer. GitHub Releases page showing the latest release with a green "Latest" badge Once you've found the latest release, click on its title (for example, `AgentOne 1.0.0`) to navigate to that release. ### Download the .deb file [#download-the-deb-file-1] Scroll to the bottom of the release page and expand the `Assets` accordion. Look for a file named `AgentOne_x.x.x_amd64.deb` and click on it to download it. ### Install the package [#install-the-package-1] Open a terminal and navigate to the directory where the file was downloaded. Then run: ```bash sudo dpkg -i AgentOne_*.deb sudo apt-get install -f ``` ### Launch AgentOne [#launch-agentone-1] Once the installation is complete, you can launch AgentOne from your application menu or by running `agent-one` in your terminal. ## Other Options [#other-options] You can also install AgentOne via the [Snap Store](/docs/installation/linux/snap), which works on any distribution with snap support. # Fedora & RHEL Need help? [Join our Discord server.](https://www.agent-one.dev/discord) There are two primary ways to install AgentOne on Fedora and RHEL. We recommend installing from agent-one.dev. ## Install from agent-one.dev [#install-from-agent-onedev] ### Download the .rpm file [#download-the-rpm-file] Navigate to [https://www.agent-one.dev/download](https://www.agent-one.dev/download) in your browser. Make sure the `Linux` tab is selected, then download the `.rpm` file. ### Install the package [#install-the-package] Open a terminal and navigate to the directory where the file was downloaded (usually `~/Downloads`). Then run: ```bash sudo dnf install ./AgentOne-*.rpm ``` Alternatively, you can use `rpm` directly: ```bash sudo rpm -i AgentOne-*.rpm ``` ### Launch AgentOne [#launch-agentone] Once the installation is complete, you can launch AgentOne from your application menu or by running `agent-one` in your terminal. ## Install from GitHub Releases [#install-from-github-releases] If you followed the steps in the [Install from agent-one.dev](#install-from-agent-onedev) section, you can skip this section. ### Find AgentOne on GitHub Releases [#find-agentone-on-github-releases] Open [https://github.com/AgentOne-Dev/agent-one-public/releases](https://github.com/AgentOne-Dev/agent-one-public/releases). ### Select the latest release [#select-the-latest-release] Usually, the latest release is the first release on the list. You'll see a green `Latest` badge next to the latest stable release. If the release has a `Pre-release` badge or title, don't use it unless you're a developer. GitHub Releases page showing the latest release with a green "Latest" badge Once you've found the latest release, click on its title (for example, `AgentOne 1.0.0`) to navigate to that release. ### Download the .rpm file [#download-the-rpm-file-1] Scroll to the bottom of the release page and expand the `Assets` accordion. Look for a file named `AgentOne-x.x.x-1.x86_64.rpm` and click on it to download it. ### Install the package [#install-the-package-1] Open a terminal and navigate to the directory where the file was downloaded. Then run: ```bash sudo dnf install ./AgentOne-*.rpm ``` ### Launch AgentOne [#launch-agentone-1] Once the installation is complete, you can launch AgentOne from your application menu or by running `agent-one` in your terminal. # Linux Setup Guide AgentOne is available on Linux in several package formats. The recommended installation method depends on your distribution. ## Select Your Distribution [#select-your-distribution] Run AgentOne on any distro without installing Install from the AUR with yay or paru Install using a .deb package Install using an .rpm package Install via Snap on any supported distro # Snap Store Need help? [Join our Discord server.](https://www.agent-one.dev/discord) AgentOne is available on the [Snap Store](https://snapcraft.io/agent-one) and works on any Linux distribution with snap support. If you have an app center that supports Snapcraft installed, open it and search `AgentOne`, then install AgentOne by following the steps in your app-store. ## Install from the Snap Store [#install-from-the-snap-store] ### Install AgentOne [#install-agentone] Open a terminal and run: ```bash sudo snap install agent-one ``` ### Launch AgentOne [#launch-agentone] Once the installation is complete, you can launch AgentOne from your application menu or by running `agent-one` in your terminal.