This is the full developer documentation for fxbot # This page isn't here > The page you asked for isn't on fxbot.sh. Try the [home page](/), the [docs](/docs/), or the [SDK](/sdk/). # fxbot docs > fxbot: AI assistants that do real work, built your way. Each one chats, remembers, works on a computer of its own, and runs tasks on a schedule, on any model, hosted or local, from any browser or the fxbot app on your phone. fxbot is AI assistants that do real work, built your way. Each one chats, remembers, works on a computer of its own, and runs tasks on a schedule. Pick its model, hosted or local, its look, and what it can do with [plugins](/docs/explanation/core-and-plugins/), and talk to it from any browser, or the fxbot app on your phone, with [web pairing](/docs/how-to/reach-it-from-your-phone/). fxbot is free and open source, and runs on a machine of your own. New to it? Start with the tutorial, [Your first fxbot](/docs/tutorials/first-fxbot/), which puts fxbot on your phone too, or [ask your AI agent to set it up](/docs/tutorials/set-up-with-an-agent/). Already set up? Put it on [your phone](/docs/how-to/reach-it-from-your-phone/) or [your computer](/docs/how-to/reach-it-from-your-computer/). The docs are in four parts, each for a different need. ## Tutorials A guided first run, from a fresh machine to a chat. * [Your first fxbot](/docs/tutorials/first-fxbot/) * [Set up with your AI agent](/docs/tutorials/set-up-with-an-agent/) ## How-to guides Steps for one task, when you know what you want. * [Reach it from your phone](/docs/how-to/reach-it-from-your-phone/) * [Reach it from your computer](/docs/how-to/reach-it-from-your-computer/) * [Reach it from other devices](/docs/how-to/reach-it/) * [Pair another device](/docs/how-to/pair-another-device/) * [Add a provider](/docs/how-to/add-a-provider/) * [Add a plugin](/docs/how-to/add-a-plugin/) * [Add a skill](/docs/how-to/add-a-skill/) * [Add an MCP server](/docs/how-to/add-an-mcp-server/) * [Give bots a computer](/docs/how-to/give-bots-a-computer/) * [Talk with several bots in a room](/docs/how-to/talk-in-a-room/) * [Start a chat over with /fresh](/docs/how-to/start-fresh/) * [Let bots dream](/docs/how-to/let-bots-dream/) * [Give a bot a routine](/docs/how-to/give-a-bot-a-routine/) * [Keep what a bot writes](/docs/how-to/keep-what-a-bot-writes/) * [Draw diagrams in chat](/docs/how-to/draw-diagrams-in-chat/) * [Let bots work together](/docs/how-to/let-bots-work-together/) * [Hand work to subagents](/docs/how-to/hand-work-to-subagents/) * [Give a bot a soul](/docs/how-to/give-a-bot-a-soul/) * [Choose how hard a bot thinks](/docs/how-to/choose-how-hard-a-bot-thinks/) * [Choose what a bot can do alone](/docs/how-to/choose-what-a-bot-can-do-alone/) * [Choose memory search's vectors](/docs/how-to/memory-search/) * [When a device can't connect](/docs/how-to/when-a-device-cant-connect/) * [Forward or map a port](/docs/how-to/forward-a-port/) * [Reach it with WireGuard](/docs/how-to/reach-it-with-wireguard/) * [Run your own TURN server](/docs/how-to/run-your-own-turn/) * [Run your own STUN server](/docs/how-to/run-your-own-stun/) * [Run your own relay](/docs/how-to/run-your-own-relay/) * [Serve it at its own name](/docs/how-to/tailscale-service/) * [Update to a new release](/docs/how-to/update/) * [Go back to an earlier release](/docs/how-to/go-back/) * [Back up fxbot](/docs/how-to/back-up/) * [Fix an install that stopped](/docs/how-to/fix-an-install/) * [Uninstall fxbot](/docs/how-to/uninstall/) * [Run a checkout beside a release](/docs/how-to/checkout-beside-release/) * [Cut a release](/docs/how-to/cut-a-release/) ## Providers How to connect each provider: signing in or making a key, its fields, its models, and its quirks. * [Vercel and AI Gateway](/docs/providers/vercel/) * [ChatGPT and Codex plans](/docs/providers/chatgpt/) * [Grok plans](/docs/providers/grok/) * [OpenRouter](/docs/providers/openrouter/) * [Hugging Face](/docs/providers/huggingface/) * [OrcaRouter](/docs/providers/orcarouter/) * [Nous Portal](/docs/providers/nous/) * [OpenAI](/docs/providers/openai/) * [Anthropic](/docs/providers/anthropic/) * [Google Gemini](/docs/providers/gemini/) * [DeepSeek](/docs/providers/deepseek/) * [Z.ai](/docs/providers/zai/) * [Qwen](/docs/providers/qwen/) * [Kimi](/docs/providers/kimi/) * [MiniMax](/docs/providers/minimax/) * [xAI](/docs/providers/xai/) * [Mistral](/docs/providers/mistral/) * [Groq](/docs/providers/groq/) * [Together AI](/docs/providers/together/) * [Fireworks AI](/docs/providers/fireworks/) * [DeepInfra](/docs/providers/deepinfra/) * [Cerebras](/docs/providers/cerebras/) * [NVIDIA](/docs/providers/nvidia/) * [OpenCode Zen and Go](/docs/providers/opencode/) * [Vertex AI](/docs/providers/vertex/) * [AWS Bedrock](/docs/providers/bedrock/) * [Azure OpenAI](/docs/providers/azure/) * [Cloudflare](/docs/providers/cloudflare/) * [Ollama](/docs/providers/ollama/) * [LM Studio](/docs/providers/lmstudio/) * [llama.cpp](/docs/providers/llamacpp/) * [vLLM](/docs/providers/vllm/) * [LiteLLM](/docs/providers/litellm/) ## Reference Facts to look up: settings, paths, commands, providers, and changes. * [Under the hood](/docs/reference/under-the-hood/) * [Configuration](/docs/reference/configuration/) * [What setup.sh creates](/docs/reference/install-layout/) * [Commands](/docs/reference/commands/) * [Providers](/docs/reference/providers/) * [The computer](/docs/reference/computer/) * [Web pairing](/docs/reference/web-pairing/) * [Changelog](/docs/reference/changelog/) ## Explanation How fxbot works, and why it works that way. * [Core and plugins](/docs/explanation/core-and-plugins/) * [Security model](/docs/explanation/security/) * [Releases and updates](/docs/explanation/releases/) * [Architecture](/docs/explanation/architecture/) * [Bots, chats, memories, and the library](/docs/explanation/bots-and-chats/) * [How web pairing works](/docs/explanation/web-pairing/) # Architecture > fxbot is one Node server around libfx, Postgres, and a web page. This page is about how those parts fit, and why there are so few of them. fxbot is one Node server around [libfx](https://fx.sh/docs/lib), Postgres, and a web page. This page is about how those parts fit, and why there are so few of them. ## One process [Section titled “One process”](#one-process) A release runs one Node process, in a container beside its database’s. It serves the built page and its API on the machine’s 127.0.0.1, runs every bot’s agent, and holds every key. A third container, unless it’s turned off, runs the local embedder, llama.cpp’s server, which turns text into vectors for memory search. There is no other service and no queue. Podman or docker restarts a container that crashes, and systemd starts them at boot. Records live in Postgres, and libfx keeps each chat’s session in files. ## The packages [Section titled “The packages”](#the-packages) The repository is a TypeScript monorepo, laid out after [eve](https://eve.dev): a core package with a client subpath, a thin server, and a UI on the client. The packages run as TypeScript source on Node 22.18 or newer. Only the app and this site have a build step. | Package | What it holds | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@fxbot/sdk` | The agent system: providers and their sign-ins, one libfx agent per provider, bots, settings, the library, MCP servers, each bot’s durable chat, its memories, and its searchable history, with the vectors that search by meaning uses. It keeps the records in Postgres, seals the secrets, and runs the migrations. | | `@fxbot/sdk/client` | A typed client for the server’s API, with the stream reader and the turn reducer a UI needs. It carries no credentials. | | `@fxbot/server` | HTTP and nothing more: `node:http` routes over the SDK, body limits, and status codes. It reads the settings, serves the page, and asks the machine for updates. | | `@fxbot/ui` | The app: Vite, React, and shadcn/ui, built on `@fxbot/sdk/client` alone. | | `@fxbot/website` | This site, built to static pages. | Everything about bots lives in the SDK, so another server or UI could be built on it. The UI imports only the client entry, so no server code or secret can reach the browser. More is in the SDK’s [README](https://github.com/iammrduncan/fxbot/blob/main/packages/sdk/README.md). ## A message, end to end [Section titled “A message, end to end”](#a-message-end-to-end) 1. The page sends a message with an id it made, to `/api/profiles//messages`. 2. The SDK hands it to the libfx agent of the bot’s provider, with the bot’s instructions, its newest memories and the team’s, and its list of skills, and answers once libfx has stored the prompt. The same id sent again runs nothing new. 3. The page reads the chat as a stream of lines, from the start and then as they come. After a dropped connection it picks up where it left off. 4. libfx runs the turn, calling tools as the model asks, and writes each step to the session’s files. Because the turn lives on the server, a reload, a closed app, or a lost connection doesn’t stop it. A turn that a stopped server left open runs again when the server starts. ## Why one agent per provider [Section titled “Why one agent per provider”](#why-one-agent-per-provider) A libfx session belongs to the agent that started it, and an agent’s tools are fixed when it is made. So fxbot keeps one agent per provider, shared by the bots on it, and decides inside each tool which bots may use it. Moving a bot to another provider starts a new session, which [carries a summary](/docs/explanation/bots-and-chats/#starting-a-chat-over) of the old one. ## Kept small on purpose [Section titled “Kept small on purpose”](#kept-small-on-purpose) No web framework, no Next.js, no Vercel AI SDK, and no second agent runtime. A new abstraction waits for its second real use. The core holds only what every bot needs, and the rest comes as [plugins](/docs/explanation/core-and-plugins/). The repository’s [CONVENTIONS.md](https://github.com/iammrduncan/fxbot/blob/main/CONVENTIONS.md) has the rules. # Bots, chats, memories, and the library > A bot in fxbot is meant to be talked to for months, not for one task. This page is about what that asks of a bot, its chat, what it remembers, and the files it keeps. A bot in fxbot is meant to be talked to for months, not for one task. This page is about what that asks of a bot, its chat, what it remembers, and the files it keeps. ## A bot is a profile [Section titled “A bot is a profile”](#a-bot-is-a-profile) A bot is a name, instructions, a provider and a model, with how hard the model [thinks](/docs/how-to/choose-how-hard-a-bot-thinks/), and a look: one of 32 shapes in one of eleven colors, with a feeling, and something on its head, its face, and its body. It blinks and watches the pointer, hops while it works, looks at you while a call waits on an answer, smiles when it finishes, and sleeps when it has no provider. Up to three bots can be pinned to the top of the list. ![The New bot screen: a green bunny in a beanie, with the Shape tab open](/shots/look-desktop-light.png) ![The New bot screen: a green bunny in a beanie, with the Shape tab open](/shots/look-desktop-dark.png) ## One chat that lasts [Section titled “One chat that lasts”](#one-chat-that-lasts) Each bot has one long-running chat, a durable libfx session on the server. The page only shows it, so the chat survives a reload, a closed app, and a server restart, and a reply carries on while nobody watches. Everything in a chat is also kept in Postgres: what you and other bots said, the bot’s replies, its thinking, and its tool calls with their results. Each bot has a `chat_history` tool that searches all of that, across all its chats, and reads it in full around a match, in the order it happened. So a bot can look up what was said in an earlier chat, or long ago, and what it did about it. Each result says who it’s from, so another bot’s words don’t read as yours. It reaches only its own chats. Thinking and tool calls are kept since 0.6.0, each up to 64 KiB. ## A message to a working bot [Section titled “A message to a working bot”](#a-message-to-a-working-bot) You don’t wait for a bot to finish. A message you write while it works joins what it’s doing: a reply it’s writing is cut short, and it goes on with your words in mind. While a tool runs, your message waits for the tool, then joins, so the chat shows it where the bot took it in, among its steps. If nothing is running, it’s an ordinary turn. Some messages don’t join: * A picture of yours ends the running turn and runs next, since it’s usually a change of course. What the bot had done stays. * A turn that only passes something on, such as a routine’s result, takes no messages. A message waits for it, for the few seconds it takes. Up to 32 turns run at once, across all your bots, and a bot waiting on a long command holds its place. Past that, a turn waits for one to end. **Turns at once** in **Settings** › **General** changes it, from the next time fxbot starts. To end a turn instead, press **Stop**, where the send button is while the box is empty. It doesn’t wait for a running tool, and a command on the bot’s computer stops too. Anything you sent that the bot hadn’t read runs next, so nothing you wrote is lost. ## The sidebar [Section titled “The sidebar”](#the-sidebar) The sidebar lists your bots, with up to three pinned on top, larger. Drag a bot to move it, with a mouse, or with a finger after a moment’s hold, so a swipe still scrolls. Pinned bots move among themselves, and a bot you pin or unpin goes to the end of its group. Right-click a bot, or hold it on a phone, for its menu: **Edit**, **Pin** or **Unpin**, **Default bot**, and **Delete**. ![A bot's menu in the sidebar: Edit, Pin, Default bot, and Delete](/shots/menu-desktop-light.png) ![A bot's menu in the sidebar: Edit, Pin, Default bot, and Delete](/shots/menu-desktop-dark.png) ## The default bot [Section titled “The default bot”](#the-default-bot) One bot can be the default, picked in **Settings** › **General**, or with **Default bot** in its menu in the sidebar, where it wears a small star. Opening fxbot at its address then opens that bot’s chat, where it left off, instead of the list of bots. A link to another screen opens that screen, and a reload stays where it was. Deleting the bot clears the choice. ## Memories [Section titled “Memories”](#memories) A bot keeps what it learns as memories: what you prefer, facts about you and your work, decisions, and corrections. Each memory is one fact, in a sentence that stands on its own, of at most 1,000 characters. Memories belong to one bot, not to a chat, so a new chat, or a move to another provider, keeps them. Deleting the bot deletes them. [Team memories](#team-memories) are every bot’s. The bot saves them on its own, during its turns, with three tools. The chat shows each as a sentence: * `memory_save` saves a fact, as **Saved a memory**. Given `replaces` and a memory’s `mem:`, it changes that memory instead. Saving what is already saved, in other case or spacing, answers with the memory that’s there. A change that says what another memory says merges the two. * `memory_search` finds memories, as **Searched memories**. * `memory_forget` removes one that is wrong or no longer true, as **Forgot a memory**. A memory the bot saves records the message of the turn it was saved in. `memory_search` names that message, and `chat_history` reads it, with what came before and after. The newest memories are in the bot’s instructions, which fxbot sends on every turn: newest first, each with its `mem:` and date. They take at most 2% of the model’s context window, at 4 characters a token, or 8,000 characters when the window isn’t known. All the instructions together stay within libfx’s 64 KiB, so very long bot instructions leave less room for memories. When more memories don’t fit, a line says how many, and asks the bot to merge or forget ones that overlap. `memory_search` finds the rest. The section calls them notes, not instructions. The section changes only when a memory is saved, changed, or removed, not when one is searched, so the model’s prompt cache holds between changes. And since the instructions go with every turn, a memory saved in a long chat reaches that chat on its next turn. You see a bot’s memories under **Memories** on its edit screen, which **Edit** in its panel opens: newest first, each with its date, and **Saved by** the bot or **Added by you**. Search them there, add one with **Add a memory**, change one with its pencil button, or delete one. The bot sees your change on its next turn. ## Team memories [Section titled “Team memories”](#team-memories) Team memories are notes every one of your bots reads: who you are, how you like things done, and what your household or business is. They work as a bot’s own memories do, with a wider reach. * **You keep them** in **Settings** › **Memory**, under **Team memories**, to search, add, edit, and delete, as on a bot’s screen. Each says who saved it: you, a bot, or **a removed bot**, once that bot is deleted. Deleting a bot keeps the team memories it saved. * **A bot saves one** with `memory_save` and `team`, when you ask it to remember something for all your bots. Its `memory_search` finds the team’s with its own, marked `team`, and `memory_forget` removes one. * **To share one of a bot’s own,** choose **Share with every bot**, the people button beside it on the bot’s screen. It moves to the team’s list. * **In the instructions,** the team’s newest go after the bot’s own, under a header that calls them notes, not instructions. They take up to 1% of the model’s context window, or 4,000 characters when the window isn’t known. A change reaches every bot on its next turn, and a room, a routine’s run, and a subagent get them too. The same fact can be both a bot’s own and the team’s. Saving what the team already has answers with the one there. With the chat rooms plugin, each room keeps memories of its own as well: see [Give a room memories](/docs/how-to/talk-in-a-room/#give-a-room-memories). ## A soul, with the soul plugin [Section titled “A soul, with the soul plugin”](#a-soul-with-the-soul-plugin) With the [soul plugin](/docs/how-to/give-a-bot-a-soul/), each bot also has a soul: a few lines, in its own words, of who it is, how it sounds, and how it helps you. It writes it in a first meeting with you, and rewrites it when you ask. The soul goes first in the bot’s instructions, in every chat: its own, a room, a routine’s run, and a subagent. A line before it says your instructions come first where they differ, and that the soul never changes the bot’s rules or what it may do. So the split is: * **Instructions** are yours: the rules, which the bot can’t change. * **The soul** is the bot’s: its voice and its idea of its job, which it keeps up with you, in its own chat only. * **Memories** are facts: about you, your work, and what was decided. ## Search by words and by meaning [Section titled “Search by words and by meaning”](#search-by-words-and-by-meaning) `memory_search` and `chat_history` find matches in two ways at once: * **By words.** Any word of the search counts, also as the start of a longer word, and more matches rank higher. * **By meaning.** An embedding model turns each memory and message into a vector: a list of numbers that puts texts of close meaning close together. The search’s own vector finds the nearest. How close the nearest one is varies from search to search, so only matches within 0.05, in cosine distance, of the nearest count. The two lists are fused with reciprocal rank fusion, so a match in both ranks above a match in one. When there is no embedder, or it doesn’t answer within 5 seconds, search uses words alone, and still answers. The vectors come from a local embedder on the machine, on its CPU by default or on a GPU, or from a provider’s embedding model. How to choose: [Choose where memory search’s vectors come from](/docs/how-to/memory-search/). One loop in the server fills in the vectors that are missing, memories first, then messages, newest first, and the chat never waits for it. Each model has vectors of its own, so a new model means new vectors for everything. Until they are done, search uses the vectors the current model has made, and words. Vectors are kept in Postgres, with pgvector, beside the rows they belong to. A search compares the query with each of the bot’s vectors, with no index, since an index takes vectors of one size and each model has its own. Over 100,000 messages of one bot, that took about a quarter of a second when measured. ## Starting a chat over [Section titled “Starting a chat over”](#starting-a-chat-over) A chat starts over three ways, and all work the same. A model writes a summary of the chat so far, and the bot starts a new chat from it. The earlier messages show above a card with the summary, and stay searchable with `chat_history`. Pages open on the chat follow it to the new one. * **Moving a bot to another provider.** A session can’t move between agents, and fxbot runs one agent per provider, so a move starts a new chat. The old provider writes the summary, or the new one when the old can’t. The card says **Continued from** the old provider. * **`/fresh`,** built in since 0.10.0. A summary aimed at what you write next keeps what bears on it, and your message goes to the new chat. The card says **Started over**. See [Start a chat over with /fresh](/docs/how-to/start-fresh/). * **Idle compaction,** since 0.10.0. A long chat that sits with no message for 30 minutes is summarized while you’re away, so your next message starts fast: the bot reads the summary, not the whole chat again. The card says **Compacted while idle**, with a link to turn it off. ### Idle compaction [Section titled “Idle compaction”](#idle-compaction) Every minute, fxbot looks for a bot whose own chat has had no message for the time set in **Settings** › **General** › **Idle compaction**: 30 minutes, unless you choose 15, an hour, 2 hours, or **Off**. It compacts that chat only when all of these are true: * **It’s long:** its text is at least 120 KB, about 30,000 tokens: what was said, thought, and called, and the documents you sent. Images don’t count. A short chat starts fast anyway. * **Nothing runs:** no turn of the bot’s is running, and it isn’t waiting on you. * **It’s new since:** it hasn’t been tried since its last message. A summary that failed isn’t tried again until a new message comes, and a compacted chat isn’t compacted again until it grows. Only the bot’s own chat counts and is compacted here. A room, a routine’s run, or a subagent doesn’t keep it awake, and isn’t compacted with it. fxbot compacts one bot at a time, so many idle bots don’t send a burst of requests. A chat room is compacted too, with chat rooms 0.5.0, by the same setting and the same rules, as a whole: one summary for the room, which its lead writes, unless **Summarize with** names a model. Each bot’s next turn there starts from it. See [Start a room over](/docs/how-to/talk-in-a-room/#start-a-room-over). What the bot keeps, in its own chat’s instructions, in place of the chat. Its rooms, routines, and subagents don’t get it: * the summary, which keeps your requests and instructions in your words, what was decided and why, facts about you and your work, and each open task * the last messages word for word, up to 6,000 characters * a line that says the summary is for reference, and not to act on it alone **Summarize with**, under it, picks the model that writes the summary: each bot’s own, or a cheaper one you choose. A model on the bot’s provider reads the chat as the bot does; one on another provider reads its stored messages. When the model you chose has a window smaller than the chat, the bot’s own model writes the summary, and fxbot’s log says so. A message you send while a summary is being written calls it off, and goes to the chat as it was. A summary that fails changes nothing. ## The library [Section titled “The library”](#the-library) Chats hold files: images, PDFs, and text files you send, and documents bots save. A bot reads a PDF as the text fxbot finds in it, page by page: up to 60,000 characters in your message, and the rest with `library_read`. A PDF of scanned pages has no text to read. The library keeps one copy of each, by the SHA-256 of its bytes, so the same file sent twice, or by two bots, is one item. Each item is tagged with every bot and chat that saved it, which leads it back to where it came from, and it outlives a deleted bot. You see it two ways: across every bot, from the button beside Settings, and per bot, in the panel beside its chat. Bots reach it through three tools, `library_search`, `library_read`, and `library_save`, and only items tagged for them. A bot is tagged onto an item only by saving its exact bytes, so nothing passes from one bot to another through the library. Deleting an item removes fxbot’s copy for every bot. A chat that read a document keeps its text, and libfx keeps its own copy of an image until it ages out. ## Tools from MCP servers [Section titled “Tools from MCP servers”](#tools-from-mcp-servers) An MCP server gives its tools to all bots, or to the bots you choose. libfx fixes an agent’s tools when it is made, and one agent serves every bot on a provider. So each allowed tool goes to every agent, named after its server, and refuses to run inside a bot that wasn’t chosen. Adding a server, or changing its tools, rebuilds the agents. How to add one is in [Add an MCP server](/docs/how-to/add-an-mcp-server/). # Core and plugins > fxbot is a small core that every install runs, and plugins that you add only if you want them. This page is about where that line falls, and why. fxbot is a small core that every install runs, and plugins that you add only if you want them. This page is about where that line falls, and why. ## The core [Section titled “The core”](#the-core) The core is what every bot needs, and what fxbot needs to run: * bots, each with its instructions and one long-running chat * providers: accounts, keys, and local model servers * the library, one copy of every file the chats hold * each bot’s memories, the team’s memories that every bot reads, and each bot’s history, which the bot can search by words and by meaning * the app, which installs on phones and desktops * releases, updates, and the database’s migrations * keys and tokens, sealed in Postgres It also holds the seams that plugins plug into: **Plugins** itself, which finds, adds, and updates them, and the plugin API, through which a plugin’s code changes fxbot. ## Plugins [Section titled “Plugins”](#plugins) Everything else is a plugin. A plugin carries any mix of three things, and at least one of them: * [skills](/docs/how-to/add-a-skill/), with instructions that a bot reads when a task needs them * [MCP servers](/docs/how-to/add-an-mcp-server/), which give bots tools from a remote service * [code](/docs/how-to/add-a-plugin/), which runs inside fxbot and can add screens, tools, its own tables and settings, and the turns it starts Each goes to all bots, or only to the ones you choose; its screens are for everyone. By default, fxbot shows only the plugins it vets, tagged **fxbot**, and a switch in Settings › Plugins shows the public registries too. What each part may do is in the [Security model](/docs/explanation/security/#vetted-plugins). The plugin API is the seam that most later features plug into. fxbot’s own plugins, such as chat rooms, use it as anyone’s do. ## Why the line is there [Section titled “Why the line is there”](#why-the-line-is-there) Every install runs the core, so everything in it costs every owner: code to keep safe, work on each request, and weight in the page. A plugin costs only the owners who add it. So a feature goes in the core only when every bot needs it, when plugins need it to plug in, or when fxbot needs it to run. A plugin that you haven’t added costs nothing: no process, no timer, no requests, and no space in the app outside **Plugins**. Removing one leaves the rest of fxbot as it was. When a feature can’t be built as a plugin, what’s missing is a seam. The core gets the smallest seam that the plugin needs, and the feature stays a plugin. fxbot’s own plugins use the same seams as anyone’s. # Releases and updates > fxbot gives people a version to stay on, while its owner keeps working on the next one. This page is about how releases are made, how an install moves between them, and why the database only moves forward. fxbot gives people a version to stay on, while its owner keeps working on the next one. This page is about how releases are made, how an install moves between them, and why the database only moves forward. ## A release is a merge into main [Section titled “A release is a merge into main”](#a-release-is-a-merge-into-main) One version covers the whole repository. Work happens on a branch named for the next release, and `npm run dev` runs from it. When it is ready, it merges into `main`, which holds releases, and updates to the site between them. The release workflow runs on `main`. When the version in `package.json` has no tag yet, it typechecks and builds, checks that no shipped migration changed, and builds fxbot’s image for amd64 and arm64 and pushes it to ghcr.io. Only then does it tag the version and publish the release, with its notes from `docs/releases/`. No tag points at a build that failed, and Settings never offers a release without an image. The [changelog](/docs/reference/changelog/) and each release’s notes are written by hand: the changelog in full, and the notes as a short post, for GitHub, Settings, and anywhere else. A release that adds migrations, bumps libfx, or needs a step by hand opens its changelog section with **Before upgrading**, and its notes say so above their list of changes, so Settings shows it before anything else. ## Installs stay where they are [Section titled “Installs stay where they are”](#installs-stay-where-they-are) An install stays on its release until someone chooses the next one. fx, which fxbot takes after, updates itself by default. fxbot doesn’t: you update when you are ready. Once a day, the server asks GitHub for the newest release, and **Settings** › **About** shows its notes and an **Update** button. `FXBOT_UPDATE_CHECK=off` stops the asking. Prereleases install only by name, so nobody lands on one by accident. ## Plugins move on their own [Section titled “Plugins move on their own”](#plugins-move-on-their-own) A plugin isn’t part of a release. fxbot checks each one’s repository every hour, and offers an update when its files change, whatever release the install runs. fxbot’s own plugins live in fxbot’s repository, so they change as soon as its `main` does, often before an install has updated fxbot itself. So each plugin with code says the oldest fxbot it runs on, as `minFxbot` in its `plugin.json`. An older install shows **Needs fxbot** for a version it can’t run, and keeps the one it has. The other way round, when a release breaks something plugins use, fxbot.sh lists it in `plugin-breaks.json`, and a plugin it would break stops as **Unsupported**, rather than breaking a bot halfway through a turn. Its files, settings, and tables stay until a version that fits arrives. Since 0.7.0. ## An image per release [Section titled “An image per release”](#an-image-per-release) An install runs three containers, from the release’s compose file: the app, from fxbot’s image for that version, its database, from pgvector’s Postgres image, and the local embedder for memory search, from llama.cpp’s server image, unless it’s turned off. Every machine then runs the same Node, the same Postgres, and pgvector, whatever its distro ships. `/opt/fxbot/.env` names the version that runs. The app doesn’t start containers itself, and has no podman or docker socket. **Update**, in Settings › About, writes a request into a folder the app shares with the machine. systemd sees it and runs the machine’s `fxbot` command, as root, which takes only a version from the request. The command downloads the release’s compose file and itself, pulls the images it doesn’t have yet, writes the new version, and recreates the app’s container. Running chats get up to 90 seconds to finish, the database keeps running, and the app is down for a few seconds. The command writes each step to a status file, which Settings shows, and the page reloads onto the new version once it answers. Nothing changes until the new release has downloaded, so a failed download leaves fxbot as it was. If the new app isn’t healthy within 5 minutes, the command goes back to the release it replaced by itself, restoring the backup the new app took before its migrations, if it ran any. Settings then shows why, from the new app’s last log lines. [Going back](/docs/how-to/go-back/) by hand later works the same way. ## Migrations [Section titled “Migrations”](#migrations) Each release’s database changes are numbered SQL files, which ship with the release and never change after it. A starting server runs the ones its database hasn’t, in one transaction, under a lock: all of them or none. The chats’ tables are the exception: they belong to Workflow’s Postgres World, which fxbot pins to one version, and its own setup migrates them when a release moves that version. They only move forward. Writing a way back for every change would double the work and rarely be tried, so fxbot takes a copy instead. Before any migration runs on a database in use, the server backs up the database and the data folder, whatever started it, and keeps the last five. In a release, `pg_dump` runs in the app’s container, whose image carries Postgres 17’s client. An older release refuses a database that a newer one migrated, so going back across a migration means restoring that copy. ## Built from the tag [Section titled “Built from the tag”](#built-from-the-tag) A release’s image is built by the release workflow from the commit its tag points at, with the packages in the lockfile. Compose names the exact version of each image, such as `0.3.0`, not `latest`. `setup.sh` and `fxbot update` take the compose file and the `fxbot` command from the release’s tag. Chats are libfx’s sessions, so a release that bumps libfx, or the Postgres World that keeps them, says so under **Before upgrading**. # Security model > fxbot is built for one person's machine. It keeps every secret on the server, sealed, and leaves who reaches it to you. This page is about why it works that way, and where its edges are. fxbot is built for one person’s machine. It keeps every secret on the server, sealed, and leaves who reaches it to you. This page is about why it works that way, and where its edges are. ## Loopback only, with no login [Section titled “Loopback only, with no login”](#loopback-only-with-no-login) fxbot listens on the machine’s 127.0.0.1 and has no accounts, so what sits in front of it decides who gets in. On the machine itself, that is whoever uses that machine. Through web pairing, the recommended way in, it is the devices you’ve paired, each with a key of its own that you approved. Through Tailscale, it is your tailnet’s access rules. Either way, each device is already known, so a second login in fxbot would be one more password guarding the same door, and a weaker one. The cost is that whoever reaches the address can use all of fxbot: every bot, every chat, every provider. So fxbot should never be open to a network directly, through port forwarding or [Tailscale Funnel](https://tailscale.com/kb/1223/funnel), and any other way in, such as a reverse proxy, needs a login of its own ([Reach it from other devices](/docs/how-to/reach-it/)). In a release install, fxbot runs in a container as the `fxbot` user, and compose publishes its port on the machine’s 127.0.0.1. Its database has no port on the machine. ## Keys sealed in Postgres [Section titled “Keys sealed in Postgres”](#keys-sealed-in-postgres) Every key and token fxbot stores is sealed in the SDK with AES-256-GCM before it reaches Postgres, with a fresh nonce each time, and bound to the record it belongs to. Postgres holds only ciphertext and never sees the key. fxbot doesn’t use pgcrypto, whose key would travel inside SQL and could reach Postgres’s logs. The key is a file, `/etc/fxbot/secret.key` in a release install, that only the server’s user reads. Compose mounts it into the app’s container, read-only. `sudo fxbot rotate-key` seals everything again under a new key, for when the old one may have leaked; a checkout uses `npm run rotate-key`. See [Commands](/docs/reference/commands/#fxbot-rotate-key). ## Nothing secret on the page [Section titled “Nothing secret on the page”](#nothing-secret-on-the-page) The page sends a key, or Vertex AI’s service account file, once, and never gets it back: a provider in a list says only whether it has a key or a sign-in. Device code and OAuth sign-ins run on the server, as attempts the page checks on. The page sees a link and a code, and never a verifier or a token. OpenRouter’s sign-in comes back to fxbot’s own address, where the server trades the code for a key with a verifier only it holds. The page’s code carries no credentials, and its build reads no `.env`. ## Files served as data [Section titled “Files served as data”](#files-served-as-data) The library serves what chats hold as data, never as a page. Images are checked from their bytes. Documents are served as plain text, with `nosniff` and a sandbox that runs nothing, even opened in a tab of their own. The library never serves HTML or SVG as themselves. The Pages plugin runs a bot’s HTML page in a sandboxed frame of its own, as [Keep what a bot writes](/docs/how-to/keep-what-a-bot-writes/) describes. ## Vetted plugins [Section titled “Vetted plugins”](#vetted-plugins) By default, fxbot finds and adds only the plugins on its own lists, which the project vets, tagged **fxbot**. Until you turn on **Show unvetted plugins** in **Settings** › **Plugins**, fxbot asks none of the public registries, and its server refuses to look at or add anything else: an MCP server by its address, a public registry’s entry, a skill from skills.sh, or a repository. Plugins you already added keep working either way. Vetting is the project’s choice of what to list, not a review of every version that follows. ## MCP servers [Section titled “MCP servers”](#mcp-servers) A remote MCP server’s tools are code fxbot doesn’t control, and a call may not be safe to run twice. Bots get only a server’s read-only tools until you allow others by name. The [permissions](/docs/how-to/choose-what-a-bot-can-do-alone/) plugin can ask before any tool call, a server’s included. Adding a server makes fxbot’s server fetch its address. So fxbot takes HTTPS only, and refuses local and private addresses, the tailnet’s included, unless you allow one for a server you run. A server’s key, headers, and OAuth client are sealed like a provider’s. A registry entry says who published it, checked by the registry, but not that its server is safe or theirs. Its page shows the server’s host, in red when it isn’t on the publisher’s domain, and nothing is saved before **Add**. If the entry changes between the page and **Add**, fxbot refuses and shows the page again. fxbot fetches its own lists every hour, GitHub’s MCP registry every hour while unvetted plugins are on or a server from it is installed, and the official registry only when you tick **Search everything**, which sends it your search words. It loads no icons from them. ## Skills [Section titled “Skills”](#skills) A skill is someone else’s instructions, which a bot follows like its own. fxbot shows a skill’s `SKILL.md` before you add it, and keeps it pinned to the commit of its repository that page came from. When its files change there, it waits for you to update it. Nothing in a skill runs: fxbot keeps only its text files, and bots read its scripts as text. With unvetted plugins on, each search sends its words to skills.sh, and adding a skill fetches its repository from GitHub. ## Plugins with code [Section titled “Plugins with code”](#plugins-with-code) A plugin with code runs inside fxbot, with everything fxbot can reach: its database, the keys it opens, every bot’s chats, and in a release, whatever fxbot’s container reaches. Adding one trusts its author as much as fxbot’s own. So fxbot shows its code before you add it, keeps it pinned to the commit of its repository that page came from, and waits for you when its files change there, showing what changed. Only the page code and CSS that its `plugin.json` names are served to the page. Its secret settings are sealed like a provider’s key, and the page never gets them back. ## What it doesn’t cover [Section titled “What it doesn’t cover”](#what-it-doesnt-cover) * Each message goes to the provider its bot uses, which sees the chat. Only a local model server keeps it on your network. With a provider’s embedding model for memory search, that provider also receives the text of every memory and message it turns into a vector. * There are no users, roles, or audit log inside fxbot. * The backups taken before migrations hold the database and the data folder, readable only by `fxbot`. The secrets in them stay sealed. # How web pairing works > How web.fxbot.sh opens your own fxbot over a WebRTC connection straight to it: the app and its frames, the relay, the keys, pairing, getting through NATs, and what each party sees. Web pairing opens your own fxbot on a phone or any computer, at web.fxbot.sh, over a WebRTC connection straight to it. Your fxbot listens only on its own machine, as always, and nothing on that machine is exposed. This page explains the parts and why they’re shaped this way. To set it up, see [Reach fxbot from your phone](/docs/how-to/reach-it-from-your-phone/). ## The parts [Section titled “The parts”](#the-parts) | Part | Where | What it does | | -------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | The **web-pairing** plugin | your fxbot | Keeps fxbot’s keys and its devices, talks to the relay, makes the WebRTC connections, and passes each device’s requests to fxbot’s own server | | The app | web.fxbot.sh | Keeps each device’s keys, pairs, connects, and draws the screens for pairing and devices | | A frame | `.fxbot.sh`, one for each paired fxbot | Runs your fxbot’s own page, plugins and all, which it gets through the connection | | The relay | web.fxbot.sh/signal | Passes sealed messages between a device and its fxbot until they connect | The app and the frames are static files, and the relay keeps nothing, so one Cloudflare Worker serves all three. Anyone can [run their own](/docs/how-to/run-your-own-relay/). ## Why a relay at all [Section titled “Why a relay at all”](#why-a-relay-at-all) Two ends can’t open a WebRTC connection until they’ve traded an offer, an answer, and the addresses each can be reached at. Something both can reach has to pass those, and a phone can’t reach fxbot, which listens on its machine only. So fxbot keeps one outgoing WebSocket to the relay while a device is paired, and a device calls it there. The relay can’t read what it passes: the two ends seal every message to each other’s keys first. It sees which fxbot is being called, by an address made from its keys, the IP addresses of both sockets, when, and how much. It doesn’t see which device, the addresses the two will connect at, or anything that crosses the connection afterwards. ## Keys [Section titled “Keys”](#keys) Your fxbot makes two keys the first time the plugin runs, and keeps them sealed in its database, so a backup carries them: * an X25519 key, for the handshakes with devices * an Ed25519 key, which it proves itself to the relay with Its address at the relay is a hash of both, so the relay can check that whoever listens there holds them. A fresh install makes new keys, and devices pair again. Each device makes an X25519 key when it pairs, which its browser keeps and can’t export: the page can use it, but not read it. To fxbot, a device is that key’s public half, with no password, no token, and no expiry. ## Pairing [Section titled “Pairing”](#pairing) Pairing starts where fxbot already trusts you: its own **Settings**, on the machine, over Tailscale or an SSH tunnel, or a device that’s already paired. Only that side shows a code, so nobody can hand you one that grants them access. It makes a ticket, kept in memory for 10 minutes, with a 32-byte secret. The QR code’s link carries the secret, after a `#`, which browsers never send to a server. A typed code, such as `47-3816-0925`, is too short to carry it, so it runs [CPace](https://datatracker.ietf.org/doc/draft-irtf-cfrg-cpace/) first, which turns the code into a shared key and allows one guess per code: the `47` finds your fxbot at the relay, and the eight digits stay between the two ends. Then the device runs a [Noise](https://noiseprotocol.org) handshake (IKpsk2) with fxbot’s key and the secret. Both sides end with the same handshake hash, and show six digits made from it. If someone in the middle had run two handshakes, the digits wouldn’t match. You check them and approve on the side that showed the code, and fxbot adds the device. ## Connecting [Section titled “Connecting”](#connecting) Each time the app opens, comes back to the front, or changes network, the device runs a Noise IK handshake through the relay. Its first message carries a counter that only goes up, so fxbot refuses one it has seen. fxbot finds the device by its key, refuses one it doesn’t know or has removed, and answers with its list of STUN and TURN servers. Then fxbot makes the WebRTC offer, and the device answers, each sealed by the handshake. The offer and answer carry each side’s certificate fingerprint, and WebRTC’s own encryption, DTLS, checks the connection against them. So the connection belongs to the two keys that paired. Each side’s first message on it is a check made from the handshake too. After that the relay plays no part: everything goes over the connection, peer to peer. ## The app and the frame [Section titled “The app and the frame”](#the-app-and-the-frame) Your fxbot’s page expects to be served by fxbot itself: it asks `/api/…` for everything. In the frame, a small script and the frame’s service worker give that page what it expects: * **Requests** it makes go to the app, which sends each over a data channel of its own to fxbot, which answers it from its own server. A chat’s reply streams back as it comes. * **What it loads by address,** such as its scripts, images, a plugin’s styles, and the pages plugin’s frames, the service worker fetches the same way. Scripts and styles named by their hash are kept, so the app draws at once when you open it again. * **WebSockets,** such as the computer’s desktop, each get a data channel. Each fxbot’s frame is on a name of its own, so its page, and the plugins’ code in it, can’t reach the device’s keys or another fxbot’s frame. A request that comes through a device is marked, and the plugin’s own device routes refuse it, so code in the page can’t pair a device. ## Getting through [Section titled “Getting through”](#getting-through) Both ends sit behind NATs, as nearly every phone and home network does. Each asks a STUN server what public address it has, and they try each pair of addresses until one works. That covers most networks, with nobody passing the traffic. It doesn’t cover: | Case | Why | What works | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | A network that blocks UDP | WebRTC’s direct connections use UDP | A TURN server over TLS on 443; Tailscale | | A symmetric NAT against a typical home router | The NAT gives each destination a different port, so the address STUN saw is no use to the other side. About 40% of phone carriers do this. | A mapped or forwarded port at home; IPv6; TURN; Tailscale | | Carrier-grade NAT at home | A second NAT, your provider’s, sits in front of your router | IPv6 or a public address from your provider; TURN; Tailscale | fxbot checks its own side in advance, under **Settings** › **Web pairing** › **Reachability**, and the device checks its side as it connects. When nothing works in 15 seconds, the device says what each side found, and links to [the fix](/docs/how-to/when-a-device-cant-connect/). fxbot.sh runs no TURN server, which would carry everyone’s traffic. A TURN server of [your own](/docs/how-to/run-your-own-turn/) sees addresses and volume, never contents. ## What each party sees [Section titled “What each party sees”](#what-each-party-sees) | Who | Sees | Doesn’t see | | -------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | | fxbot.sh’s relay | Which fxbot is called, the IP addresses of both ends’ sockets, times, sizes | Which device, its addresses for the connection, anything you do | | Cloudflare, which runs the relay | What any website’s host sees: IP addresses and connection times | The same | | A STUN server | Each end’s public address, when it asks | Anything else | | Your own TURN server | Both ends’ addresses, times, and how much passes | What passes: it’s encrypted end to end | | web.fxbot.sh’s files | Nothing: they’re static, and the app’s code runs on your device | | The app’s code comes from web.fxbot.sh, so it’s only what that site serves. Its build prints a hash of each file, so anyone can compare what it serves with a build of the same release. ## Staying paired [Section titled “Staying paired”](#staying-paired) A pairing has no expiry. What could end it, and what keeps it: * **fxbot restarting or updating:** the keys are in its database, and it reconnects to the relay by itself. * **The relay restarting:** fxbot reconnects with a little randomness, and devices try again. * **A phone in the background:** iOS ends the connection within about a minute; the app reconnects when it comes back. * **Safari clearing a site after seven days:** it doesn’t for Home Screen apps, which is why an iPhone pairs there. * **The browser clearing storage:** the app asks the browser to keep its storage, and says whether it agreed. A second device or a passkey [pairs it again](/docs/how-to/pair-another-device/) from anywhere. * **A lost device:** remove it from any other. # Add a plugin > A plugin gives your bots more, or changes fxbot itself. It carries any mix of three things: - skills: instructions for a kind of task, which a bot reads when a task calls for them - MCP servers: tools from a remote service - code, which runs inside fxbot and can add a screen, a group in the sidebar, tools, and settings of its own A plugin gives your bots more, or changes fxbot itself. It carries any mix of three things: * **skills**: instructions for a kind of task, which a bot reads when a task calls for them * **MCP servers**: tools from a remote service * **code**, which runs inside fxbot and can add a screen, a group in the sidebar, tools, and settings of its own By default, fxbot shows only the plugins it vets, tagged **fxbot**. Each has a page in the [plugin directory](/plugins/), which says what it carries. 1. Open **Plugins**, the puzzle button at the bottom of the sidebar, and choose **Browse**. fxbot’s picks you haven’t added are listed, each with what it carries beside its name. Each plugin’s icon is drawn from who made it and its name, so it looks the same wherever it shows, here and on [fxbot.sh](https://fxbot.sh). 2. Choose one to open its page. fxbot reads it at its newest version, and the page shows what it carries, with **Docs**, a link to its guide here, for one of fxbot’s own. For code, under **Runs inside fxbot**, choose **Read** to see each file: code runs with everything fxbot can reach. 3. Choose the **Add** button, which names the plugin. fxbot shows it under **Installed**, with what it carries, and what it adds to the app shows at once. Its name there opens its page again, read from the files it runs, with **Settings** in place of **Add**. 4. To change its settings, open its tab in **Settings**. Each plugin has one, with its bots, settings, log, updates, and **Remove**, and **Docs** at the top when its page has it. A secret setting is sealed, and the page never shows it again. A plugin’s MCP servers are on its tab too, each with its own sign-in or key and tools. 5. To give it to some bots only, choose **Choose** under **Bots**, and switch it on for each bot that should have it. Its servers follow, and its screens are for everyone. ![The Plugins screen on Browse, with Essentials at the top and fxbot's picks below](/shots/plugins-desktop-light.png) ![The Plugins screen on Browse, with Essentials at the top and fxbot's picks below](/shots/plugins-desktop-dark.png) ## Essentials [Section titled “Essentials”](#essentials) **Essentials**, at the top of **Browse**, is what most people want from fxbot, and it’s what first-run setup offers. **Add the other 3** adds the ones you don’t have, in order, and shows how each went. One that fails doesn’t stop the rest. **What’s in it** lists them, each opening its page, where you can read its code. The pack is a shortcut, not a bundle: each plugin stays its own, so you can remove any of them, and the rest carry on. ## A plugin that needs another [Section titled “A plugin that needs another”](#a-plugin-that-needs-another) Some plugins build on another, such as one that installs programs on the computer. Its page says **Needs computer**, and **Add** waits until the computer is added. While it’s added, the computer can’t be removed. A bot that has it on and the computer off says **Needs computer on this bot** in its settings: switch the computer on for it too. ## Show unvetted plugins [Section titled “Show unvetted plugins”](#show-unvetted-plugins) fxbot’s picks are the plugins it vets. To see the rest, open **Settings** › **Plugins**, and turn on **Show unvetted plugins**. **Browse** then adds: * MCP servers from GitHub’s registry, with **Search everything** for the official one, and **Add by address**: see [Add an MCP server](/docs/how-to/add-an-mcp-server/) * skills from skills.sh: see [Add a skill](/docs/how-to/add-a-skill/) * **From GitHub**: any plugin with a `plugin.json`, by its repository, as `owner/repo`, or `owner/repo/folder` when it’s in a folder fxbot doesn’t vet any of these. Read what each one does before you add it. While the switch is off, fxbot asks none of those registries, and adds nothing but its picks. Plugins already installed keep working either way. ## fxbot’s plugins [Section titled “fxbot’s plugins”](#fxbots-plugins) * **chat-rooms**: rooms where several of your bots talk with you. Tag a bot with `@` to ask it, and bots hand work to each other by tagging: see [Talk with several bots in a room](/docs/how-to/talk-in-a-room/). * **computer**: a Linux computer for each bot, with a desktop you watch and take over, a terminal, a web browser, and files. Its engine is set up once on the machine: see [Give bots a computer](/docs/how-to/give-bots-a-computer/). ## When it goes differently [Section titled “When it goes differently”](#when-it-goes-differently) * **Its row says Off, with a reason.** Its code failed to load, or its folder is gone. The rest of fxbot runs. Its tab in **Settings** shows its log. * **Its page says it needs a newer fxbot.** **Add** stays off, and its code still shows. [Update fxbot](/docs/how-to/update/), then add it. * **Its row says Needs fxbot.** A newer version of it needs a newer fxbot than yours. The one you have keeps running, and you can update it once you’ve updated fxbot. * **Its row says Unsupported.** This fxbot broke something it uses, or fxbot’s list marks its version as bad. It doesn’t run, and the rest of fxbot does. Its tab in **Settings** says why, with **Update** when there’s a version that fits. Its files, settings, and tables are kept. A plugin that guards your bots, such as permissions, isn’t guarding them while it’s **Unsupported**, so see to it soon. * **Its tab says its page didn’t load.** Its code ran, and its part of the app didn’t. Update it, or ask its author. * **Settings says a plugin won’t run on the next release.** It shows above **Update**, so you can wait for the plugin’s update first. fxbot finds this by reading names in a plugin’s code, so it can miss a break, and it can flag a plugin that’s fine. * **Its row says Update available.** Its files changed in its repository. Open its tab in **Settings** and choose **Update to**: fxbot shows what changes, with the code to read, and moves only when you choose **Update**. If new code doesn’t load, the old version keeps running. * **A server it carries isn’t added.** A plugin’s remote MCP servers are added with it, under the same rules as any other server: from GitHub, an address on this machine or your network isn’t added. Its log says why. A server that runs a command on this machine isn’t used yet. * **A file is passed over.** Files over 2 MiB, and files that aren’t text, aren’t kept. **Remove**, on its tab in **Settings**, runs the plugin’s own cleanup, then removes its tables, its settings, its files, and the servers it added. To write a plugin, see [Write a plugin](/sdk/how-to/write-a-plugin/) in the SDK’s pages. # Add a provider > A provider is where a bot's model runs. Open Settings › Providers, choose Add provider, and pick one: sign in with an account, use a key, a cloud, or a server on your own machine. A provider is where a bot’s model runs. Open **Settings** › **Providers**, and choose **Add provider**. First-run setup shows the same page. ![The Add a provider page in Settings, with sign-ins first, then providers that take a key](/shots/providers-desktop-light.png) ![The Add a provider page in Settings, with sign-ins first, then providers that take a key](/shots/providers-desktop-dark.png) The page groups providers by how they connect: **Sign in**, **Use a key**, **Clouds**, and **On your machine**, with **Custom** at the end of the first row. **Search** finds any of them, and about 175 more from [models.dev](https://models.dev). Each provider’s card has **Help**, which opens its own page in these docs. ## Sign in with an account [Section titled “Sign in with an account”](#sign-in-with-an-account) For **ChatGPT and Codex**, **Grok**, **OpenRouter**, **Hugging Face**, and **OrcaRouter**. There’s nothing to copy: each sign-in gives fxbot a key or a token, which it keeps sealed. 1. Tap the provider. ChatGPT and Grok start at once. For the others, choose **Sign in with** its name. 2. Most show a code. Open the link on any device, or scan the QR with your phone, sign in, and enter the code. Leave the page open: it finishes by itself. 3. OpenRouter shows **Continue to OpenRouter** instead. Approve fxbot in the tab it opens, and it comes back to fxbot. When fxbot’s address is plain HTTP, such as `http://192.168.1.20:8787`, OpenRouter shows a code to paste instead. **Didn’t come back? Use a code instead** asks for one too. If it fails: * A code that runs out says so, with **Start again**. * A ChatGPT account or workspace must allow device code sign-in. The error says how to turn it on. * After a failed refresh, the provider’s **Sign in again**, in **Settings** › **Providers**, starts a new sign-in. ## Use a key [Section titled “Use a key”](#use-a-key) For the gateways and labs under **Use a key**, from AI Gateway and OpenAI to Groq and Nous Portal. 1. Tap the provider. Its card links straight to the page where its keys are made, says what to pick there, and what it costs to start. 2. Fill in any field it asks for, such as Qwen’s region. 3. Paste the key, and choose **Add**. fxbot checks it with the provider first. A key the provider refuses says the status, and what it most likely means. To change a key later, use the provider’s **Replace key**. ## A cloud [Section titled “A cloud”](#a-cloud) For **Vertex AI**, **AWS Bedrock**, **Azure OpenAI**, and **Cloudflare**, each with a field or two of its own: * **Vertex AI:** choose your service account’s JSON key file. fxbot makes its own short-lived tokens from it. See [Vertex AI](/docs/providers/vertex/). * **AWS Bedrock:** a Bedrock API key, and its region. See [AWS Bedrock](/docs/providers/bedrock/). * **Azure OpenAI:** your resource’s name, its key, and your deployments’ names. See [Azure OpenAI](/docs/providers/azure/). * **Cloudflare:** an API token for Workers AI, and your account ID. See [Cloudflare](/docs/providers/cloudflare/). ## A server on your machine [Section titled “A server on your machine”](#a-server-on-your-machine) For **Ollama**, **LM Studio**, **llama.cpp**, **vLLM**, and **LiteLLM**. fxbot looks for each at its usual address when the page opens, and marks one that answers **Found here**. 1. Tap the server. Its usual address is filled in. 2. Add a key if the server wants one. 3. Set **Context window** if the server reports the wrong one, as Ollama does when it runs with a shorter context than the model’s. fxbot reaches a server at an HTTPS address, or a plain-HTTP one on localhost. In a release install, fxbot runs in a container, where localhost is the container, not your machine, and the card says so. Put the server behind HTTPS, such as with `tailscale serve`, and give that address. ## Custom [Section titled “Custom”](#custom) For any server that speaks OpenAI’s Chat Completions. 1. Give its address, with its `/v1`, such as `https://models.example.com/v1`. 2. Add a key if the server wants one. 3. If the server lists no models, type their ids, with commas between. ## Then [Section titled “Then”](#then) * Pick the provider’s model. The list shows what each model can do, where fxbot knows: its context window, tools, and images. fxbot fills in a good first model when the provider serves it. * **Make it the default for new bots** is on for your first provider. * Move a bot onto the provider in the bot’s **Edit** page, under **Provider**. Every provider, and what fxbot reads from it, is in [Providers](/docs/reference/providers/). # Add a skill > Give your bots a skill: instructions for a kind of task, which a bot reads only when a task calls for them. A skill is a plugin that carries one skill. It comes from fxbot's own picks or, with unvetted plugins on, from skills.sh, and installs from its GitHub repository. Give your bots a skill: instructions for a kind of task, which a bot reads only when a task calls for them. A skill is a plugin that carries one skill. It comes from fxbot’s own picks or, with unvetted plugins on, from [skills.sh](https://skills.sh), and installs from its GitHub repository. 1. Open **Plugins**, the puzzle button at the bottom of the sidebar, and choose **Browse**. fxbot’s picks are listed first, tagged **fxbot**: a skill says **Skill** beside its name. 2. To find another, turn on **Show unvetted plugins** in **Settings** › **Plugins**, then type in the search above the tabs. Results under **Skills** come from skills.sh, with how many times each was installed. 3. Choose a skill to open its page. fxbot reads its repository and shows its description, its files, the repository and commit it comes from, and its license. Choose **Read** to see its `SKILL.md`. 4. Choose the **Add** button, which names the skill. fxbot shows it under **Installed**, for all bots. 5. To give it to some bots only, open its tab in **Settings**, then **Choose** under **Bots**, and switch it on for each bot that should have it. Each bot sees a short list of its skills, and reads one when a task matches it. In the chat, that shows as **Read a skill**, with the skill’s name. ## Use a skill in a message [Section titled “Use a skill in a message”](#use-a-skill-in-a-message) To be sure a bot uses a skill, name it. In the chat, type `$`, or `/` at the start of the message, and pick the skill from the list; it shows as a chip above your message. Typing more narrows the list, and `$fd` finds `frontend-design`. You can also type `$show-me` yourself. The skill goes with the message, so the bot has it before it answers. ## When it goes differently [Section titled “When it goes differently”](#when-it-goes-differently) * **The page says it can’t be added.** The skill’s `SKILL.md` lacks a name or a description, or breaks the [Agent Skills](https://agentskills.io/specification) limits. The page says which. * **The page says it is only called by name.** Its author meant a person to start it, as `show-me` is. Bots don’t see it in their list: type `$show-me` in your message, or pick it after `$`. * **A file is passed over.** Images, links, and files over 256 KiB aren’t kept. Bots read only text. * **Its row says Update available.** The skill’s files changed in its repository. Open its tab in **Settings** and choose **Update to**: fxbot shows which files changed, and moves only when you choose **Update**. * **The search shows nothing from skills.sh.** Turn on unvetted plugins in Settings › Plugins, and type 2 characters or more. Each search then sends its words to skills.sh. Nothing in a skill runs: bots read its scripts as text. Why that matters: see [Security model](/docs/explanation/security/#skills). # Add an MCP server > Give your bots the tools of a remote MCP server: a plugin that carries one server. fxbot's picks are on Browse. With unvetted plugins on, so is GitHub's MCP registry, and adding a server by its address. Give your bots the tools of a remote MCP server: a plugin that carries one server. fxbot’s picks are on **Browse**. With unvetted plugins on, so is GitHub’s MCP registry, and adding a server by its address. ## From Browse [Section titled “From Browse”](#from-browse) 1. Open **Plugins**, the puzzle button at the bottom of the sidebar, and choose **Browse**. fxbot’s picks are listed first, tagged **fxbot**: a server says **MCP server** beside its name. 2. To find another, type in the search above the tabs. With unvetted plugins on, servers from fxbot’s copy of GitHub’s MCP registry show below fxbot’s picks. fxbot refreshes that copy every hour while it’s on. 3. Choose a result to open its page. fxbot looks at the server and shows where it runs, how it signs in, the keys it needs, and who published it. 4. For a server that needs a key, paste it into the field the page names. 5. Choose the **Add** button, which names the server. fxbot shows it under **Installed**. 6. For a server that signs in with OAuth, choose **Sign in** and approve fxbot on the page that opens. 7. Open its tab in **Settings**. Under **Bots**, keep **All bots**, or choose **Choose** and switch it on for each bot that should have it. 8. Under **Tools**, allow the ones bots may call. Only the read-only tools are allowed at first. ## By its address [Section titled “By its address”](#by-its-address) For a server the registry doesn’t list. Its docs give the address, often ending in `/mcp`. This needs unvetted plugins on. 1. On **Browse**, under **MCP servers**, choose **Add by address**. 2. Paste the address and choose **Look**. fxbot shows the server’s name, and either its tools, **Takes a key**, or **Signs in with OAuth**. 3. For a server that takes a key, paste it. It is sent as `Authorization: Bearer`; for another header, write it as `Name: value`. 4. Choose the **Add** button, then follow steps 6 to 8 above. A bot’s **Edit** page lists the servers too, in its **Plugins** section. A server that a plugin brought with it shows in that plugin’s settings instead, and follows its switch and its bots. ## When it goes differently [Section titled “When it goes differently”](#when-it-goes-differently) * **Browse shows only fxbot’s picks.** Turn on **Show unvetted plugins** in **Settings** › **Plugins**. fxbot doesn’t vet what that shows. * **The search doesn’t find it.** Tick **Search everything** to look in the official MCP registry as well. Nobody reviews its entries, so check who published one before you add it. * **The page warns that the server isn’t on the publisher’s domain.** The registry checks who published an entry, not where its server runs. Add it only if you trust that host. * **The page says it runs on this machine.** That server is a program, not a remote server, and fxbot can’t add it yet. * **The address is local or private.** fxbot refuses it unless you tick **Allow a local address**. Tick it only for a server you run: it can then reach this machine and your private network. * **The sign-in page doesn’t come back.** fxbot comes back to its own address when you use it at an HTTPS address, such as your tailnet’s. Elsewhere, the page the sign-in sends you to may not load: copy its address from the browser, and paste it into fxbot. * **The server signs in with OAuth, but you have a key.** When adding by address, choose **Use a key instead** before adding it. ## Update a server [Section titled “Update a server”](#update-a-server) A server added from the registry says **Update available** on its row when the registry has a newer version. Open its tab in **Settings** and choose **Update to**: fxbot shows what the new version changes, and moves to it only when you choose **Update**. A row may also say **Deprecated** or **Removed from the registry**; the server keeps working as added. Why only read-only tools to start: see [Security model](/docs/explanation/security/#mcp-servers). # Back up fxbot > fxbot backs itself up before a release's migrations run, into /var/lib/fxbot/backups, and keeps the last five. To keep a copy of your own, off the machine, back up with sudo fxbot backup, and keep the key apart. fxbot backs itself up before a release’s migrations run, into `/var/lib/fxbot/backups`, and keeps the last five. To keep a copy of your own, off the machine, back up three things: the database, which holds the chats, the data folder, and the key. These steps are for an install made by `setup.sh`. Keep the backup in a folder only you can read, since the database holds every chat. ## Back up [Section titled “Back up”](#back-up) ```sh sudo fxbot backup ~/fxbot-backup ``` It stops the app, so the database and the data folder match, writes the database as `database.dump`, in pg_dump’s custom format, and the data folder as `data.tar.gz` into the folder, and starts the app again. The folder is yours, as the user who ran `sudo`, and only you can read it. These are the names fxbot gives its own backups, so `fxbot restore` takes the folder as it is. With no folder, it writes into `/var/lib/fxbot/backups/-by-hand`. fxbot keeps only the five newest folders there, so copy one you want to keep somewhere else. Then copy the key, and store it apart from the backup: ```sh sudo install -m 400 -o "$USER" /etc/fxbot/secret.key ~/fxbot-secret.key ``` The database holds keys and tokens sealed with it, so they can’t be opened without it. Anyone with both can open them. ## Restore [Section titled “Restore”](#restore) On a new machine, first install the same release with `setup.sh`, then put the key back: ```sh sudo install -o fxbot -g fxbot -m 400 fxbot-secret.key /etc/fxbot/secret.key ``` Then restore the database and the data folder from the backup’s folder, and start fxbot on them: ```sh sudo fxbot restore ~/fxbot-backup sudo fxbot up ``` `fxbot restore` stops the app, makes the database again from `database.dump`, and unpacks `data.tar.gz` into `/var/lib/fxbot/data`. ## Move to a new machine [Section titled “Move to a new machine”](#move-to-a-new-machine) 1. **On the old machine,** back up, and take the key and the app’s settings along with it: ```sh sudo fxbot backup ~/fxbot-move sudo install -m 400 -o "$USER" /etc/fxbot/secret.key /etc/fxbot/fxbot.env ~/fxbot-move/ ``` If you wrote `/opt/fxbot/compose.override.yaml`, such as for web pairing’s ports, take it too. 2. **Stop the old one,** with `sudo fxbot down`, or [uninstall it](/docs/how-to/uninstall/). Devices paired at web.fxbot.sh find fxbot by its keys, which move with the backup, so two fxbots running on the same keys take them from each other. 3. **On the new machine,** install the same release with `setup.sh`. Give it the port the old one had, if you changed it, such as `curl -fsSL https://fxbot.sh/setup.sh | sudo FXBOT_PORT=8780 bash`. 4. **Put the key and the settings in place, then restore:** ```sh sudo install -o fxbot -g fxbot -m 400 ~/fxbot-move/secret.key /etc/fxbot/secret.key sudo cp ~/fxbot-move/fxbot.env /etc/fxbot/fxbot.env sudo fxbot restore ~/fxbot-move sudo fxbot up ``` Put `compose.override.yaml` back in `/opt/fxbot`, if you had one, before `fxbot up`. If the old machine ran the local embedder on a GPU, run `sudo fxbot embedder gpu` too. Bots, chats, the library, providers, and plugins come back as they were, and so do the devices paired at web.fxbot.sh, with nothing done on them. A tailnet gives the new machine a name of its own, so reach it there, or move the old name in Tailscale’s admin console. # Run a checkout beside a release install > Work on fxbot from a git checkout, as yourself, on a machine that also runs a release. The checkout uses its own database and embedder containers, key, and ports, so the two never touch: the release keeps the fxbot containers, /etc/fxbot, and port 8787. Work on fxbot from a git checkout, as yourself, on a machine that also runs a release. The checkout uses its own database and embedder containers, key, and ports, so the two never touch: the release keeps the `fxbot` containers, `/etc/fxbot`, and port 8787. You need Node 22.18 or newer, and podman or docker for the checkout’s database and embedder. A release install already has one of them. Backups before migrations use the machine’s `pg_dump`, which must be Postgres 17’s. 1. Clone the repository: ```sh git clone https://github.com/iammrduncan/fxbot.git && cd fxbot npm install ``` `main` holds releases only. To work on the next one, switch to its branch, `release/`. 2. Give yourself a key and a database password, once, and point the checkout at them: ```sh sudo install -d -o "$USER" -m 700 /etc/fxbot-dev openssl rand -base64 32 > /etc/fxbot-dev/secret.key && chmod 400 /etc/fxbot-dev/secret.key pw=$(openssl rand -hex 16) printf '%s\n' "FXBOT_DB_PASSWORD=$pw" "FXBOT_DATABASE_URL=postgres://fxbot:$pw@127.0.0.1:5433/fxbot_dev" FXBOT_EMBED_URL=http://127.0.0.1:8081/v1 FXBOT_SECRET_KEY_FILE=/etc/fxbot-dev/secret.key > .env ``` 3. Start the database, `fxbot_dev` on 127.0.0.1:5433, and the local embedder for memory search, on 127.0.0.1:8081, in a compose project of their own, `fxbot-dev`: ```sh podman compose -f deploy/compose.dev.yaml --env-file .env up -d # or docker compose ``` With podman as yourself, Compose reaches podman through your own socket. If it can’t connect, turn the socket on once with `systemctl --user enable --now podman.socket`. The embedder downloads its model, 310 MB, on its first start, and until it answers, memory search uses words alone. To put it on another port, set `FXBOT_EMBED_PORT` in `.env`, and the same port in `FXBOT_EMBED_URL`. 4. Start fxbot: ```sh npm run dev # the page on 127.0.0.1:5173 and the API on 8788, reloading on any change ``` 5. To reach it from your other devices, serve the page on your tailnet: ```sh tailscale serve --bg 5173 # https://..ts.net ``` If the release already has the machine’s address, serve one of them [at a name of its own](/docs/how-to/tailscale-service/), or on another HTTPS port with `--https=`. An app installed from the development address is the development page: every change shows up as it lands, but it can’t open while `npm run dev` is down. `npm run prod` and `npm run server` default to port 8787, so give them another with `FXBOT_PORT`. ## Take the checkout away [Section titled “Take the checkout away”](#take-the-checkout-away) The release stays as it is. In the checkout: ```sh podman compose -f deploy/compose.dev.yaml --env-file .env down --volumes # its database and the embedder's model sudo rm -rf /etc/fxbot-dev rm .env ``` If you set up the computer for the checkout, take it away too, with the script that set it up: ```sh sudo bash plugins/computer/host/setup.sh --user "$USER" --remove ``` It removes the release’s computer as well when they share the user `fxbot-computer`, so name the checkout’s own with `--name` if you gave it one. ## A checkout from before 0.3 [Section titled “A checkout from before 0.3”](#a-checkout-from-before-03) Before 0.3, a checkout’s `fxbot_dev` database was on the machine’s own Postgres. To move it into the container: 1. In `.env`, put the `FXBOT_DB_PASSWORD`, `FXBOT_DATABASE_URL`, and `FXBOT_EMBED_URL` lines from step 2 in place of the old `FXBOT_DATABASE_URL` and `PGHOST`. Keep `FXBOT_SECRET_KEY_FILE` and its key, which sealed the keys and tokens in that database. 2. Start the database and the embedder, as in step 3. 3. Copy the old database across: ```sh pg_dump --format=custom fxbot_dev > fxbot_dev.dump podman compose -f deploy/compose.dev.yaml --env-file .env exec -T db pg_restore -U fxbot -d fxbot_dev --no-owner < fxbot_dev.dump ``` The scripts, and the settings `.env` takes, are in [Commands](/docs/reference/commands/) and [Configuration](/docs/reference/configuration/). # Choose how hard a bot thinks > Set how hard a bot's model thinks before it answers, from the levels that model offers, and the level its subagents think at. A model that reasons thinks before it answers. **Thinking**, on a bot’s edit screen, sets how hard: the model’s own default, or one of the levels the model offers. A higher level is slower and costs more, and a lower one is quicker and cheaper. 1. Open the bot’s edit screen: **Edit** in the panel beside its chat. 2. Under **Model**, choose a level in **Thinking**: **Model’s default**, or one the model offers, such as **Low**, **Medium**, **High**, **Extra high**, or **Max**. **Off** turns thinking off, on a model that allows it. 3. Choose **Save**. The bot’s next message thinks at that level. A model that offers no levels shows no **Thinking**. A bot starts at **Model’s default**, which sends no level at all, so its chat behaves as before. ## Which levels [Section titled “Which levels”](#which-levels) Each model offers its own: GPT-5 offers Minimal to High, and Claude Opus 5.5 Low to Max, for example. fxbot reads them from where the bot’s provider lists them, and offers only those. The thinking each reply did shows in its steps, as **Thinking**, then **Thought**. ## When the model changes [Section titled “When the model changes”](#when-the-model-changes) A bot moved to another model keeps its level. If the new model doesn’t offer it, the bot runs at the nearest lower level the model does offer, never at **Off**, and **Thinking** says so, such as “Max: runs as High on this model”. With no lower level, the model’s own default runs. Your level stays saved, and comes back on a model that offers it. ## Which providers [Section titled “Which providers”](#which-providers) A bot’s level reaches its model through **AI Gateway**, **Vercel**, a **ChatGPT** sign-in, and a **Grok** sign-in now. Every other provider, by key or on your machine, takes it with a coming update of the agent fxbot runs on. Until then, **Thinking** shows for those providers’ models, says it takes effect with that update, and sends nothing. See [Providers](/docs/reference/providers/#thinking-levels). Changing the level in a long chat on Claude costs the chat’s prompt cache once, so choose one and keep it. ## For subagents [Section titled “For subagents”](#for-subagents) [Subagents](/docs/how-to/hand-work-to-subagents/) think at their bot’s level by default. To have them think harder, or more lightly, open **Settings** › **Subagents**, and set `thinking` to a level, such as `high`, or back to `same`. A level the bot’s model doesn’t offer runs as the nearest lower one. # Choose what a bot can do alone > Decide what each bot does by itself and what it asks you about first, with a mode for each bot, a card in its chat, and rules you build as you go. Decide what each bot does by itself and what it asks you about first, with a mode for each bot, a card in its chat, and rules you build as you go. 1. Add **permissions** from **Plugins**, on **Browse**, where fxbot’s picks list it. It needs fxbot 0.6.0 or newer. 2. Every bot starts on **Auto**. To change one, press the shield beside its message box, in the middle of a chat if you like, or open **Permissions** in its settings. ![A card in Rook's chat: Rook wants to use routines_add, with its input, Approve once, Always allow, and Deny](/shots/approval-desktop-light.png) ![A card in Rook's chat: Rook wants to use routines_add, with its input, Approve once, Always allow, and Deny](/shots/approval-desktop-dark.png) ## The three modes [Section titled “The three modes”](#the-three-modes) | Mode | What it does | | -------- | ------------------------------------------------------------------------------------------------------------------------- | | **Ask** | Asks you before anything but a safe tool | | **Auto** | Runs safe tools and everyday work. A reviewer model looks for what’s risky, and asks you about it unless you asked for it | | **Yolo** | Runs everything, with no checks. It’s what fxbot does without this plugin | A safe tool only reads, or writes the bot’s own notes: its memories, its library, its chat history, and its skills. Tools from MCP servers are never safe, whatever they say about themselves. ## Answer a card [Section titled “Answer a card”](#answer-a-card) When a call needs you, a card shows above the bot’s message box, with exactly what it wants to do. **Waiting on you** in the sidebar lists every open card, wherever you are in the app. In a room, the header shows how many are waiting. * **Approve once** runs this call. * **Always allow** runs it and saves a rule, so it won’t ask again. * **Deny** stops it, and you can say why. The bot won’t try the same thing again until you write to it, and three no’s in a turn make it stop and tell you. Writing to the bot instead of answering closes the card, and the bot reads what you wrote. ## Rules [Section titled “Rules”](#rules) **Always allow** saves a rule for that bot. Most rules are a whole tool. For the computer’s shell, terminal, and desktop, a rule is that exact action, down to the spaces, since allowing those tools outright would be the same as **Yolo**. A bot’s rules are under **Permissions** in its settings, each with **Remove**. ## Work you didn’t start [Section titled “Work you didn’t start”](#work-you-didnt-start) A card from a routine, a room, or another bot expires after 30 minutes, and the action doesn’t happen. The bot hears that no one answered, which isn’t a no. An expired card stays until you dismiss it, and can still save a rule for next time. A card from your own chat waits for as long as you take, and the bot waits with it. **Stop** ends it. ## Pick the reviewer [Section titled “Pick the reviewer”](#pick-the-reviewer) **Settings** › **Permissions** has the reviewer. It’s each bot’s own model at first, or you can pick a provider and model for every bot. A small, fast one is usually enough, and costs less. The reviewer sees what you wrote and the action. When a bot works on what you asked another bot, which passed it on, the reviewer sees what you asked, in your words, too. It allows everyday work, such as editing files, running builds and tests, installing packages, and starting services, whether or not you asked for that step. It asks you about what’s risky, unless you plainly asked for it: deleting what can’t be put back, changing something outside the bot’s own computer, such as a remote API, a deploy, or a push, touching secrets such as keys and passwords, weakening security, and spending money. It doesn’t see tool results, what other bots said, or the rest of the chat, so what fooled the bot can’t reach it, except through the action itself. ## What it can’t do [Section titled “What it can’t do”](#what-it-cant-do) * A reviewer misses things, and a page can be written to fool one. * **Auto** checks the action, not the outcome: a harmless-looking command can do harm. * A rule isn’t reviewed again once it’s saved. * Safe tools run with no check, so a bot talked into saving a bad memory isn’t stopped. * **Yolo** does what it says. ## What it costs [Section titled “What it costs”](#what-it-costs) In **Auto**, each new risky call is one model request of a few hundred tokens, and a few seconds’ wait. A busy computer session could be hundreds of them, so a cheaper reviewer and a few rules help. Safe calls, and calls a rule allows, add nothing. An open card holds that bot’s turn, which takes one of **Turns at once** in **Settings** › **General**. ## Set its limits [Section titled “Set its limits”](#set-its-limits) Open **Settings** › **Permissions**: | Setting | What it is | Default | | --------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | | `mode` | A bot’s mode until you set one: ask, auto, or yolo | `auto` | | `seconds` | The most seconds a review takes, 5 to 300 | 60 | | `expires` | The minutes a background card waits, 1 to 1,440 | 30 | | `trusted` | Plugins whose turn text counts as your words, such as a routine’s task | `routines` | | `exact` | Tools whose rules are the exact action | `computer_shell, computer_terminal, computer_desktop` | A bot can’t change these, its mode, or its rules. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **Every risky call shows a card that says the reviewer couldn’t check it.** The reviewer failed or timed out. Check its provider in **Settings** › **Permissions**, or raise `seconds`. * **A routine doesn’t get its work done.** Its risky calls are waiting on cards. Add a rule from a card, or use a bot on **Yolo** for that routine. * **A card asks about something you allowed.** On the computer’s tools, a rule is that exact action, so a different command asks again. # Cut a release > For maintainers. Work for the next release happens on release/, made from main after the last release. These steps release 0.2.0. For maintainers. Work for the next release happens on `release/`, made from `main` after the last release. These steps release `0.2.0`. 1. Check the branch: ```sh npm run typecheck && npm run build ``` 2. Set the version, in `package.json` and the lockfile: ```sh npm version 0.2.0 --no-git-tag-version ``` 3. In `CHANGELOG.md`, rename `## Unreleased` to `## 0.2.0 ()`. If the release adds migrations, bumps libfx, or needs a step by hand, open its section with **Before upgrading**. 4. Write the release’s notes in `docs/releases/0.2.0.md`, shaped like the last one’s. GitHub Releases and Settings show them, and they’re short enough to paste anywhere. Leave out **Before upgrading** when the changelog has none. Keep it above **Changes**, because Settings shows the notes in a small box above **Update**. ```md fxbot v0.2.0 is out! https://fxbot.sh/docs/reference/changelog/ Before upgrading: what an owner needs to know first. Changes: - New Plugin: Name => What it gives you - A line for each thing worth telling - Bug fix: what stopped going wrong ``` 5. Commit, merge into `main`, and push: ```sh git add docs/releases && git commit -am "Release 0.2.0" git switch main && git merge --ff-only release/0.2.0 && git push ``` 6. Start the next release’s branch: ```sh git switch -c release/0.3.0 && git push -u origin release/0.3.0 ``` The [release workflow](https://github.com/iammrduncan/fxbot/blob/main/.github/workflows/release.yml) then typechecks and builds `main`, checks that no shipped migration changed, builds fxbot’s image for amd64 and arm64, and pushes it to ghcr.io as `0.2.0`, `0.2`, and `latest`. Only then does it tag `v0.2.0` and publish a GitHub Release with `docs/releases/0.2.0.md` as the notes, so Settings never offers a release without an image. If a check or the image’s build fails, the changelog has no section for the version, or the notes are missing or open with another version, nothing is tagged or published. * **A prerelease,** such as `0.3.0-rc.1`, is the same steps with that version. It is published as a prerelease, and its image gets only its own tag, `0.3.0-rc.1`. * **A fix to a release** goes on `release/0.2.1`, made from `main`, and is merged into the open release branch after. * **An update to the site alone** goes to `main` with no new version. The workflow finds that version tagged and does nothing, and the site deploys, so installs see no change. Only do this while the branch holds nothing but the site and docs. How versions, tags, and migrations fit together is in [Releases and updates](/docs/explanation/releases/). ## Once, after the first release with an image [Section titled “Once, after the first release with an image”](#once-after-the-first-release-with-an-image) GitHub makes a new package private, and `setup.sh` pulls the image without a login. After the workflow has pushed the first image, open the `fxbot` package on GitHub, then **Package settings**, **Change visibility**, and **Public**. Check it from a machine that isn’t logged in to ghcr.io: ```sh podman pull ghcr.io/iammrduncan/fxbot: ``` # Draw diagrams in chat > With the mermaid plugin, the Mermaid code blocks your bots write draw as diagrams, in their replies, pages, and rooms, in the app's own colors and font. With the **mermaid** plugin, the ` ```mermaid ` code blocks your bots write draw as diagrams: flowcharts, sequence diagrams, state diagrams, timelines, charts, and the rest of [Mermaid](https://mermaid.js.org)’s types. 1. Add **mermaid** from **Plugins**, on **Browse**. It needs fxbot 0.9.0 or newer. 2. Ask a bot for something a picture explains: “draw how a refund goes through our support”, or “show the steps between the app, the server, and the bank when someone pays”. 3. The diagram draws in its reply, as the bot writes it. ![Pixel's chat: a flowchart of an order's journey, from Order placed through Paid? to the customer's door, drawn in the reply](/shots/diagram-desktop-light.png) ![Pixel's chat: a flowchart of an order's journey, from Order placed through Paid? to the customer's door, drawn in the reply](/shots/diagram-desktop-dark.png) Bots draw one by themselves when a picture explains it better than words, such as a process, the steps between people or systems, a structure, or a timeline. To have one, or to stop them, say so. ## Where they draw [Section titled “Where they draw”](#where-they-draw) In a bot’s replies, in [Markdown pages](/docs/how-to/keep-what-a-bot-writes/), in [rooms](/docs/how-to/talk-in-a-room/), and in a document’s preview in the library. A diagram takes the app’s colors and font, and follows light and dark with your system. On a phone, a wide one turns to run top to bottom. While a reply streams, the diagram grows as lines arrive. ## Use one [Section titled “Use one”](#use-one) The buttons at a diagram’s top right show on hover, and always on a phone: * **Show the code** switches to the diagram’s Mermaid source, and back. * **Copy the code** copies the source. * **Download as SVG** saves the diagram, in today’s colors, to open anywhere. * **Expand** opens it full screen, at its own size, to scroll around a big one. ## When one doesn’t draw [Section titled “When one doesn’t draw”](#when-one-doesnt-draw) A diagram with a mistake shows its code, and a line saying what’s wrong and where. Tell the bot, “the diagram didn’t draw”, and it fixes it. Bots check a diagram with the `mermaid_check` tool before they send it, which draws it as you’ll see it. A diagram that takes longer than 3 seconds to draw stops, and shows its code, and so does one over 50,000 characters. ## What a diagram can’t do [Section titled “What a diagram can’t do”](#what-a-diagram-cant-do) Diagrams in fxbot have no links, images, icons, or math, and a diagram can’t change its own colors or font: the app sets them. The plugin draws with [Pele](https://pele.run), Obsidian’s Mermaid renderer, which reads Mermaid’s syntax with a layout and look of its own, so a diagram can look a little different from Mermaid’s. # Fix an install that stopped > When setup.sh can't install fxbot, or the computer's setup can't make its engine, it stops and says why. Find the line it printed, and its fix. When `setup.sh` can’t install fxbot, it stops before it changes anything, and prints a line that starts with `fxbot setup stopped:`. The computer’s setup, which runs when you add the computer, stops the same way, and **Settings** › **Computer** shows its line. Find that line below, fix what it names, and run the same command again: both pick up where they stopped. ## On the wrong system [Section titled “On the wrong system”](#on-the-wrong-system) **`fxbot runs on Linux, and this is macOS`**, or Windows, or another system. fxbot installs on a Linux machine: a server, a small VPS, a computer at home, or a Linux VM. On Windows, WSL 2’s Ubuntu works, with systemd on (below). **`setup.sh installs through apt, dnf, zypper, or pacman`**. It runs on Debian, Ubuntu, Fedora, RHEL and its rebuilds, openSUSE, Arch, and the distros built on them. This system has none of those package managers. **`this system installs software as a whole image`**. Fedora Silverblue and CoreOS, and openSUSE MicroOS, change only as whole images, so `setup.sh` can’t add the packages fxbot needs. Use a distro that installs packages one at a time. **`fxbot needs systemd`**. fxbot starts at boot, and updates from **Settings**, through systemd. In WSL, turn it on: add these lines to `/etc/wsl.conf`, run `wsl --shutdown` in Windows, then open Ubuntu again. ```ini [boot] systemd=true ``` **`fxbot's images are for x86_64 and arm64`**. A 32-bit Raspberry Pi OS is `armv7l`. On a Raspberry Pi 4 or 5, install the 64-bit Raspberry Pi OS. ## Another program listens on the port [Section titled “Another program listens on the port”](#another-program-listens-on-the-port) **`another program listens on port 8787`**. fxbot listens on `127.0.0.1:8787`, and something else does already, such as RStudio Server. Install fxbot on another port: ```sh curl -fsSL https://fxbot.sh/setup.sh | sudo FXBOT_PORT=8780 bash ``` It keeps that port for good, in `/opt/fxbot/.env`. Use it wherever these docs say 8787, such as `sudo tailscale serve --bg 8780`. ## Docker from snap [Section titled “Docker from snap”](#docker-from-snap) **`Docker here is a snap, which can't reach fxbot's folders`**. Ubuntu offers Docker as a snap, whose daemon reaches only home folders. Remove it, then run `setup.sh` again, which installs an engine that works: ```sh sudo snap remove docker curl -fsSL https://fxbot.sh/setup.sh | sudo bash ``` Or keep the snap for other things, and give fxbot podman: run `setup.sh` with `FXBOT_ENGINE=podman` in place of the second line. ## Not enough room [Section titled “Not enough room”](#not-enough-room) **`fxbot's images need 3 GB free in /var/lib`**. Free some space where the engine keeps its images, `/var/lib`, then run `setup.sh` again. The computer’s image takes 1.2 GB more, later. ## A package that won’t install [Section titled “A package that won’t install”](#a-package-that-wont-install) **`installing … would remove …, so nothing was installed`**. apt would remove a package to install one of fxbot’s. `setup.sh` won’t do that unasked. Read what apt would do, with the package it named, and decide: ```sh sudo apt-get install --simulate podman ``` ## Old package lists on Arch [Section titled “Old package lists on Arch”](#old-package-lists-on-arch) **`pacman has no package lists`**, or **`pacman couldn't install …`**. `setup.sh` doesn’t update an Arch system itself, since that upgrades everything on it. Update it first, then run `setup.sh` again: ```sh sudo pacman -Syu ``` ## No engine to install [Section titled “No engine to install”](#no-engine-to-install) **`this system's packages have no podman 4.9 or newer, and Docker publishes no docker-ce for it`**. Install podman or Docker yourself, and `setup.sh` uses it. On Amazon Linux 2023: ```sh sudo dnf install docker sudo systemctl enable --now docker ``` **`Docker's signing key … isn't the one it should be`**. `setup.sh` checks the key of Docker’s repository before adding it. A key that doesn’t match comes from somewhere else: a proxy, or a mirror. Nothing was installed. Run it again where `download.docker.com` is reached directly. ## The computer [Section titled “The computer”](#the-computer) ### Ubuntu’s own Docker [Section titled “Ubuntu’s own Docker”](#ubuntus-own-docker) **`the computer needs podman 4.9 or newer, or a Docker that runs rootless`**, or **`dockerd-rootless.sh isn't installed`**. The computer runs on a second engine, rootless, for a user of its own. On Ubuntu 22.04, podman is too old for it, and Ubuntu’s own `docker.io` has no way to run rootless. Docker’s own `docker-ce` has one. Swap Ubuntu’s Docker for it, keeping fxbot and its database: ```sh sudo fxbot backup sudo fxbot down sudo apt-get remove docker.io docker-compose-v2 containerd runc curl -fsSL https://fxbot.sh/setup.sh | sudo bash ``` `apt-get remove` keeps `/var/lib/docker`, where fxbot’s database is, and takes Ubuntu’s Compose too, whose files Docker’s own would clash with, and `setup.sh` adds Docker’s repository and installs `docker-ce`, as [Docker’s own steps](https://docs.docker.com/engine/install/ubuntu/) do, then starts fxbot again. Then press **Try again** in **Settings** › **Computer**. On Ubuntu 24.04, the computer needs nothing of this: it runs on rootless podman, beside Ubuntu’s Docker. On Amazon Linux 2023, which has no podman and whose Docker can’t run rootless, the computer can’t run. ### An old podman [Section titled “An old podman”](#an-old-podman) **`the computer needs podman 4.9 or newer, and this machine has podman 4.3.1`**, as Debian 12 has. fxbot runs on that podman, and the computer needs a newer one, or Docker’s own `docker-ce`, which runs rootless. Move fxbot onto `docker-ce`, with its bots and chats: ```sh sudo fxbot uninstall curl -fsSL https://fxbot.sh/setup.sh | sudo FXBOT_ENGINE=docker bash sudo fxbot restore /var/lib/fxbot/backups/-uninstall sudo fxbot up ``` The uninstall keeps a backup and the key. `setup.sh` installs `docker-ce` from Docker’s repository, and the restore brings back what you had. A new install on Debian 12 gets `docker-ce` by itself. ### cgroups v1 [Section titled “cgroups v1”](#cgroups-v1) **`this machine runs cgroups v1, and the computers' limits need v2`**. Without cgroups v2, each computer’s limits on memory, CPU, and processes would do nothing. RHEL 8 and its rebuilds boot v1. Switch the kernel to v2, then restart: ```sh sudo grubby --update-kernel=ALL --args=systemd.unified_cgroup_hierarchy=1 ``` ### No user namespaces [Section titled “No user namespaces”](#no-user-namespaces) **`this machine keeps its users from making user namespaces`**. A rootless engine needs them. Arch’s `linux-hardened`, and some hardened setups, turn them off. Turn them on: ```sh echo 'kernel.unprivileged_userns_clone = 1' | sudo tee /etc/sysctl.d/90-fxbot-userns.conf sudo sysctl --system ``` On a system that sets `user.max_user_namespaces` to 0, set it to `28633` the same way. ## fxbot doesn’t answer after a start [Section titled “fxbot doesn’t answer after a start”](#fxbot-doesnt-answer-after-a-start) **`fxbot did not answer`**, and `sudo fxbot logs fxbot` shows `getaddrinfo EAI_AGAIN db`. The app can’t find its database by name. On podman, the containers ask the network’s own DNS server for names, and a firewall that denies incoming connections drops those asks: * **ufw:** `sudo fxbot up` lets port 53 in on podman’s network, marked `fxbot`. Run it again. * **firewalld:** `sudo fxbot up` turns on `netavark-firewalld-reload.service`, which puts podman’s rules back after each `firewall-cmd --reload`. Run it again. # Forward or map a port > Give your fxbot a UDP port that stays put on your router, so devices behind a symmetric NAT, as on many phone carriers, can reach it directly. Give your fxbot a UDP port that stays put on your router, so devices behind a symmetric NAT, as on many phone carriers, can reach it directly. It doesn’t help when your provider has a NAT of its own in front of your router: see [Carrier-grade NAT](/docs/how-to/when-a-device-cant-connect/#carrier-grade-nat). ## The ports [Section titled “The ports”](#the-ports) Web pairing uses UDP ports 8790 to 8799 for its connections, one or two each. Change the range under **Settings** › **Web pairing** › **Relay and ports**, from 2 to 100 ports. When every port in it is taken, a connection uses another, and the plugin’s log says so: a forwarded port doesn’t cover that one. ## Let fxbot map them [Section titled “Let fxbot map them”](#let-fxbot-map-them) With **Map the ports on the router, by NAT-PMP or UPnP** on, which is the default, fxbot asks the router for the range while it listens, renews it, and gives it back when it stops. **Relay and ports** says what it got: by NAT-PMP or UPnP, and at which public address. This needs NAT-PMP or UPnP on in the router’s settings. Many routers call it **UPnP** or **NAT-PMP**, under **Advanced** or **NAT**. Some have it off, since any program on the network can ask. If the router answers neither, the tab says so, and you can forward by hand. It can’t work from inside a container. See [From the release containers](#from-the-release-containers). ## Forward them by hand [Section titled “Forward them by hand”](#forward-them-by-hand) In the router’s settings, find **Port forwarding** (sometimes **Virtual servers** or **NAT rules**), and add one rule: | Field | Value | | ---------------- | ----------------------------------------------------------------- | | Protocol | UDP | | External ports | 8790–8799 | | Internal address | your fxbot machine’s address on the network, such as 192.168.1.20 | | Internal ports | 8790–8799 | Give the machine a fixed address on the network first, in the router’s DHCP settings, so the rule keeps pointing at it. ## From the release containers [Section titled “From the release containers”](#from-the-release-containers) An install made by `setup.sh` runs fxbot in a container, which needs the ports published as well. In `/opt/fxbot/compose.override.yaml`, add: ```yaml services: fxbot: ports: [ "8790-8799:8790-8799/udp" ] ``` The file is yours: nothing else writes over it. The computer keeps its own lines in `compose.computer.yaml`. On an install updated from 0.7.0 with the computer, its lines are still in `compose.override.yaml`, under `# Written by the computer plugin's setup.sh`: run `sudo fxbot computer on` once first, which moves them to their own file. Then run `sudo fxbot up`, which starts the app again with the ports published. With ufw active, let the range through to the container too, since ufw drops what the machine forwards: ```sh sudo ufw route allow proto udp to any port 8790:8799 ``` Then forward the same ports on the router, by hand: fxbot can’t find the router from inside its container. ## Check it [Section titled “Check it”](#check-it) **Settings** › **Web pairing** › **Reachability**, then **Check again**. A port mapped by fxbot shows as mapped. A port forwarded by hand can’t be seen from inside, so the best check is a phone on cellular, with Wi-Fi off. # Give a bot a routine > A routine is a task a bot runs on a schedule, such as a morning summary, with everything it has. It tells you in its chat, with what it saved, and stays quiet when there's nothing to say. A routine is a task a bot runs on a schedule, such as a morning summary, with everything it has. It tells you in its chat, with what it saved, and stays quiet when there’s nothing to say. 1. Add **routines** from **Plugins**, on **Browse**, where fxbot’s picks list it. It needs fxbot 0.6.0 or newer. 2. Check **Time zone** in **Settings** › **General**. The first browser to open fxbot set it, and every schedule uses it. 3. In the bot’s own chat, say what you want, in your own words: “every weekday at 8, summarize my calendar and unread mail”, or “tomorrow at 9, remind me to call the vet”. 4. The bot saves it, and the reply shows when it runs, with **Remove**, in case that isn’t what you meant. It’s on from then, and first runs at its next time. When it runs, the bot works in a session of its own, beside its chat, so you can go on talking to it. Then its result arrives in its chat, under the routine’s name, and you can reply to it there. For a task that matters only sometimes, say so: “every hour, check the price, and tell me only if it drops”. A run with nothing to say stays quiet. ![Pixel's chat: the owner asks for design reading every Monday, and the routine is added, with Remove](/shots/routine-desktop-light.png) ![Pixel's chat: the owner asks for design reading every Monday, and the routine is added, with Remove](/shots/routine-desktop-dark.png) ## What a run can do [Section titled “What a run can do”](#what-a-run-can-do) Everything the bot can do in its chat. It has its tools, its [computer](/docs/how-to/give-bots-a-computer/), the MCP servers you allowed it, its skills, its memories, and its library, and whatever else your plugins give it. What it saves to its library comes back with the result, and opens from the chat. Up to 5 files go with the message, and it names the rest, which stay in its library. No one is watching a run, so: * **The task is your say-so for what it names, and for nothing else.** If it says to send the report, the bot sends it. What you didn’t ask for, such as sending, buying, signing in, or deleting, it leaves undone, and says so. Write the task with that in mind. * **A step only you can do stops the run.** If a sign-in has lapsed, the bot says what it needs. On its computer, it hands you the desktop: take over, sign in, and choose **Hand back**, and it goes on in its chat. Until then, its desktop and terminal tools wait. * **A run and its chat share the bot’s computer.** Commands are fine side by side. Two turns on one desktop or browser can get in each other’s way, so time a routine that uses the desktop for when you aren’t using it. ## See and change routines [Section titled “See and change routines”](#see-and-change-routines) Open the bot’s settings. **Routines** lists each one, with when it runs next and its newest runs. Each has a switch, **Run now**, and **Remove**. While one runs, **Stop** ends it, and **Show** opens what a run said. To change a routine, ask the bot in its chat: “move the morning summary to 7”. Routines are made and changed only in the bot’s own chat, so a page it reads or another bot can’t add one. To see them all, ask it to list them. ## Set its limits [Section titled “Set its limits”](#set-its-limits) Open **Settings** › **Routines**: | Setting | What it is | Default | | -------------- | -------------------------------------------------------------------------------- | ------- | | `minutes` | The most minutes one run takes, up to 240. Raise it for long work on a computer. | 15 | | `calls` | The most tool calls one run makes | 100 | | `everyMinutes` | The fewest minutes between a routine’s runs, at least 5 | 15 | | `routines` | The most routines a bot can have | 20 | | `atOnce` | The most runs going at one time | 3 | | `failures` | Failures in a row before a routine pauses | 10 | | `keepRuns` | How many of a routine’s runs to keep | 20 | A bot can’t change these. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **It ran at the wrong time.** Check **Time zone** in **Settings** › **General**. * **A time was skipped.** When the clocks go forward, a time they skip doesn’t happen that day, so a routine at 02:30 can miss one day a year. A time that comes twice runs once. * **It says Missed.** fxbot wasn’t running at that time, and the run would have been too late to be worth making: more than half the time between its runs, from 2 minutes to 2 hours. A one-time routine still runs up to a day late. One a restart cut off doesn’t run again, since its tools may have done their work. * **It says Skipped.** The run before it was still going. * **It stopped by itself.** After 10 failures in a row it pauses, and the bot says so. You hear about the first failure too. The switch turns it on again. * **It’s cut off at the time limit.** Raise `minutes`. * **The bot can’t say when.** A routine runs on a five-field cron or once at a time, so “every other Tuesday” and “the last day of the month” don’t fit. The bot says so, and the reply shows what it saved. # Give a bot a soul > The soul plugin has each bot write a short brief of who it is, how it sounds, and how it helps you: in a first meeting when you make it, again when you ask, or brought over from Hermes Agent or OpenClaw. The soul plugin gives each bot a soul: a few lines, in its own words, of who it is, how it sounds, and how it helps you. It goes first in every chat of the bot. Your instructions still come first where the two differ, and the soul never changes what the bot may do. 1. Add **soul** from **Plugins**, on **Browse**, or with **Essentials**, which has it. It needs fxbot 0.10.0 or newer. 2. Make a bot, with **New bot** at the top of the sidebar, and open its chat. 3. The bot speaks first. From its name, it guesses who it might be, and asks whether that fits and what you’d like help with. 4. Answer it. It writes its soul, shows it to you, and offers to change it. ## The first meeting [Section titled “The first meeting”](#the-first-meeting) The meeting starts once, the first time you open a new bot’s chat. The chat shows “First meeting”, from Soul, then the bot’s greeting. It asks three questions at most. If you’d rather get straight to work, ask for what you need. The bot does it, and doesn’t bring the meeting up again. A bot you made before adding the plugin has no meeting: ask it to write its soul whenever you like. ## Change a soul [Section titled “Change a soul”](#change-a-soul) * **In the chat:** tell the bot, such as “From now on, be blunter with me.” It rewrites its soul, and says what changed. The chat shows **Updated its soul**, which opens to the new text. A request about one reply, such as “keep this one short”, changes that reply, not the soul. * **On its edit screen:** open the bot’s settings. **Soul** is under **Instructions**. Edit it there, and choose **Save soul**. Clearing it and saving leaves the bot with no soul. The bot changes its soul only in its own chat, with you. In a room, a routine, or a subagent’s work, it can’t. ## Go back to an earlier soul [Section titled “Go back to an earlier soul”](#go-back-to-an-earlier-soul) Under **Soul**, choose **History**. Each version shows who saved it, the bot or you, and when. **Restore** saves that one again, as the newest. A bot keeps its last 30 versions. ## Bring a bot from elsewhere [Section titled “Bring a bot from elsewhere”](#bring-a-bot-from-elsewhere) The plugin comes with a skill, `import-profile`, for bringing a bot over from another assistant. Tell the bot where you’re coming from, and send what it asks for: * **Hermes Agent:** the profile’s `SOUL.md`, `profile.yaml`, `memories/MEMORY.md`, `memories/USER.md`, and `config.yaml`. They’re in `~/.hermes`, or `~/.hermes/profiles//`, or inside the archive `hermes profile export` writes: open it, and send the files inside. * **OpenClaw:** the workspace’s `SOUL.md`, `IDENTITY.md`, `USER.md`, and `MEMORY.md`, usually in `~/.openclaw/workspace/`. * **Grok Bot, ChatGPT, or Claude:** the bot gives you a prompt to paste there. Paste its whole answer back. Never send `.env`, `auth.json`, or a credentials folder: they hold keys, and the bot doesn’t need them. Before it saves anything, the bot shows you the soul it would write and the memories it would keep, and what it left out. It keeps the imported words as they were. Your old assistant’s model, connections, and schedules aren’t brought over: the bot tells you where each goes in fxbot. ## Only some bots [Section titled “Only some bots”](#only-some-bots) The soul plugin is on for every bot once added. To give only some bots a soul, open **Settings** › **Soul**, and under **Bots** choose **Choose**, then switch it on for each one. A bot it’s off for keeps its soul, but doesn’t use it. # Give bots a computer > Each bot can have a Linux computer of its own, with a desktop you watch and take over, a terminal, a web browser, and files that last. The computer is a plugin. Each bot can have a Linux computer of its own: a Debian machine where it is root, with a desktop, a terminal, Chromium, and files that last. A bot runs commands there, browses, works in desktop apps, and saves what it makes to its library. You watch its desktop as it works, and take it over when it needs you. The computer is a plugin, and the engine it runs in is set up once on the machine. You need fxbot on a Linux machine with cgroups v2, as every distro `setup.sh` installs on has by default. The computer runs on podman 4.9 or newer where the distribution has it, beside whichever engine fxbot runs on, or else on the machine’s own Docker, run rootless, as on Debian 12 and Ubuntu 22.04 with Docker’s own `docker-ce`. 1. Open **Plugins**, choose **Browse**, and choose **computer**. Read what runs inside fxbot, then choose **Add computer**. Its latest needs fxbot 0.10.0 or newer. 2. The machine sets up the computer’s engine by itself, in a minute or two: podman, or the machine’s own Docker, run rootless for a user of its own, `fxbot-computer`, with a firewall that keeps its computers to the internet. fxbot starts again when it’s done. **Settings** › **Computer** shows it working, then names the engine, such as `podman 5.4.2, rootless`. 3. The computer is on for every bot once added. To give it to some bots only, open **Settings** › **Computer**, and under **Bots** choose **Choose**, then switch it on for each bot that should have one. 4. Ask a bot to do something on its computer, such as “make a chart of these numbers with Python and save it to the library”, or “find the opening hours on the library’s site”. To point it at the computer, choose the screen button beside the message box, which adds `$computer` to the message. A bot’s first call makes the image its computers share, which takes a minute or two. After that a computer and its desktop start in about a second, and stop after 15 minutes without a call. Its home, `/root`, is kept, with the browser’s sign-ins; programs a bot installs last until the computer is made again from a new image. ## Watch and take over [Section titled “Watch and take over”](#watch-and-take-over) Open a bot’s computer from the dot on its screen button, which shows while the computer runs, or with **Open computer** in the bot’s settings or in **Settings**. Its screen has two tabs: * **Desktop** shows the computer’s screen as the bot works, with Chromium, a file manager, and a terminal window. It’s for watching: a click there does nothing. * **Terminal** is the same terminal as the window on the desktop, the one the bot types in with `computer_terminal`. What you type there reaches it too. To use the desktop yourself, choose **Take over**. The mouse and keyboard are yours, and the bot’s desktop and terminal tools wait; its shell and file tools go on. Choose **Hand back** when you’re done. Closing the screen hands it back too. A computer someone watches doesn’t stop while it’s open. When a bot needs you for something only you can do, such as a sign-in, a passkey, or a CAPTCHA, it asks: the dot turns orange, and the computer’s screen says what it needs. Do it, then choose **Hand back**. The bot hears, looks at the screen, and carries on. ## Give a room a computer [Section titled “Give a room a computer”](#give-a-room-a-computer) With [chat rooms](/docs/how-to/talk-in-a-room/) added too, a room can have a computer of its own, which its bots share. It’s part of the computer since its 0.5.0, so there’s nothing more to add. Before that, it was the chat-rooms-computer plugin: update the computer first, then remove chat-rooms-computer, and each room keeps its computer. 1. In a room, choose the screen button at the top, beside **Edit**, and turn on **Computer**. 2. The room’s bots now use the room’s computer in the room, taking turns, as they take turns talking, and their own computers in their own chats. Its hostname is the room’s name and `-computer`. 3. **Open** shows it, with an arrow where each bot last pointed. A skill, `room-computer`, teaches the bots to look before they act, to keep a browser tab of their own, and to say in the room what they did. Turning it off stops it and keeps its files, for the next time it’s on. Deleting the room deletes its computer. When a bot asks you for help on it, take over, do it, hand it back, and tag the bot in the room to go on. ## The browser [Section titled “The browser”](#the-browser) Chromium is on each computer’s desktop. Bots drive it with [agent-browser](https://github.com/vercel-labs/agent-browser), and you see each page they open. It starts the first time a bot uses it. ## Look after the computers [Section titled “Look after the computers”](#look-after-the-computers) * **Settings** › **Computer** lists each bot’s computer, running or stopped, with its home’s size. **Rebuild image** makes the image again from a new copy of Debian. **Delete all computers** deletes every computer and its home. * A bot’s settings, under **Computer**, have **Stop**, and **Reset**, which deletes that bot’s computer and its home. * Removing the plugin keeps the computers, their homes, and the engine. Delete the computers first, or, after removing it, run `sudo fxbot computer off`, which also removes the user, its firewall, and the engine’s socket. In a checkout, run the setup script with `--remove`. ## When it goes differently [Section titled “When it goes differently”](#when-it-goes-differently) * **The setup failed.** Settings shows why, with **Try again**. [Fix an install that stopped](/docs/how-to/fix-an-install/#the-computer) has each reason and its fix, such as Ubuntu 22.04’s `docker.io`, which can’t run rootless, or a podman older than 4.9. On Ubuntu 24.04 it stops when no AppArmor profile lets the engine make user namespaces; install the engine from Ubuntu’s or Docker’s packages, which carry one. * **The section shows a command.** fxbot runs from a checkout as a user other than root, so nothing it runs can set up the engine. Run the command on the machine, as root. Choose **Read the script** to see what it does first. * **It says the engine runs as root.** The `engine` setting points at a root engine’s socket, which the computer won’t use. Clear the setting. * **The image doesn’t build.** The section shows the step that failed and its last lines, and the old image stays in use. A plugin’s setup step may need the network: the computer’s engine reaches the internet. * **A bot can’t reach something on your network.** That’s the firewall: a computer reaches the internet only. See [The computer](/docs/reference/computer/) for what it refuses, and how to let one address through. * **The desktop stays on Connecting….** The computer is starting, or its desktop stopped. Choose **Connect again**. If the screen says the computer is stopped, choose **Start it**. * **Chinese, Japanese, or Korean text, or emoji, shows boxes.** The image has no fonts for them. A plugin that needs the computer can add them with a setup step, such as `apt-get install -y fonts-noto-cjk fonts-noto-color-emoji`. For the tools, the skills, the settings, and what a computer reaches, see [The computer](/docs/reference/computer/). # Go back to an earlier release > Each release is an image, and /opt/fxbot/.env names the one that runs, in FXBOT_VERSION. Going back means naming the older version and starting it. These steps use 0.3.0; use the version you are going back to. Each release is an image, and `/opt/fxbot/.env` names the one that runs, in `FXBOT_VERSION`. Going back means naming the older version and starting it. These steps use `0.3.0`; use the version you are going back to. An update that doesn’t start goes back by itself. These steps are for a release that started, which you want to leave. ## With no migration in between [Section titled “With no migration in between”](#with-no-migration-in-between) The changelog says whether a release added migrations, under **Before upgrading**. If none did: ```sh sudo sed -i 's/^FXBOT_VERSION=.*/FXBOT_VERSION=0.3.0/' /opt/fxbot/.env && sudo fxbot up ``` ## After a migration [Section titled “After a migration”](#after-a-migration) The older release refuses a database that a newer one migrated. Restore the backup taken before the migration, then switch. 1. Find the backup. Each is a folder in `/var/lib/fxbot/backups`, named for when it was taken and the first migration it came before: ```sh sudo ls /var/lib/fxbot/backups ``` 2. Restore the database and the data folder from that folder, then name the older version and start it: ```sh sudo fxbot restore /var/lib/fxbot/backups/-before- sudo sed -i 's/^FXBOT_VERSION=.*/FXBOT_VERSION=0.3.0/' /opt/fxbot/.env && sudo fxbot up ``` `fxbot restore` stops the app first, puts the backup in place of the database, and unpacks its data folder. Going back from 0.4.0 or later to 0.3, restore the backup named `-before-0006_plugins`. The update to 0.4.0 took it before its migrations and before it moved the chats into the database, so it holds their old files. Anything said or saved after the backup is lost with the restore. Why the database only moves forward: see [Releases and updates](/docs/explanation/releases/#migrations). # Hand work to subagents > A bot can start subagents, helpers that work in the background on one task each while it carries on, and hear back from them together. Its panel lists them, and each opens to its thread. A bot can start subagents: helpers that work in the background on one task each, while it carries on talking with you. Each subagent is the bot itself, run again in a session of its own, with its tools, computer, skills, and memories, but not its chat. 1. Add **subagents** from **Plugins**, on **Browse**, or with **Essentials**, which has it. It needs fxbot 0.10.0 or newer. 2. Ask a bot for something that takes a lot of digging: “compare the three hosting offers, and check what each says about backups”. The bot hands it to subagents, one for each part, tells you what it started and that it’ll come back with the results, and you can carry on talking with it. 3. When the last of them has ended, their reports reach the bot together, in one message from **Subagents**, and the bot tells you what they found. Each subagent has a name of its own, a scientist’s, such as Curie or Ramanujan, that none in the bot’s list has, and a color of its own too. A subagent hasn’t seen your chat, so the bot puts everything it needs in its task. With the plugin on, a bot hands work that takes a lot of digging to subagents by itself. To have it start one only when it decides to, set `handOff` to `off`. ## They talk with the bot [Section titled “They talk with the bot”](#they-talk-with-the-bot) A subagent can’t ask you anything, but it can tell the bot’s chat what can’t wait for its report: a question only the chat can answer, or a finding to act on now. It shows in the chat as a message from the subagent’s name, joins what the bot is doing, or wakes it, and the subagent carries on. A subagent does this at most five times. The bot answers, or changes a subagent’s task, by messaging it by name: the message reaches the subagent at its next step, while it works. You can ask the bot to do it: “tell Curie to look only at EU regions”. ## Watch them work [Section titled “Watch them work”](#watch-them-work) ![Atlas's chat: three subagents started, Curie, Hopper, and Turing, each at work, and the bot's panel listing them under Subagents, 3 working](/shots/subagents-desktop-light.png) ![Atlas's chat: three subagents started, Curie, Hopper, and Turing, each at work, and the bot's panel listing them under Subagents, 3 working](/shots/subagents-desktop-dark.png) The bot’s panel, on the right of its chat, lists its subagents under **Subagents**, each with its name in a color of its own and what it’s working on: the ones working, with the tool each is in and how many calls it has made, and those that ended in the last day. Past the three newest that ended, the rest fold under **N earlier**. On a phone, the panel opens from the button at the top right of the chat. Click one to open its thread: its task, each step it takes, and what it found, as it works. When it ends, the thread says how long it took, its calls and tokens, and that it reported to the bot. The back button returns to the chat. In the chat, the bot’s call that started one shows as a card, such as **Started Curie**, with how it’s going and **Open**. ## Stop one [Section titled “Stop one”](#stop-one) **Stop** is on a working subagent’s row, and on its thread. The bot hears that you stopped it, with the others’ reports. You can also ask the bot to stop one. **Stop** in the bot’s chat stops what the bot is doing there, not its subagents: they’re background work. ## What a subagent can do [Section titled “What a subagent can do”](#what-a-subagent-can-do) All the bot can do, but for what its chat decides. A subagent can’t: * start a subagent of its own * save or forget memories, message your other bots, or make routines * ask you anything, or hand you the computer, though it can tell the bot’s chat It says in its report what it would do, and the bot decides, in its chat with you. With [Permissions](/docs/how-to/choose-what-a-bot-can-do-alone/), a subagent’s call that needs your OK waits at a card in the bot’s chat, as other background work does. Subagents start only in a bot’s own chat with you, not in a room or a routine’s run. ## On the computer [Section titled “On the computer”](#on-the-computer) A bot’s subagents share its [computer](/docs/how-to/give-bots-a-computer/), and work on it together as a room’s bots do: * **Each has its name and arrow** on the computer’s screen, such as “Ann · Curie”, and each is told what the others did last. * **Each has its own browser tab,** with the bot’s sign-ins, so they can browse at once. * **They take turns at the desktop and the terminal.** One that finds another using either waits for its turn, up to a minute, then works in the shell or its browser tab meanwhile. * **Each is told to keep its files** in a folder of its own, `~/subagents/s/`. ## What it costs [Section titled “What it costs”](#what-it-costs) A subagent’s requests carry the bot’s instructions and tools, and its task, but not the chat, so each is smaller than the chat’s. Its whole run counts toward your provider’s usage, as the bot’s own turns do. Passing their reports on is one more turn of the bot, with its whole chat as context, once for each batch. ## Set its limits [Section titled “Set its limits”](#set-its-limits) Open **Settings** › **Subagents**: | Setting | What it is | Default | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | `atOnce` | The most subagents a bot has working at one time, up to 10 | 4 | | `perAsk` | The most subagents one request from you leads to, up to 50 | 10 | | `minutes` | The most minutes one subagent works, up to 240 | 60 | | `calls` | The most tool calls one subagent makes, up to 1,000 | 100 | | `keepDays` | How many days an ended subagent is kept, up to 90 | 30 | | `handOff` | `on`: the bot hands work that takes a lot of digging to subagents, and tells you it’ll come back with the results. `off`: it starts one only when it decides to | `on` | | `thinking` | How hard subagents think: `same`, the bot’s own [level](/docs/how-to/choose-how-hard-a-bot-thinks/), or a level such as `low`, `medium`, `high`, `xhigh`, or `max` | `same` | | `blocked` | Tools a subagent can’t call | its chat’s: memories, messages, routines, and asking you for the computer | `perAsk` counts the subagents your message started, and those the bot starts from their reports. A bot can’t change these. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The bot says it can’t start one.** It has as many working as `atOnce`, or your request has led to `perAsk` already. Wait for their reports, or raise the setting. * **A subagent stopped, “cut off when fxbot or this plugin restarted”.** A restart, or an update of the plugin, stops the subagents working then. They aren’t run again, since their tools may have done half the work. The bot hears it, and can start one again. * **It failed at the time limit.** Raise `minutes`, or ask for smaller parts. * **A subagent waited for the desktop.** Another of the bot’s subagents was using it. It gets its turn when the other’s turn ends, or a minute passes. # Keep what a bot writes > A page is something a bot writes for you to read and keep, outside the chat, such as a report, a guide, or a plan. The library keeps it, with every version. A page is something a bot writes for you to read and keep, outside the chat, such as a report, a guide, or a plan. The library keeps it, with every version. 1. Add **pages** from **Plugins**, on **Browse**, where fxbot’s picks list it. **Essentials** has it too. It needs fxbot 0.7.0 or newer. 2. Ask a bot for something to keep, in your own words: “write up our trip plan as a page”, or “make a report on last week’s sales”. 3. The bot writes it, and says in a sentence what it covers. A card in the chat has the page’s title and **Open**. A bot also writes a page without being asked when its answer would be long, such as a report, a comparison, research findings, or a plan. What a few sentences answer stays in the chat. To have an answer in the chat instead, say so: “just tell me here”. ![A page called A slow weekend in Lisbon, with two boxes ticked](/shots/page-desktop-light.png) ![A page called A slow weekend in Lisbon, with two boxes ticked](/shots/page-desktop-dark.png) ## Read it [Section titled “Read it”](#read-it) **Open** fills the screen with the page, at an address of its own, on a phone too. It can have headings, tables, code, and images from the library. * **Copy** copies its Markdown. * **Print** prints it, or saves it as a PDF, which is how a page goes to someone who can’t reach your fxbot. * **Delete** removes it from the library, for every bot, with its versions. ## Change it [Section titled “Change it”](#change-it) Ask the bot, in its chat: “move day two to the coast”. It changes the same page, and a new card shows the new version. An older card says **Updated since**, and opens the newest. Each request makes one version. To go back, pick an earlier one on the page, and choose **Restore**. That makes it the newest, so nothing is lost. ## Tick things off [Section titled “Tick things off”](#tick-things-off) Ask for a checklist: “make me a packing list as a page”. Each item has a box, and what you tick stays. The bot sees it too, so you can ask “what’s left?”, and if it rewrites the page, it keeps your ticks. An older version shows the ticks it had, and **Restore** brings them back. ## Find it later [Section titled “Find it later”](#find-it-later) A page is in the library, under **Documents**, and on the bot’s panel beside its chat. **Open page**, in its preview, opens it. Ask the bot for it too: it finds its pages by what’s in them. ## Charts and controls [Section titled “Charts and controls”](#charts-and-controls) When a page needs more than text, such as a chart with filters, ask for that, and the bot writes the page in HTML. It costs more to write, and any change rewrites it. * It stands alone, in a frame of its own, so the bot draws its charts itself. * A link shows its whole address above the page, and opens when you say so. * If the bot is set to **Ask** in [what it can do alone](/docs/how-to/choose-what-a-bot-can-do-alone/), it waits for your OK first, since a page’s code runs when you open it. * A page can save what you do on it, such as a note or a filter, if the bot built it to. To change the page itself, ask the bot. * A button on a page can draft a message to the bot. You read it, and choose **Send**. * If a page hits an error, a line below it says so, and **Tell the bot** drafts a message about it. * **Open in a tab** opens it alone, to print. ![An HTML page Ledger wrote: this month's spending, as bars by category](/shots/chart-desktop-light.png) ![An HTML page Ledger wrote: this month's spending, as bars by category](/shots/chart-desktop-dark.png) ## Keep its numbers current [Section titled “Keep its numbers current”](#keep-its-numbers-current) A bot can send an HTML page new numbers without rewriting it, which costs a fraction of a rewrite. Ask for a dashboard, then a routine: “every morning, update the sales page’s numbers”. The first time, a bar on the page says the bot wants to give it data. A page with code can send what it holds elsewhere, so only choose **Allow** for a page you’re happy to trust with that data. What was waiting then arrives. If the bot rewrites the page, it asks again. An open page shows new numbers when you come back to it. ## From a routine or a room [Section titled “From a routine or a room”](#from-a-routine-or-a-room) * **A [routine](/docs/how-to/give-a-bot-a-routine/)** can write a page, such as a weekly report, and its result arrives in the bot’s chat with the page attached. An HTML page on **Ask** waits for your OK, and the routine’s request expires after 30 minutes. * **In a [room](/docs/how-to/talk-in-a-room/),** there’s no card, so the bot links the page in what it says. ## Remove it [Section titled “Remove it”](#remove-it) **Remove**, on the plugin’s tab in **Settings**, leaves each page in the library as a document, at its newest version. Its older versions go. # Let bots dream > The dreams plugin has each bot go over its day at night: it saves what's worth remembering and writes down ways of working as skills, and a journal in the bot's settings shows each change, with Undo. The dreams plugin gives each bot a pass over its day at night. The bot saves what will matter in later chats as memories, citing the turns they came from, and when the day showed a way of doing a kind of task that worked, it writes it down as a skill. Each change is in a journal in the bot’s settings, where **Undo** takes it back. 1. Add **dreams** from **Plugins**, on **Browse**, where fxbot’s picks list it. It needs fxbot 0.6.0 or newer. 2. Open **Settings** › **Dreams**, and set when bots dream: `hour`, 3 by default. It’s in the time zone in **Settings** › **General**, which the first browser to open fxbot set. 3. Chat as usual. A bot dreams at that hour once it has 6 turns since its last dream, which `minTurns` changes. To see a dream now, open a bot’s settings, then **Dream now** under **Dreams**. It reads the turns since the last dream, and takes as long as a long reply. ## Read the journal [Section titled “Read the journal”](#read-the-journal) **Dreams**, in each bot’s settings, shows each night: how many turns it read, and its last line, such as “Saved two memories.” Under it is each change: * **Saved a memory**, **Changed a memory**, or **Merged a memory**, with the old text * **Made a skill** or **Rewrote a skill**, with **Show** * the turns it came from, with your words in them **Undo** puts the memory or the skill back as it was. If you changed that memory since, Undo leaves it and says so: edit or delete it in **Memories**. **Skills from dreams** lists the bot’s skills, with **Remove**. Each bot keeps its own: one bot’s skills from dreams aren’t another’s. ## What a dream changes [Section titled “What a dream changes”](#what-a-dream-changes) * **Memories:** up to 10 changes a night. It changes only the bot’s own memories, never the ones you wrote, and never forgets one. You remove memories in **Memories**. * **Skills:** one change a night, and 20 skills a bot. Set `skills` to `off` for memories only. * **The day is evidence, not instructions.** A dream doesn’t follow requests quoted in what it read, saves only what a turn shows, and leaves out secrets and what mattered only that day. A dream runs on the bot’s own model and provider. A night costs one turn of it for each bot that dreams, with up to 96 KB of the day. The plugin’s [README](https://github.com/iammrduncan/fxbot/tree/main/plugins/dreams) has the rules it gives the model. ## Only some bots [Section titled “Only some bots”](#only-some-bots) Dreams is on for every bot once added. To have only some bots dream, open **Settings** › **Dreams**, and under **Bots** choose **Choose**, then switch it on for each bot that should dream. A bot it’s off for has no turns kept, and doesn’t dream. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) * **A night says “Failed”.** The bot’s provider didn’t answer. The turns wait for the next night. * **A night says it was stopped.** It ran past `minutes`, 10 by default, or fxbot restarted during it. The turns wait for the next night. * **No dream at the hour.** A bot needs `minTurns` turns since its last dream, and dreams within 4 hours of `hour`. A bot busy in a chat dreams a few minutes later. # Let bots work together > Your bots can message each other in their own chats, so one can ask another for what it knows, or hand it a job, and you can watch the work happen. Your bots can message each other in their own chats, so one can ask another for what it knows, or hand it a job, and you can watch the work happen. 1. Add **messages** from **Plugins**, on **Browse**, where fxbot’s picks list it. It needs fxbot 0.6.0 or newer, and at least two bots. 2. Optional: in each bot’s settings, under **Messages**, say in a line what it does, such as “Runs the deploys”. The others see that line, which helps them pick the right bot. 3. Ask a bot for something another one knows or does: “ask Philly what broke staging”. The bot sends a message, which shows in its chat as a small pill, **1 sent · Philly**. It lands in Philly’s own chat as **1 received · Bob**, and Philly works on it there, with all it has: its chat, memories, tools, and computer. You can open either chat at any point, and write in it. ![Sprout's chat: a pill for the message it sent Atlas, then one for Atlas's answer, and Sprout's reply](/shots/together-desktop-light.png) ![Sprout's chat: a pill for the message it sent Atlas, then one for Atlas's answer, and Sprout's reply](/shots/together-desktop-dark.png) ## Read a bot’s chat [Section titled “Read a bot’s chat”](#read-a-bots-chat) Messages between bots don’t fill the chat. Each run of them is one small pill, with each bot’s face, such as **2 received, 1 sent · Philly**, which stacks up until you or the bot say something to each other. Click it to read them, with what the bot did and answered. A message that couldn’t be sent stays in view, with why. When a message expects a reply, that work and that answer go in the pill, since they’re for the other bot. What a bot says to you always stays in view, such as what it made of an answer it got. If you write while a bot is on a folded message, the rest of that turn shows, so what you said never disappears. ## Tag a bot [Section titled “Tag a bot”](#tag-a-bot) In a bot’s chat, type `@` to list the bots it can reach, and pick one. It goes in your message as a chip with its face. The bot then knows exactly which one you mean, which matters when two have the same name: each shows the line from its settings, to tell them apart. A tag doesn’t wake the bot you tag. The bot you’re talking to sends the message: “ask @Philly what broke staging”. A name you type out without picking it stays plain text. ## How a conversation goes [Section titled “How a conversation goes”](#how-a-conversation-goes) A message wakes a bot that’s idle, and joins what a working bot is doing. Either way the bot is told who it’s from, and that a bot’s words aren’t yours. A message expects a reply. The bot can say “got it, on it” first and carry on working. When its turn ends, its last message goes to whoever asked, unless it has just sent them its answer. If it had nothing to say, or it failed, they’re told so. A bot can also send a message that needs no reply, such as “got it” or a finished result. A no-reply message can’t be answered from the turn it wakes, so two bots can’t thank each other forever. Each conversation can go through as many bots as the work needs, up to its budget of 20 messages. Then the bot that was refused tells you where things stand, and your next message starts a new conversation. ## Watch and stop [Section titled “Watch and stop”](#watch-and-stop) **Open conversations**, in **Settings** › **Messages**, shows each conversation as one thread, with how far through its budget it is and how each message went. A row opens that bot’s chat. * **Stop** on a conversation ends the turns its messages started, and refuses any more sends in it. A turn that a message only joined goes on. * **Stop** in a bot’s chat ends what that bot is doing, whatever started it. If a message started it, the bot that asked hears that you stopped it. ## Rooms or messages [Section titled “Rooms or messages”](#rooms-or-messages) Use a [room](/docs/how-to/talk-in-a-room/) when you want to talk with several bots in one place, and see all they say side by side. Use messages when one bot should get on with something and fetch what it needs from another, in the background, in their own chats. ## What it costs [Section titled “What it costs”](#what-it-costs) A message to an idle bot is one turn of that bot, with its whole chat as context, where your provider counts usage. So a conversation of 20 messages can be 20 turns at the full size of each bot’s chat, and this is the cost to watch. A message to a bot that’s working costs no new turn: it joins the turn running. ## Who can ask whom [Section titled “Who can ask whom”](#who-can-ask-whom) Any bot the plugin is on for can message any other it’s on for, and ask it to act. The one that gets the message has all its tools. It’s told that a bot’s words are a colleague’s request, and that what it would ask you about first, another bot can’t OK. When your message started the work, it also gets your own words, quoted by fxbot from the chat where you said them. So it knows the request is yours, and can tell when a bot asks for more than you did, and so does each bot after it. To keep a bot out of this, turn the plugin off for it in **Settings** › **Messages**. To have a bot ask you before it acts on a colleague’s word, see [Choose what a bot can do alone](/docs/how-to/choose-what-a-bot-can-do-alone/). ## Set its limits [Section titled “Set its limits”](#set-its-limits) Open **Settings** › **Messages**: | Setting | What it is | Default | | -------------- | ---------------------------------------------------------- | ------- | | `conversation` | The most messages in one conversation, up to 100 | 20 | | `perTurn` | The most messages one turn sends, up to 20 | 5 | | `perHour` | The most messages between two bots in an hour, up to 1,000 | 60 | | `minutes` | The most minutes a bot works on one message, up to 240 | 15 | | `calls` | The most tool calls in one message’s turn, up to 1,000 | 100 | A bot can’t change these. `minutes` and `calls` are for turns a message started: a turn a message only joined keeps whatever limits it had. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **A bot says it can’t reach another.** The plugin is off for that bot, or the bot has no provider. * **A message says Waiting.** The bot is finishing a turn that takes no messages, such as passing on a routine’s result, or the message has a picture, which waits for the turn to end so the bot’s work isn’t lost. * **Two bots have one name.** A bot has to use an id to reach either of them. Rename one. * **It’s cut off at the time limit.** Raise `minutes`. * **A file didn’t arrive.** A message takes up to 5 files from the sender’s library, with text under 100 KB and pictures within a message’s limits. The rest are named in the message, and stay in the sender’s library. # Choose where memory search's vectors come from > Bots find their memories and earlier chats by words, and by meaning with vectors from an embedding model. By default, the vectors come from a local embedder on the machine's CPU. You can move it to an NVIDIA GPU, use a provider's embedding model instead, or turn vectors off. How search uses them: see Search by words and by meaning. Bots find their memories and earlier chats by words, and by meaning with vectors from an embedding model. By default, the vectors come from a local embedder on the machine’s CPU. You can move it to an NVIDIA GPU, use a provider’s embedding model instead, or turn vectors off. How search uses them: see [Search by words and by meaning](/docs/explanation/bots-and-chats/#search-by-words-and-by-meaning). | Choice | What it uses | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Local, on the CPU** | The default. The machine’s `embed` container: llama.cpp’s server with EmbeddingGemma 2. It downloads the model, 310 MB, on its first start, holds about 380 MB of memory, and gives way to everything else that needs the CPU. | | **Local, on a GPU** | The same container on an NVIDIA GPU, with Qwen3-Embedding-0.6B. See [On a GPU](#on-a-gpu). | | **A provider’s embedding model** | A provider in Settings that serves embeddings. See [From a provider](#from-a-provider). | | **Off: words only** | No vectors. Search uses words alone. | The local choices need an install made by `setup.sh`, which runs `embed` as one of its containers. **Off** and a provider leave `embed` out, so it uses nothing. A checkout’s local embedder is the one `deploy/compose.dev.yaml` runs, on the CPU, and Settings can’t move it. ![Settings, on the Memory tab: team memories, then memory search](/shots/memory-desktop-light.png) ![Settings, on the Memory tab: team memories, then memory search](/shots/memory-desktop-dark.png) ## Pick one [Section titled “Pick one”](#pick-one) 1. Open **Settings**, then **Memory**. 2. Under **Where vectors come from**, pick one of the choices. A local choice, or **Off**, asks the machine to start, move, or stop `embed`. While it does, the line below says so, such as **Switching the local embedder to the GPU…**. 3. Read the line below the choices. Once vectors are on, it names the model and how far they have got: ```plaintext On: embeddinggemma-2 on the CPU. 12 of 40 memories and 1,204 of 5,690 messages have vectors. ``` With **Off**, it says **Off: memories and earlier chats are searched by words.** When something failed, it shows the last error. The counts rise while fxbot fills in the missing vectors, memories first, then messages, newest first, 32 to a request. A new choice means a new model, and so new vectors for everything. Search keeps working meanwhile, with the vectors the new model has made, and with words. On the CPU, the embedder handled about 600 tokens a second on 6 cores, when measured: under a second for a 2,000-character reply, and about 7 minutes for 1,000 earlier messages of 1,000 characters each. Chats don’t wait for it. ## On a GPU [Section titled “On a GPU”](#on-a-gpu) You need: * an install made by `setup.sh` * an NVIDIA GPU, with NVIDIA’s driver, so that `nvidia-smi` works on the machine * the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html), set up for your engine. With podman, that is a CDI spec: `sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml`. With docker, it is `sudo nvidia-ctk runtime configure --runtime=docker`, then `sudo systemctl restart docker`. Then pick **Local, on a GPU**. Before it switches, the machine makes a trial run: `nvidia-smi` in llama.cpp’s CUDA image, with the GPU. If no GPU answers, the embedder stays where it was, and the line says **No GPU answered a trial run. A GPU needs NVIDIA’s driver and container toolkit on the machine.** The first switch downloads llama.cpp’s CUDA image, about 2.6 GB, and the model, 639 MB. On a fresh install, `setup.sh` makes this switch itself when `nvidia-smi` works on the machine, and stays on the CPU if the trial run fails. ## From a provider [Section titled “From a provider”](#from-a-provider) 1. If you don’t have one yet, [add a provider](/docs/how-to/add-a-provider/) that serves embeddings: an OpenAI, OpenRouter, or AI Gateway key, a Vercel account, Ollama, LM Studio, or another OpenAI-style server. A Vercel account hasn’t been tested. 2. In **Memory search**, pick **A provider’s embedding model**. 3. Pick the **Provider**, and type an **Embedding model** that it serves. fxbot suggests `text-embedding-3-small` for OpenAI, `openai/text-embedding-3-small` for OpenRouter, AI Gateway, and a Vercel account, and `nomic-embed-text` for Ollama, which must have pulled it first (`ollama pull nomic-embed-text`). 4. Choose **Use this model**. fxbot embeds a test string first. If that fails, it keeps the old setting and shows why. The provider receives the text of every memory and message it turns into a vector. Picking a provider also turns the machine’s `embed` container off. If you remove the provider later, search uses words alone until you pick another choice. ## Vectors for chat messages [Section titled “Vectors for chat messages”](#vectors-for-chat-messages) Memories always get vectors while vectors are on. Chat messages get them too by default, from the first 8,000 characters of each, so `chat_history` finds earlier messages by meaning. Each message’s vector adds about 4 KB to the database. * To give vectors to memories only, turn off **Vectors for chat messages too**. `chat_history` then searches by words. * To embed more or less of each message, change the number in **From the first … characters of each**. It applies to messages embedded after the change. Messages that have vectors keep them. ## From a shell [Section titled “From a shell”](#from-a-shell) On an install made by `setup.sh`, the machine’s `fxbot` command switches the local embedder too, with the same trial run before `gpu`: ```sh sudo fxbot embedder gpu # or cpu, or off ``` It changes what the machine runs, not where fxbot takes its vectors from. After `off`, pick **Off** in Settings as well, or the line says the local embedder isn’t answering. More in [Commands](/docs/reference/commands/#fxbot-embedder). ## When it goes differently [Section titled “When it goes differently”](#when-it-goes-differently) * **The line says the local embedder isn’t answering yet.** On its first start, it downloads its model. Until it answers, search uses words, and the vectors wait. Its log: `sudo fxbot logs embed`. * **Local, on a GPU can’t be picked.** It needs an install made by `setup.sh`. * **The line says no GPU answered a trial run.** The machine lacks one of the things in [On a GPU](#on-a-gpu). The embedder stays where it was. * **The embedding model didn’t answer.** The test string failed, and the old setting stays. Check the model’s id, and that the provider serves it. * **Settings says none of your providers serves embeddings.** Add one of the kinds in [From a provider](#from-a-provider). ChatGPT and Grok plans, and OpenCode keys, serve none. # Pair another device from one you have > A paired device pairs another one from anywhere, so a phone that lost its storage, or a new laptop, doesn't wait until you're home. A passkey pairs one with no other device. A paired device pairs another one from anywhere, so a phone that lost its storage, or a new laptop, doesn’t wait until you’re home. A passkey pairs one with no other device. ## From a paired device [Section titled “From a paired device”](#from-a-paired-device) 1. On the paired device, open web.fxbot.sh, and tap **Devices** beside your fxbot. 2. Choose **Pair another device**. It shows a code and a QR code, for 10 minutes and one try. 3. On the new device, open web.fxbot.sh, choose **Pair a device**, and type the code. On an iPhone, [add it to the Home Screen](/docs/how-to/reach-it-from-your-phone/#install-the-app-on-the-device) first, and pair in that app. 4. Both screens show six digits. Check they match, then tap **Approve** on the device that showed the code. Every connected device hears that a device was added, and your fxbot lists it under **Settings** › **Web pairing** › **Devices**, with the device that approved it. ## With a passkey [Section titled “With a passkey”](#with-a-passkey) A passkey pairs a device again with no code and no other device, such as a phone after a reset. Your password manager keeps it, such as iCloud Keychain or Google Password Manager, and syncs it to your other devices. **Add one** while a device is paired: on its **Devices** screen, choose **Add a passkey**, and follow the browser. Your fxbot keeps one public key for it, under **Settings** › **Web pairing** › **Passkeys**. **Use it** on the new device: open web.fxbot.sh, choose **Use a passkey**, and pick the passkey for your fxbot. The device is paired, and every connected device hears it. Your fxbot uses the relay it had when you added the passkey: if it’s one of your own, put its address under **Relay** first. A passkey works only at web.fxbot.sh, so another site can’t use it. To stop one pairing devices, remove it under **Passkeys**. ## Remove a lost device [Section titled “Remove a lost device”](#remove-a-lost-device) On any paired device’s **Devices** screen, or in **Settings** › **Web pairing** › **Devices** on your fxbot, choose **Remove** beside it. Its connection closes at once, and it can’t connect again until it pairs again. Removing the device you’re on works too: it says so, and stops. **Forget on this device**, on the **Devices** screen, only deletes the pairing from the device in your hand. Your fxbot keeps listing it until you remove it there. # Reach fxbot from other devices > fxbot listens on 127.0.0.1:8787 and has no login of its own. This guide shows the ways to open it: on the machine, then from other devices, starting with web pairing, the recommended way. fxbot listens on 127.0.0.1:8787 and has no login of its own. This guide shows the ways to open it: on the machine, then from other devices, starting with web pairing, the recommended way. ## On the machine itself [Section titled “On the machine itself”](#on-the-machine-itself) Open `http://127.0.0.1:8787` in a browser on that machine. Everything works there, [installing the app](/docs/how-to/reach-it-from-your-computer/#install-it-as-an-app) included, and nothing else can reach it. ## With web pairing (recommended) [Section titled “With web pairing (recommended)”](#with-web-pairing-recommended) The **web-pairing** plugin opens your fxbot at [web.fxbot.sh](https://web.fxbot.sh) on a phone or any computer, over a WebRTC connection straight to it. Nothing on the machine is exposed, and fxbot.sh passes only the sealed handshake. You pair each device once. See [Reach it from your phone](/docs/how-to/reach-it-from-your-phone/) and [from your computer](/docs/how-to/reach-it-from-your-computer/). Most networks connect directly. Some, such as work Wi-Fi that blocks UDP, need Tailscale, WireGuard, or a TURN server of your own: **Settings** › **Web pairing** › **Reachability** says in advance, and [When a device can’t connect](/docs/how-to/when-a-device-cant-connect/) has the fixes. ## Over SSH [Section titled “Over SSH”](#over-ssh) For a machine with no screen, such as a VPS, run this on a computer that reaches it by SSH: ```sh ssh -N -L 8787:127.0.0.1:8787 @ ``` While it runs, fxbot is at `http://127.0.0.1:8787` on that computer, and on nothing else. For a phone, use web pairing or Tailscale. ## With Tailscale [Section titled “With Tailscale”](#with-tailscale) [Tailscale](https://tailscale.com) gives fxbot an HTTPS address that only your own devices reach. On the machine, with Tailscale running and [HTTPS turned on](https://tailscale.com/kb/1153/enabling-https) for your tailnet: ```sh sudo tailscale serve --bg 8787 ``` fxbot is then at `https://..ts.net` on every device in your tailnet. To give it a name of its own, such as `bot..ts.net`, see [Serve it at its own name](/docs/how-to/tailscale-service/). On a phone: 1. Install Tailscale from the App Store or Google Play, and sign in with the same account as the machine. 2. Turn the VPN on in the app. 3. Open `https://..ts.net` in the browser. [MagicDNS](https://tailscale.com/kb/1081/magicdns), on by default, makes that name work. Add it to the Home Screen to install fxbot as an app. Tailscale connects where web pairing can’t directly, such as on networks that block UDP, through its own relays over HTTPS. With Tailscale on the phone too, web pairing likely connects through the tailnet as well, since the machine’s tailnet address is one of its candidates. ## Through a proxy or VPN of your own [Section titled “Through a proxy or VPN of your own”](#through-a-proxy-or-vpn-of-your-own) Anything else in front of fxbot works if it: * **adds its own login or access control.** Whoever reaches fxbot can use all of it: every bot, chat, and provider. * **serves HTTPS.** Phones install the app only from an HTTPS address, and an MCP server’s sign-in comes back to fxbot by itself only over HTTPS. * **passes the `Host` header through unchanged,** such as nginx’s `proxy_set_header Host $host`. fxbot refuses a write whose page origin doesn’t match the host it was reached at. * **doesn’t buffer responses,** such as nginx’s `proxy_buffering off`, and lets them run long: each chat streams its replies. Point the proxy at `http://127.0.0.1:8787` on the same machine. ## Never [Section titled “Never”](#never) * Open port 8787 to a network directly, or forward it from a router. * Share fxbot publicly, such as with [Tailscale Funnel](https://tailscale.com/kb/1223/funnel), without a login in front of it. The [security model](/docs/explanation/security/) explains why fxbot leaves this to what you put in front of it. # Reach it from your computer > Open fxbot as an app of its own on a Windows, Mac, or Linux computer, in Chrome, Edge, Safari, or Firefox: on the machine it runs on, or on any other computer with web pairing. Open fxbot as an app of its own on a Windows, Mac, or Linux computer, in Chrome, Edge, Safari, or Firefox: on the machine it runs on, or on any other computer with web pairing. Installed, it has its own window and icon, without the browser’s bars. ## On the machine fxbot runs on [Section titled “On the machine fxbot runs on”](#on-the-machine-fxbot-runs-on) Open `http://127.0.0.1:8787` in a browser there, then [install it](#install-it-as-an-app). ## On another computer [Section titled “On another computer”](#on-another-computer) Web pairing opens your fxbot at [web.fxbot.sh](https://web.fxbot.sh), over a connection straight to it, away from home too. You need the **web-pairing** plugin: add it from **Plugins**. 1. On the computer, open web.fxbot.sh, [install it](#install-it-as-an-app), and open the app. Pair in the app, not in a private window: what a private window stores is gone when it closes. 2. On your fxbot, open **Settings** › **Web pairing**, and choose **Pair a device**. Use the machine itself, Tailscale, or an [SSH tunnel](/docs/how-to/reach-it-from-your-phone/#from-a-server-with-no-screen). It shows a code, such as `47-3816-0925`. 3. In the app, choose **Pair a device**, and type the code. 4. Both screens show six digits. Check they’re the same, then choose **Approve** on your fxbot. The app says **Paired**. Choose **Open**: your fxbot fills the window, with your bots, plugins, and settings. A computer that’s already paired can [pair this one](/docs/how-to/pair-another-device/) from anywhere. For other ways in, such as an SSH tunnel or Tailscale, see [Reach fxbot from other devices](/docs/how-to/reach-it/). ## Install it as an app [Section titled “Install it as an app”](#install-it-as-an-app) Install from whichever address you opened: `http://127.0.0.1:8787` on the machine, or web.fxbot.sh elsewhere. * **Chrome,** on Windows, Mac, or Linux: choose **Install** at the right of the address bar. Or open the menu (**⋮**), then **Cast, save, and share** › **Install page as app**. At `http://127.0.0.1:8787`, fxbot’s **Settings** › **General** has an **Install** button too. * **Edge,** on Windows, Mac, or Linux: choose the install button at the right of the address bar. Or open **Settings and more** (**…**), then **More tools** › **Apps** › **Install this site as an app**. At `http://127.0.0.1:8787`, **Settings** › **General** has the **Install** button here too. * **Safari,** on a Mac with macOS Sonoma 14 or later: choose **File** › **Add to Dock**, or **Share** › **Add to Dock**, then **Add**. * **Firefox** runs fxbot in a tab, and doesn’t install it as an app of its own. To keep it at hand, right-click its tab and choose **Pin Tab**. Then open fxbot like any other app: * **Windows:** from the Start menu. Right-click its icon in the taskbar, and choose **Pin to taskbar** to keep it there. * **Mac:** from the Dock, Launchpad, or Spotlight. * **Linux:** from your desktop’s app menu. # Reach fxbot from your phone > Open your own fxbot from a phone or any computer, at web.fxbot.sh, over a connection straight to it, with no Tailscale. Open your own fxbot from a phone or any computer, at [web.fxbot.sh](https://web.fxbot.sh), over a connection straight to it, with no Tailscale. You pair each device once, and it stays paired until you remove it. You need the **web-pairing** plugin: add it from **Plugins**. It needs fxbot 0.8.0 or newer. ## Install the app on the device [Section titled “Install the app on the device”](#install-the-app-on-the-device) * **On an iPhone or iPad,** open web.fxbot.sh in Safari, tap **Share**, then **Add to Home Screen**. Open fxbot from the Home Screen, and pair there. The Home Screen app keeps its own storage, apart from Safari’s, and Safari clears a site’s storage after seven days without a visit. A pairing made in Safari stays in Safari. * **On Android,** open web.fxbot.sh in Chrome, and tap **Install app** in its menu. Pair in the installed app. * **On a computer,** see [Reach it from your computer](/docs/how-to/reach-it-from-your-computer/). Don’t pair in a private window: what it stores is gone when it closes. The app says so when it sees one. ## Pair it [Section titled “Pair it”](#pair-it) 1. On your fxbot, open **Settings** › **Web pairing**, and choose **Pair a device**. Use the machine itself, Tailscale, or an [SSH tunnel](#from-a-server-with-no-screen). It shows a code, such as `47-3816-0925`, and a QR code. 2. On the device, in the app, choose **Pair a device**, and type the code. On Android, **Scan the QR code** scans it instead. A laptop can open the QR code’s link. On an iPhone, type the code: the camera would open the link in Safari, not in the Home Screen app. 3. Both screens show six digits. Check they’re the same, then tap **Approve** on your fxbot. If they differ, tap **Deny**: someone else is pairing. The device says **Paired**. Tap **Open**: your fxbot’s own page fills the screen, with your bots, plugins, and settings. A code works once, for 10 minutes. A wrong code ends it, so ask for a new one. Three wrong codes in 15 minutes lock pairing for 15 minutes. ## After pairing [Section titled “After pairing”](#after-pairing) * **It reconnects by itself,** when you come back to the app, when the network changes, and when your fxbot restarts. A dot by its name says whether it’s connected. * **Keep a way back.** Pair a second device, such as your laptop, so a phone that loses its storage can [pair again from it](/docs/how-to/pair-another-device/) from anywhere. Or add a passkey there. * **Check it’ll connect from elsewhere.** **Settings** › **Web pairing** › **Reachability** says what your fxbot found about its network, before you leave home. If it says a network won’t connect directly, see [When a device can’t connect](/docs/how-to/when-a-device-cant-connect/). The app asks the browser to keep its storage. The **Devices** screen says whether the browser agreed. If it didn’t, the browser may clear the pairing when space runs low, so keep a second device or a passkey. ## From a server with no screen [Section titled “From a server with no screen”](#from-a-server-with-no-screen) On a VPS or a machine with no browser, open its **Settings** through an SSH tunnel from your computer: ```sh ssh -N -L 8787:127.0.0.1:8787 @ ``` Then open `http://127.0.0.1:8787/settings/plugins/web-pairing` on your computer, and pair from there. Close the tunnel when you’re done. The device reaches the server directly afterwards. ## Remove a device [Section titled “Remove a device”](#remove-a-device) On your fxbot, in **Settings** › **Web pairing** › **Devices**, or on another paired device’s **Devices** screen, choose **Remove**. Its connection closes at once, and it can’t connect again until it pairs again. # Reach fxbot with WireGuard > A WireGuard tunnel from your phone to your home network, which works where web pairing can't connect directly, run by you, with no account anywhere. A [WireGuard](https://www.wireguard.com) tunnel from your phone to your home network works where web pairing can’t connect directly, run by you, with no account anywhere. It needs one UDP port open at home, so it doesn’t help when your provider’s NAT is in front of your router ([carrier-grade NAT](/docs/how-to/when-a-device-cant-connect/#carrier-grade-nat)). There, use Tailscale or a TURN server. ## Where it runs [Section titled “Where it runs”](#where-it-runs) * **On the router,** if it has WireGuard, as OpenWrt, OPNsense, pfSense, UniFi, and many others do. Follow its own guide, then skip to [Open fxbot through it](#open-fxbot-through-it). * **On fxbot’s machine,** with UDP 51820 forwarded to it on the router. The steps below are for Debian or Ubuntu. ## Set it up on fxbot’s machine [Section titled “Set it up on fxbot’s machine”](#set-it-up-on-fxbots-machine) 1. **Install it, and make the machine’s keys:** ```sh sudo apt install wireguard qrencode wg genkey | sudo tee /etc/wireguard/server.key | wg pubkey | sudo tee /etc/wireguard/server.pub ``` 2. **Make a key pair for the phone:** ```sh wg genkey | tee phone.key | wg pubkey > phone.pub ``` 3. **Write `/etc/wireguard/wg0.conf`:** ```ini [Interface] Address = 10.88.0.1/24 ListenPort = 51820 PrivateKey = [Peer] # The phone: it reaches this machine only. PublicKey = AllowedIPs = 10.88.0.2/32 ``` 4. **Start it, and open the port:** ```sh sudo systemctl enable --now wg-quick@wg0 sudo ufw allow 51820/udp ``` On the router, forward UDP 51820 to this machine, as [Forward or map a port](/docs/how-to/forward-a-port/#forward-them-by-hand) shows. 5. **Make the phone’s config,** `phone.conf`: ```ini [Interface] Address = 10.88.0.2/32 PrivateKey = [Peer] PublicKey = Endpoint = :51820 # Only fxbot's machine goes through the tunnel; everything else goes as usual. AllowedIPs = 10.88.0.1/32 PersistentKeepalive = 25 ``` 6. **Give it to the phone.** Install the WireGuard app, tap **+**, then **Scan from QR code**, and scan: ```sh qrencode -t ansiutf8 < phone.conf ``` Then delete `phone.key` and `phone.conf`. Each phone gets its own key pair and `[Peer]`, at the next address. ## Open fxbot through it [Section titled “Open fxbot through it”](#open-fxbot-through-it) fxbot listens on the machine’s loopback only, so the tunnel alone doesn’t reach it. Either: * **Use web pairing through the tunnel.** With the tunnel on, the phone and fxbot can likely connect over it, since the tunnel’s address is one of fxbot’s candidates. Open web.fxbot.sh as usual. * **Or put a proxy on the tunnel’s address,** such as Caddy listening on `10.88.0.1` and passing to `127.0.0.1:8787`, as [Reach it](/docs/how-to/reach-it/#through-a-proxy-or-vpn-of-your-own) describes. A phone installs the app only over HTTPS. # Run your own relay > Run web.fxbot.sh's Worker, the shell, the frames, and the relay, on your own Cloudflare account and domain, and point your fxbot at it. Run web.fxbot.sh’s Worker on your own Cloudflare account and domain, and point your fxbot at it. It’s the same code: the app your devices open, a frame for each fxbot, and the relay that passes the sealed handshake. One fxbot uses about 100 of the free plan’s 100,000 daily Durable Object requests. You need a Cloudflare account with a domain on it, such as `example.com`, and a checkout of fxbot with Node 22.18 or newer. ## Deploy it [Section titled “Deploy it”](#deploy-it) 1. In `packages/web-app/wrangler.toml`, copy the `[env.production]` section as `[env.mine]`, with your domain: ```toml [env.mine] name = "fxbot-web" routes = [ { pattern = "web.example.com", custom_domain = true }, { pattern = "*.example.com/*", zone_name = "example.com" }, ] vars = { SHELL_HOST = "web.example.com" } durable_objects.bindings = [ { name = "RELAY", class_name = "Relay" }, { name = "PLATES", class_name = "Plates" }, ] ``` The app must be at `web.` of a domain: each fxbot’s frame is at a name of its own beside it, `.example.com`. 2. In Cloudflare’s DNS for the domain, add a proxied `A` record for `*` pointing at `192.0.2.1`, so the frames’ names reach the Worker. The custom domain makes `web.` itself. 3. Build and deploy, from `packages/web-app`: ```sh npm ci npx wrangler login node build.mjs && npx wrangler deploy --env mine ``` ## Use it [Section titled “Use it”](#use-it) In your fxbot’s **Settings** › **Web pairing** › **Relay and ports**, put `wss://web.example.com/signal`, and **Save**. Your fxbot connects there, and its pairing links and codes say so. On a device, pair at `https://web.example.com`, or type the relay under **Relay** when you type a code. Devices paired through fxbot.sh’s relay need pairing again: a pairing remembers its relay. ## What it keeps [Section titled “What it keeps”](#what-it-keeps) Nothing. The Worker has no storage, no alarms, and no logs: its `wrangler.toml` turns Workers Logs off. Each fxbot’s connection lives in a Durable Object’s memory while it’s open. Cloudflare still sees IP addresses and connection times, as for any Worker. # Run your own STUN server > A STUN server tells each end its public address, so a device and your fxbot can connect directly. fxbot uses Cloudflare's by default; you can add your own, put it first, or remove Cloudflare's. A STUN server tells each end its public address, so a device and your fxbot can connect directly. It sees only that address. fxbot uses Cloudflare’s, `stun:stun.cloudflare.com:3478`, by default. You can add your own, put it first, or remove Cloudflare’s, under **Settings** › **Web pairing** › **ICE servers**. Devices get the same list, in the same order, and contact no others. ## With coturn, STUN only [Section titled “With coturn, STUN only”](#with-coturn-stun-only) On any machine with a public address, such as a small VPS: ```sh sudo apt install coturn ``` In `/etc/turnserver.conf`: ```ini listening-port=3478 stun-only no-cli no-stdout-log log-file=/dev/null ``` Then `sudo systemctl enable --now coturn`, and open UDP 3478 in its firewall. A TURN server of your own answers STUN too, so if you [run one](/docs/how-to/run-your-own-turn/), you have this already. ## Or another public server [Section titled “Or another public server”](#or-another-public-server) Any STUN server works, such as Google’s `stun:stun.l.google.com:19302`. Each sees your public address when your fxbot or a device connects. ## Put it in the list [Section titled “Put it in the list”](#put-it-in-the-list) 1. In **ICE servers**, pick **STUN server**, type its address, such as `stun:stun.example.com:3478`, and choose **Add**. 2. Move it up with **↑** to try it first. 3. To stop using Cloudflare’s, choose **Remove** beside it. **Add Cloudflare’s STUN back** returns it. Your fxbot’s own WebRTC library uses the first STUN server in the list. With none at all, devices connect only on your fxbot’s own network. ## Add a second STUN server [Section titled “Add a second STUN server”](#add-a-second-stun-server) With two STUN servers, or one at two addresses, **Reachability** can tell how your fxbot’s NAT maps ports, which says whether devices behind a [symmetric NAT](/docs/how-to/when-a-device-cant-connect/#a-symmetric-nat) can reach it. With one, it says it can’t tell. Add any second server, then **Check again**. # Run your own TURN server > A TURN server carries a device's connection when no direct path works, such as on a network that blocks UDP. fxbot.sh runs none: this is yours, on a small VPS or on Cloudflare. A TURN server carries a device’s connection when no direct path works, such as on a network that blocks UDP. fxbot.sh runs none: this is yours, on a small VPS or on your own Cloudflare account. The connection stays encrypted end to end through it: a TURN server sees IP addresses, timing, and how much passes, not what. Either way, it goes into **Settings** › **Web pairing** › **ICE servers**, and devices get it the next time they connect. ## On a small VPS, with coturn [Section titled “On a small VPS, with coturn”](#on-a-small-vps-with-coturn) Any VPS with a public IPv4 address works, such as one for €4 a month. A watched desktop through it is about 1.35 GB an hour; a chat is kilobytes. These steps are for Debian or Ubuntu, with a domain name pointing at the VPS, such as `turn.example.com`. 1. **Install coturn and a certificate:** ```sh sudo apt install coturn certbot sudo certbot certonly --standalone -d turn.example.com ``` coturn runs as its own user, which can’t read certbot’s keys, so give it a copy, now and at each renewal: ```sh sudo install -d -o turnserver -g turnserver /etc/coturn/certs printf '#!/bin/sh\ninstall -o turnserver -m 600 /etc/letsencrypt/live/turn.example.com/fullchain.pem /etc/letsencrypt/live/turn.example.com/privkey.pem /etc/coturn/certs/\nsystemctl restart coturn\n' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/coturn > /dev/null sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/coturn && sudo /etc/letsencrypt/renewal-hooks/deploy/coturn ``` 2. **Make a shared secret,** which fxbot turns into short-lived passwords: ```sh openssl rand -hex 32 ``` 3. **Write `/etc/turnserver.conf`:** ```ini # TLS on 443, which networks that allow only web traffic let through, and plain UDP on 3478. listening-port=3478 tls-listening-port=443 cert=/etc/coturn/certs/fullchain.pem pkey=/etc/coturn/certs/privkey.pem realm=turn.example.com # Passwords fxbot makes from the shared secret, each good for 24 hours. use-auth-secret static-auth-secret= # Never relay into the VPS's own network, or any private one. no-multicast-peers denied-peer-ip=0.0.0.0-0.255.255.255 denied-peer-ip=10.0.0.0-10.255.255.255 denied-peer-ip=100.64.0.0-100.127.255.255 denied-peer-ip=127.0.0.0-127.255.255.255 denied-peer-ip=169.254.0.0-169.254.255.255 denied-peer-ip=172.16.0.0-172.31.255.255 denied-peer-ip=192.168.0.0-192.168.255.255 denied-peer-ip=::1 denied-peer-ip=fc00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff denied-peer-ip=fe80::-febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff # A limit for each user, and no log of who connected. user-quota=12 total-quota=120 no-cli no-stdout-log simple-log log-file=/dev/null ``` 4. **Let it bind port 443, and start it:** ```sh sudo setcap cap_net_bind_service=+ep /usr/bin/turnserver sudo systemctl enable --now coturn ``` 5. **Open the firewall:** TCP 443, UDP and TCP 3478, and UDP 49152–65535, which coturn relays through. With ufw: ```sh sudo ufw allow 443/tcp && sudo ufw allow 3478 && sudo ufw allow 49152:65535/udp ``` 6. **Add it to fxbot.** In **ICE servers**, pick **TURN with a shared secret (coturn, eturnal)**, and add it twice, once for each way in: * `turns:turn.example.com:443?transport=tcp`, with the secret * `turn:turn.example.com:3478`, with the secret [eturnal](https://eturnal.net) works the same way: its `secret` is the shared secret. ## On Cloudflare, with your own account [Section titled “On Cloudflare, with your own account”](#on-cloudflare-with-your-own-account) Cloudflare’s TURN gives each account 1,000 GB a month free, then $0.05 for each GB it sends. It answers on port 443 too. 1. In the Cloudflare dashboard, open **Realtime** › **TURN Server**, and create a TURN key. 2. Copy its **Turn Token ID** and its **API Token**. 3. In **ICE servers**, pick **Cloudflare TURN key**, and paste both. fxbot asks Cloudflare for credentials, good for 24 hours, each time a device connects, and keeps them for 12. The key’s token stays sealed in fxbot. ## Check it [Section titled “Check it”](#check-it) Under **ICE servers**, the TURN server sits after the STUN servers, so devices try a direct path first. **Reachability** then says “Your TURN server covers the rest”. The best check is the network that didn’t connect: the device connects within a few seconds. To check the server alone, [Trickle ICE](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/) takes a TURN address with a username and password and shows whether it answers. For a server with a shared secret, the username is a time and a name, such as `1767225600:check`, and the password is the base64 of its HMAC-SHA1 under the secret. # Start a chat over with /fresh > /fresh starts a bot's chat over toward what you write next: the bot summarizes the chat, keeping what bears on your words, and your message starts the new chat. `/fresh` starts a bot’s chat over toward what you write next. The bot summarizes the chat so far, keeping what bears on your words, and your message starts the new chat. Use it when a chat has drifted, or when you want the bot’s full attention on something new without losing what it knows about you. It’s built into every bot’s chat since fxbot 0.10.0. Before that, it came from the fresh plugin: see [When you still have the fresh plugin](#when-you-still-have-the-fresh-plugin). 1. In a bot’s chat, type `/fresh` and where you want to go, such as `/fresh let's plan the Lisbon trip`. Typing `/` lists it with the bot’s skills. 2. Send it. The bot’s model writes the summary, which takes as long as a reply, and the message shows **Thinking…** meanwhile. The chat then shows a **Started over** card, which opens to the summary, then your message without `/fresh`, and the bot’s answer. The old chat stays above the card, and the bot finds what was said there with `chat_history`. Every page open on the bot follows to the new chat. ![Atlas's chat, with /fre typed in the message box and fresh offered above it](/shots/fresh-desktop-light.png) ![Atlas's chat, with /fre typed in the message box and fresh offered above it](/shots/fresh-desktop-dark.png) ## What the summary keeps [Section titled “What the summary keeps”](#what-the-summary-keeps) * who you are, and the preferences and rules you set, each rule in your own words * the facts, decisions, and open tasks that bear on what you wrote, with exact names, numbers, dates, paths, and links * what was done, apart from what was only suggested It leaves out the threads that don’t bear on your words, in at most 600 words. `/fresh` alone starts over with what still matters, and sends nothing. The whole request is `freshAsk` in fxbot’s [source](https://github.com/iammrduncan/fxbot/blob/main/packages/sdk/src/history.ts). ## When it doesn’t start over [Section titled “When it doesn’t start over”](#when-it-doesnt-start-over) * **A chat with no messages yet:** your words go to it as they are. * **A plugin’s chat,** such as a routine’s run: `/fresh` is ordinary text there. A chat room starts over as a whole, with chat rooms 0.5.0: see [Start a room over](/docs/how-to/talk-in-a-room/#start-a-room-over). ## When you still have the fresh plugin [Section titled “When you still have the fresh plugin”](#when-you-still-have-the-fresh-plugin) On fxbot 0.10.0 and newer, the fresh plugin shows **Unsupported** in **Plugins**, since `/fresh` is built in. Remove it there. It kept nothing, so nothing is lost, and `/fresh` works the same. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) * **“Not sent: The chat could not be summarized”.** The bot’s provider didn’t answer the summary, within 2 minutes at most. Nothing moved: choose **Retry** once the provider answers. * **A long wait.** The summary is one request to the bot’s model, over the whole chat. A reverse proxy in front of fxbot must allow a request that long, as a provider switch already needs. # Serve fxbot at its own tailnet name > Give fxbot a name of its own, such as bot..ts.net, as a Tailscale Service, instead of the machine's address. The machine must be tagged. Give fxbot a name of its own, such as `bot..ts.net`, as a [Tailscale Service](https://tailscale.com/kb/1552/tailscale-services), instead of the machine’s address. The machine must be tagged. A tailnet admin does three things once: 1. **Define the service** on the admin console’s Services page: **Define a Service**, named `bot`, with the port `tcp:443`. 2. **Approve this machine** as its host on that service’s page, or with an `autoApprovers` rule for the machine’s tag. 3. **Grant access** in the policy file, such as: ```json { "src": ["autogroup:member"], "dst": ["svc:bot"], "ip": ["443"] } ``` Then, on the machine: ```sh sudo tailscale serve --service=svc:bot --https=443 http://127.0.0.1:8787 ``` Check the address from a phone or a laptop on the tailnet, not from the machine itself: a grant to people doesn’t cover a tagged machine, so the name may not resolve there. An app installed from the machine’s address stays on that address. To move to the new name, open it there and install the app again. # Talk with several bots in a room > Make a chat room of your bots, tag a bot with @ to ask it, let bots hand work to each other, and stop them. Rooms are a plugin, chat-rooms. A room holds you and several of your bots. Tag a bot with `@` to ask it. A bot can tag another to hand it part of the work, and that one answers next. Rooms are a plugin, **chat-rooms**. 1. Open **Plugins**, choose **Browse**, and add **chat-rooms**. 2. In the sidebar, choose **+** beside **Rooms**. Name the room, and pick its bots. The first bot you pick is the room’s lead. 3. In the room, type `@` and pick a bot from the list. It becomes a chip with the bot’s avatar. Write your message, and send it. ![A room called Garden party: the owner tags Pixel and Sprout, and each answers](/shots/room-desktop-light.png) ![A room called Garden party: the owner tags Pixel and Sprout, and each answers](/shots/room-desktop-dark.png) ## Who answers [Section titled “Who answers”](#who-answers) | Your message | Who answers | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Tags one or more bots | Those bots, in the order you tagged them | | Tags **Everyone** | Every bot in the room, in its order | | Tags no one | The lead, which can bring others in by tagging them. Or, with the room’s setting **Everyone answers**, every bot in order | A bot that tags another in its reply hands the conversation on: that bot answers after it, and sees what was said. When a reply tags no one, the bots stop, and it’s your turn. A bot can tag at most three bots in one reply. Each room limits the bot replies to one message of yours: 10 unless you change it. At the limit, bots stop tagging each other, and a note says they paused. The bots already asked still answer, so everyone gets to wrap up, and a round can end a reply or two past the limit. Tag a bot to go on. While bots answer, the room shows who’s writing and who’s next. **Stop** ends the reply being written and drops the rest. A message you send meanwhile drops the bots waiting their turn too. ## Change a room [Section titled “Change a room”](#change-a-room) **Edit**, at the top of a room, changes its name, its bots and their order, what a message that tags no one does, and the bot replies per message. **Delete room** deletes the room and what was said in it. To move a room in the sidebar, drag it, with a mouse, or with a finger after a moment’s hold. Rooms keep the order you leave them in. Needs fxbot 0.7.0. Only bots that chat rooms is on for can be in a room. To give it to some bots only, see [Add a plugin](/docs/how-to/add-a-plugin/). ## Give a room memories [Section titled “Give a room memories”](#give-a-room-memories) Each room keeps notes of its own, such as what the room is for, what was decided there, and who does what. Every bot in the room reads them there, and not in its other chats. Needs chat rooms 0.4.0. * **To see them,** choose **Memories** at the top of the room. Each one says when it was saved, and who saved it: you, or a bot. * **To add one,** write it in the box, and choose **Add a memory**. **Edit** and **Delete** change and remove one. The bots see a change on their next turn in the room. * **To have a bot save one,** ask it to remember something for the room. A bot also saves one when the room settles something. It saves with `chat-rooms_remember`, and removes one with `chat-rooms_forget`. Both work only in a room. A memory is one note, of at most 1,000 characters. The newest that fit in 6,000 bytes go to each bot. Deleting a room deletes its memories, and so does removing the plugin. For what every bot should know, in every chat, use team memories, in **Settings** › **Memory**: see [Team memories](/docs/explanation/bots-and-chats/#team-memories). A room can also have a computer of its own, which its bots share: see [Give a room a computer](/docs/how-to/give-bots-a-computer/#give-a-room-a-computer). ## Start a room over [Section titled “Start a room over”](#start-a-room-over) A room starts over from a summary, as a bot’s own chat does: each bot goes on from the summary and what’s said after it, not the whole room again. Needs chat rooms 0.5.0. * **To start it over,** begin a message with `/fresh`, then what you want next, such as `/fresh let's plan the second week`. Typing `/` at the start of the message box lists it. The room stops what its bots are doing, says **Starting the room over…**, and a summary aimed at what you wrote keeps what bears on it. Then **Started over** shows, your message follows, and the bots answer it from the summary. `/fresh` alone starts the room over and waits for your next message. * **While you’re away,** a long room that sits idle is compacted, by the same setting as a bot’s own chat: **Settings** › **General** › **Idle compaction**, and **Summarize with** for the model. It shows **Compacted while idle**. See [Idle compaction](/docs/explanation/bots-and-chats/#idle-compaction). The room’s lead, its first bot, writes the summary, unless **Summarize with** names a model. Each card opens to its summary. The earlier messages stay above it, and the bots still find them with `chat_history`. If the summary can’t be written, the room says so, and goes on as it was. ## What a bot knows in a room [Section titled “What a bot knows in a room”](#what-a-bot-knows-in-a-room) Each bot answers in a chat of its own for the room, which stays out of its own chat. Its `chat_history` tool still finds what was said in a room. Each turn, it’s sent: * who it is, and who else is in the room * its own memories, the team’s, and the room’s, in that order * what was said since its last turn, with the other bots’ words quoted as theirs * who woke it, and how many replies are left * after the room starts over, its summary, which a model wrote from what everyone said there Its first turn in a room carries the plugin’s `chat-room` skill: when to answer, when to stay quiet, and how to tag. It can also read: * `room-handoff`, on handing work to another bot * `room-lead`, for the lead A bot’s tools work in a room as in its own chat. ## When it goes differently [Section titled “When it goes differently”](#when-it-goes-differently) * **A bot didn’t answer.** It may have had nothing to add: a bot can stay quiet. If a note says the bot has chat rooms off, switch it on for that bot in **Settings** › **Chat rooms**. * **The bots stopped tagging each other.** The room reached its replies per message. Tag a bot to go on, or raise the limit in **Edit**. * **Stop let the reply finish.** fxbot older than 0.4.1 can’t cancel a reply that’s being written, so **Stop** only drops the bots waiting. # Uninstall fxbot > One command takes fxbot off a machine that setup.sh installed it on. It keeps a backup and the key, so you can install again later, unless you tell it --purge. One command takes fxbot off a machine that `setup.sh` installed it on. It keeps a backup and the key, so you can install again later, unless you tell it `--purge`. ## Uninstall [Section titled “Uninstall”](#uninstall) ```sh sudo fxbot uninstall ``` It says what it removes and what it keeps, then asks once, `[y/N]`. Anything but **y** changes nothing. It removes: * fxbot’s containers, its database and model volumes, and its images, at every version it pulled * the computer, when it’s set up: the user `fxbot-computer`, every computer and its home, its firewall, and its units * `fxbot.service`, `fxbot-control.path` and `fxbot-control.service`, the `fxbot` command, and `/opt/fxbot` * the rules it added to ufw, marked `fxbot` It keeps: * **a backup** it takes first, of the database and the plugins’ files, in `/var/lib/fxbot/backups/-uninstall` * **the key**, `/etc/fxbot/secret.key`, which opens the keys and tokens the backup holds * **the user `fxbot`**, which owns them * **podman or Docker**, and their other containers, volumes, and images: it touches only fxbot’s own, by name Last, it says what’s left: the packages `setup.sh` installed, with the command that removes them if nothing else uses them, and Docker’s repository when `setup.sh` added it. It also names images from older releases’ databases and embedders, which another project may use, and `sudo tailscale serve reset` when Tailscale still serves fxbot’s port. ## Remove everything [Section titled “Remove everything”](#remove-everything) ```sh sudo fxbot uninstall --purge ``` The same, with no backup, and it also removes `/var/lib/fxbot`, every backup in it, `/etc/fxbot`, the key and the app’s settings, and the user `fxbot`. What fxbot stored can’t be opened again after this. ## Without a question [Section titled “Without a question”](#without-a-question) With no terminal, as when an agent or a script runs it, it stops and asks for `--yes`: ```sh sudo fxbot uninstall --yes ``` ## Install again on the backup [Section titled “Install again on the backup”](#install-again-on-the-backup) ```sh curl -fsSL https://fxbot.sh/setup.sh | sudo bash sudo fxbot restore /var/lib/fxbot/backups/-uninstall sudo fxbot up ``` `setup.sh` uses the key it finds in `/etc/fxbot`, so the restored keys and tokens open. The last lines of the uninstall name the backup’s folder. ## On your devices [Section titled “On your devices”](#on-your-devices) The installed app goes from a phone’s home screen, or a computer’s apps, like any other. Keys you made for fxbot at a provider stay good until you revoke them there. A device paired at web.fxbot.sh reaches fxbot again after an install on the backup, since its keys come back with it. After `--purge`, open web.fxbot.sh on each device and choose **Forget on this device** under its devices. A passkey you made for fxbot stays in the device’s passwords until you delete it there. ## By hand [Section titled “By hand”](#by-hand) When the `fxbot` command is gone, or you’d rather do each step yourself. First take a backup, as [Back up fxbot](/docs/how-to/back-up/) says, if you want to keep anything. With docker, use `docker` where these say `podman`. ```sh sudo bash /opt/fxbot/computer-setup.sh --remove # when the computer is set up sudo systemctl disable --now fxbot fxbot-control.path cd /opt/fxbot && sudo podman compose down --volumes --rmi all sudo rm /etc/systemd/system/fxbot.service /etc/systemd/system/fxbot-control.path /etc/systemd/system/fxbot-control.service sudo systemctl daemon-reload sudo rm -rf /opt/fxbot /usr/local/bin/fxbot ``` To remove everything, then also: ```sh sudo rm -rf /var/lib/fxbot /etc/fxbot sudo userdel fxbot ``` `/etc/fxbot/packages` lists the packages and files `setup.sh` installed, one a line, after the name of the package manager. # Update to a new release > For an install made by setup.sh. A checkout updates with git instead. For an install made by `setup.sh`. A checkout updates with git instead. First, read the release’s section of the [changelog](/docs/reference/changelog/). A release that adds migrations, bumps libfx, or needs a step by hand opens with **Before upgrading**. ## From Settings [Section titled “From Settings”](#from-settings) When a newer release is out, **Settings** › **About** shows its notes and an **Update** button. If a plugin you run wouldn’t run on it, a line above the button names it, as “Won’t run on 0.8.0: …”. Look for a newer version of that plugin first, or update anyway and it shows as **Unsupported** ([When it goes differently](/docs/how-to/add-a-plugin/#when-it-goes-differently)). Choose **Update**. The machine’s `fxbot` command downloads the release, gives running chats 30 seconds to finish, and starts it, where any chat still running goes on, while the database keeps running. Settings shows each step, and the page reloads onto the new version once it answers. ## From a shell [Section titled “From a shell”](#from-a-shell) ```sh sudo fxbot update ``` To install a particular release, such as a prerelease, name it: ```sh sudo fxbot update 0.4.0-rc.1 ``` ## From 0.2 [Section titled “From 0.2”](#from-02) 0.2 ran on the machine’s own Node and Postgres, and its Settings can’t move it into containers. Run `setup.sh` again: ```sh curl -fsSL https://fxbot.sh/setup.sh | sudo bash ``` It stops 0.2, copies its database into `/var/lib/fxbot/backups/-move-to-containers/`, restores that copy into the database container, and starts the containers on the same chats, key, and settings. The 0.2 files and database stay until you remove them. `sudo fxbot status` prints the commands. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The new release didn’t download.** fxbot stays on the running one, and says why. * **Another update is running.** Settings says so. From a shell, the second update waits for the first. * **The new release doesn’t start.** Within 5 minutes, fxbot goes back to the release it was on, and restores the backup the new release took before its migrations, if it ran any. Settings shows why. Read more with `sudo fxbot logs fxbot`. * **fxbot doesn’t start after going back.** Read `sudo fxbot logs`, then [go back](/docs/how-to/go-back/) by hand. What an update does, step by step, is in [Releases and updates](/docs/explanation/releases/). # When a device can't connect > What each message from web pairing means, and what fixes it, in order: from what costs nothing to what takes a server of your own. A paired device connects straight to your fxbot. When its network and your fxbot’s can’t reach each other, the app says so after 15 seconds: “Your fxbot answered, but no direct path works between this network and it.” Below it are what each side found, and what would work. **Settings** › **Web pairing** › **Reachability** shows your fxbot’s side in advance, with **Check again**. This page has a section for each thing they find. ## The messages that aren’t about the network [Section titled “The messages that aren’t about the network”](#the-messages-that-arent-about-the-network) These come before any connection, and aren’t fixed by anything below. * **“Your fxbot isn’t connected to the relay.”** Your fxbot is off, web pairing is off or removed, or it lost its network. If it was installed again from nothing, it has new keys: pair again. * **“Your fxbot doesn’t know this device any more.”** The device was removed. [Pair it again](/docs/how-to/pair-another-device/). * **“Remote access is off.”** Turn it on in **Settings** › **Web pairing**. ## Try another network [Section titled “Try another network”](#try-another-network) The quickest test. A phone that can’t connect on cellular often connects on Wi-Fi, and the other way around: work and guest Wi-Fi often block UDP, and some carriers map ports in a way that doesn’t meet your home router’s. If another network works, the sections below say which side to fix. ## UDP is blocked [Section titled “UDP is blocked”](#udp-is-blocked) “This network blocks UDP” means a STUN server never answered. A direct connection needs UDP on both sides, so nothing in this list connects through it but these: 1. **A TURN server of your own, over TLS on port 443,** which looks like web traffic. See [Run your own TURN server](/docs/how-to/run-your-own-turn/). 2. **Tailscale,** whose relays run over HTTPS. See [Reach it with Tailscale](/docs/how-to/reach-it/#with-tailscale). When your fxbot’s side says it, its own network blocks UDP: check the machine’s firewall lets UDP out. ## A symmetric NAT [Section titled “A symmetric NAT”](#a-symmetric-nat) “Maps ports per destination” means a symmetric NAT: each server it talks to sees a different port, so the port a STUN server reports is no use to anyone else. Many phone carriers do this, and some routers. Two such sides can’t connect directly. The fixes, in order: 1. **A mapped or forwarded port at home,** so your fxbot’s side has a port that stays put. See [Forward or map a port](/docs/how-to/forward-a-port/). 2. **IPv6,** where both sides have it: ICE usually connects directly between two IPv6 addresses. 3. **A TURN server of your own.** See [Run your own TURN server](/docs/how-to/run-your-own-turn/). 4. **Tailscale** or **WireGuard.** Your fxbot can tell only with two STUN answers. With one server in its list, it says it can’t tell: [add a second](/docs/how-to/run-your-own-stun/#add-a-second-stun-server). ## Carrier-grade NAT [Section titled “Carrier-grade NAT”](#carrier-grade-nat) “Behind carrier-grade NAT” means your fxbot’s public address is in 100.64.0.0/10, or the router’s own public address differs from the one STUN reports: another NAT sits beyond your router, run by your provider. Forwarding a port on your router doesn’t help, since the provider’s NAT is in front of it. Devices on many networks can’t reach it directly. The fixes: 1. **Ask your provider** for a public IPv4 address, or turn on IPv6. 2. **A TURN server of your own.** See [Run your own TURN server](/docs/how-to/run-your-own-turn/). 3. **Tailscale** or **WireGuard,** whose relays or endpoints sit outside. ## No mapped port [Section titled “No mapped port”](#no-mapped-port) “The router didn’t map a port” means fxbot asked the router by NAT-PMP and UPnP, and neither answered. Many routers have both off. It matters only with a symmetric NAT on the other side. Turn on UPnP or NAT-PMP on the router, or forward the ports by hand: see [Forward or map a port](/docs/how-to/forward-a-port/). A port forwarded by hand can’t be seen from inside, so this message stays after you forward one. ## In a container [Section titled “In a container”](#in-a-container) fxbot in a container can’t map a port, since the router can’t be found from inside it. To forward the ports, publish them from the container: see [Forward or map a port](/docs/how-to/forward-a-port/#from-the-release-containers). ## No STUN server answered [Section titled “No STUN server answered”](#no-stun-server-answered) “There’s no STUN server in the list” means you removed every one. Without one, neither side learns its public address, and devices connect only on your fxbot’s own network. Add one back under **ICE servers**: **Add Cloudflare’s STUN back**, or [one of your own](/docs/how-to/run-your-own-stun/). # Anthropic > Anthropic makes the Claude models. Add credit, then add it to fxbot with a key from the Claude Console, through Anthropic's OpenAI-compatible API. Anthropic makes the Claude models. fxbot reaches them through Anthropic’s OpenAI-compatible API, with a key from the Claude Console. You add credit before a key can run a model. Its prices are on its [pricing page](https://platform.claude.com/docs/en/about-claude/pricing). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [platform.claude.com/settings/keys](https://platform.claude.com/settings/keys), and sign in or make an account. 2. Add credit under [Billing](https://platform.claude.com/settings/billing) first. 3. Choose **Create key**. Give it a name, such as fxbot, pick when it expires, and scope it to a workspace. 4. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Anthropic**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Anthropic first. 3. Pick a model. fxbot fills in `claude-sonnet-5-5` when Anthropic serves it. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Anthropic** when you leave it empty. | Anthropic’s address is `https://api.anthropic.com/v1`. fxbot fills it in, and sends the key as `x-api-key` too, where Anthropic’s model list wants it. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Anthropic’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from Anthropic’s docs. fxbot hasn’t run Anthropic with a real key yet. * **Not Anthropic’s own API.** Anthropic says its OpenAI-compatible API is “not considered a long-term or production-ready solution”. * **No prompt caching.** So a long chat costs more than it would through Anthropic’s own API. For caching now, reach Claude through [AI Gateway with your own Anthropic key](/docs/providers/vercel/#claude-with-your-own-anthropic-key). * **No thinking shown.** Claude 5 models think by default there, but the answer doesn’t carry the thinking, so fxbot shows none. * **A key for one workspace.** A key that isn’t scoped to a workspace needs Anthropic’s `anthropic-workspace-id` header on every request. fxbot doesn’t send it, and Anthropic answers with 400. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Anthropic rejected this key (HTTP 401): it’s wrong, or it was deleted.”** It may also have expired. Make another, and paste that. * **“The key check failed (HTTP 400).”** The key may not be scoped to a workspace. Make one that is. * **“Anthropic rejected this provider’s key. Replace it in Settings › Providers.”** fxbot says this when a chat gets a 401 or a 403, such as after the key expired or was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 400.** Anthropic’s error says why, such as a credit balance too low. Add credit under **Billing**. * **A chat stops with HTTP 429.** You’ve reached your usage tier’s rate limit. Anthropic raises an account’s tier over time. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Azure OpenAI > Azure OpenAI runs your own deployments of OpenAI's models and others, in Azure OpenAI or Microsoft Foundry. Add it to fxbot with a resource name, a key, and your deployments' names. Azure OpenAI runs models as deployments in your own Azure resource, in Azure OpenAI or Microsoft Foundry: OpenAI’s models, and others Foundry offers, such as DeepSeek and Grok. It bills your Azure subscription, at the prices on its [pricing page](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open your resource in the [Foundry portal](https://ai.azure.com/), or in the Azure portal, where its keys are under **Resource Management** › **Keys and Endpoint**. 2. Copy **Key 1**. Either key works. 3. Note the resource’s name: the part before `.openai.azure.com` in its endpoint. 4. Note each deployment’s name, as you named it in Azure. A model answers only once it’s deployed. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Azure OpenAI**, under **Clouds**. 2. Type the **Resource name**, paste the key, type the **Deployments**, and choose **Add**. fxbot checks the key with Azure first. 3. Pick one of your deployments as the model. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **Resource name** | The part before `.openai.azure.com` in its endpoint. For `https://my-team.openai.azure.com/`, it’s `my-team`. | | **API key** | **Key 1**. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Deployments** | Each deployment’s name, as you named it in Azure, with commas between. | | **Name** | Optional. It’s **Azure OpenAI** when you leave it empty. | fxbot fills in the address from the resource: `https://{resource}.openai.azure.com/openai/v1`, Azure’s v1 API, which needs no `api-version`. It sends the key as Azure’s `api-key` header, and as a bearer too. To add or remove deployments later, edit **Deployments** under the provider in **Settings** › **Providers**, and choose **Save**. ## Its models [Section titled “Its models”](#its-models) Your deployments are the list. Azure names the model in a request by its deployment’s name, so that’s what fxbot sends. Where a deployment’s name is a model’s own, such as `gpt-5`, fxbot shows that model’s context window, tool use, and images from [models.dev](https://models.dev). A deployment with a name of your own works the same, without those details. ## Quirks [Section titled “Quirks”](#quirks) These come from Microsoft’s docs. fxbot hasn’t run Azure with a real key yet. * **A key only.** fxbot doesn’t sign in with Microsoft Entra ID yet. * **No list from Azure.** fxbot doesn’t read your deployments from Azure. A deployment you add there shows in fxbot once you type it under **Deployments**. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Resource name isn’t one fxbot can use.”** Type the name alone, not the whole address. * **“Azure OpenAI rejected this key (HTTP 401): it’s wrong, or it was deleted.”** The key may be from another resource, or regenerated in Azure since you copied it. Copy **Key 1** again. * **“Azure OpenAI rejected this provider’s key. Replace it in Settings › Providers.”** fxbot says this when a chat gets a 401 or a 403, such as after the key was regenerated in Azure. Copy the new one, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 404.** The resource has no deployment by that name. Check its spelling under **Deployments**. * **A chat stops with HTTP 429.** You’ve reached the deployment’s quota. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # AWS Bedrock > AWS Bedrock runs OpenAI's open models, Qwen, DeepSeek, Mistral, and more in your own AWS account. Add it to fxbot with a long-term Bedrock API key and a region. AWS Bedrock runs models from many labs in your own AWS account: OpenAI’s open models, Qwen, DeepSeek, Mistral, and more. It bills your AWS account, at the prices on its [pricing page](https://aws.amazon.com/bedrock/pricing/). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open the [Bedrock console’s API keys](https://console.aws.amazon.com/bedrock/home#/api-keys), and sign in. 2. Pick the region at the top of the console. 3. In the **Long-term API keys** tab, choose **Generate long-term API keys**. 4. Under **API key expiration**, pick how long it lasts, and choose **Generate**. 5. Copy the key. AWS recommends long-term keys only for exploring Bedrock. fxbot doesn’t sign in with AWS’s IAM credentials yet. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **AWS Bedrock**, under **Clouds**. 2. Type the **Region** your models run in, paste the key, and choose **Add**. fxbot checks it with Bedrock first. 3. Pick a model. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **Region** | `us-east-1`, the default, or the region your models run in, such as `us-west-2`. | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **AWS Bedrock** when you leave it empty. | fxbot fills in the address from the region: `https://bedrock-runtime.{region}.amazonaws.com/openai/v1`, Bedrock’s OpenAI-compatible Chat Completions. The runtime has no model list, so fxbot checks the key at `https://bedrock-mantle.{region}.api.aws/v1/models` instead. To move to another region, remove the provider and add it again. ## Its models [Section titled “Its models”](#its-models) fxbot lists models.dev’s list for Bedrock, with each one’s context window, tool use, and images. Claude doesn’t serve this API on Bedrock, so it isn’t listed. Not every other model does either: each model’s card in AWS’s [Models at a glance](https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html) says which APIs it takes. ## Quirks [Section titled “Quirks”](#quirks) These come from AWS’s docs. fxbot hasn’t run Bedrock with a real key yet. * **The key expires.** A long-term key lasts as long as you picked. When it ends, chats stop with “AWS Bedrock rejected this provider’s key”. Make another, and add it with the provider’s **Replace key**. * **Ids with a region group.** Some ids start with `us.`, `eu.`, `apac.`, or `global.`. These are inference profiles, which spread requests over that group’s regions, and some models take only them. Pick one that matches your region, such as `us.` for `us-east-1`. Whether each works through Chat Completions hasn’t been checked. * **The key check needs bedrock-mantle.** AWS runs that endpoint in fewer regions than the runtime: not in `us-west-1` or `ca-central-1`, for example ([AWS’s table](https://docs.aws.amazon.com/bedrock/latest/userguide/endpoints-region-availability.html)). In a region without it, fxbot keeps the key unchecked, and a wrong key, or a misspelled region, shows at the first message. * **A model’s first use.** Bedrock turns most models on at their first use. One sold through AWS Marketplace also needs the key’s user to be allowed to subscribe, and a payment method on the account. OpenAI’s open models, and models from DeepSeek, Mistral, Qwen, and others, aren’t sold there, and need neither. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“AWS Bedrock rejected this key (HTTP 401): it’s wrong, or it was deleted.”** It may also have expired. Make another, and paste that. * **“AWS Bedrock rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** The key’s user may lack Bedrock’s permissions. A key from the console comes with AWS’s `AmazonBedrockLimitedAccess` policy, which you can check in IAM. * **The first message fails, after a key that wasn’t checked.** Check the region’s spelling, and that the key is from that region. Remove the provider, and add it again with the right one. * **“AWS Bedrock rejected this provider’s key. Replace it in Settings › Providers.”** fxbot says this when a chat gets a 401 or a 403. A 401 is an expired or deleted key: make another, and use **Replace key**. Bedrock also answers 403 when your account can’t use a model yet. Open the model once in the console’s playground, from **Model catalog**, then try again. * **A chat stops with HTTP 429.** You’ve reached Bedrock’s quota for that model. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Cerebras > Cerebras serves open models very fast, on chips of its own. Add it to fxbot with a key from its cloud console. Cerebras serves open models, such as OpenAI’s gpt-oss, very fast, on chips of its own. A free account has lower per-minute limits than a paid one. [Its pricing](https://www.cerebras.ai/pricing) says what each plan costs. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [cloud.cerebras.ai/platform](https://cloud.cerebras.ai/platform), and sign in or make an account. 2. Open **API Keys**, in the menu on the left, and choose **Generate API Key**. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Cerebras**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Cerebras first. 3. Pick a model. fxbot fills in `gpt-oss-120b` when Cerebras serves it. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Cerebras** when you leave it empty. | Cerebras’s address is `https://api.cerebras.ai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Cerebras’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. A model models.dev doesn’t know still lists, without them. ## Quirks [Section titled “Quirks”](#quirks) * **Cerebras doesn’t take the `developer` role,** the name OpenAI’s API now gives a model’s instructions, in place of `system`. If libfx, which runs fxbot’s chats, sends instructions that way, a chat fails. This is what the research for this page found: pi, another agent app, marks Cerebras so. fxbot hasn’t run Cerebras with a real key yet. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Cerebras rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached your plan’s per-minute limit, which is lower on a free account. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # ChatGPT and Codex plans > Run bots on your ChatGPT plan, as Codex does. Sign in with a code from fxbot, and your plan's own usage limits apply. Sign in with your ChatGPT plan, and bots run on the models it serves to Codex, OpenAI’s coding agent. It takes a ChatGPT Plus, Pro, Business, Enterprise, or Edu plan, and your plan’s own usage limits apply, as they do in Codex. For OpenAI’s API, billed by the token, see [OpenAI](/docs/providers/openai/). Your account, or your ChatGPT workspace, must allow device code sign-in. For your own account, turn it on in ChatGPT’s security settings. In a workspace, its admin allows it in the workspace’s permissions. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **ChatGPT and Codex**, under **Sign in**. A code shows at once. 2. Open the link on any device: scan its QR code, choose **Copy link**, or **Open auth.openai.com**. Sign in to ChatGPT, and enter the code. 3. Leave fxbot’s page open. It finishes on its own, and shows the time left. 4. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. | On the card | What it’s for | | ---------------------------- | -------------------------------------------------------- | | **The code** | What you enter on OpenAI’s page. | | **QR code** | The link, for a phone, when fxbot is open on a computer. | | **Copy code**, **Copy link** | Copy either one, to paste on another device. | | **Open auth.openai.com** | OpenAI’s page, in a new tab. | fxbot signs in through libfx, with the same OpenAI client as the Codex CLI. It keeps the plan’s tokens sealed, and libfx renews them before they end. Your ChatGPT plan and OpenAI’s terms apply to each chat. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models your plan serves to Codex, from ChatGPT’s own list, with each one’s context window, and whether it takes images. It asks as the newest Codex CLI does, so the list matches Codex’s. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“The code expired before it was entered. If OpenAI’s page said device code sign-in is off, turn it on in ChatGPT’s security settings, or ask your workspace admin.”** Do that, then choose **Start again**. * **“This sign-in expired.”** The code ran out before you entered it. Choose **Start again** for a new one. * **“OpenAI could not finish the sign-in.”** Choose **Start again**. * **A chat says “ChatGPT and Codex rejected this provider’s key.”** The sign-in no longer works. Use the provider’s **Sign in again**. * **“The provider kept refusing this, with HTTP 429, so it was stopped after 5 minutes.”** You’ve most likely reached your plan’s usage limits. They reset with time, as they do in Codex ([Providers](/docs/reference/providers/)). # Cloudflare > Cloudflare's Workers AI runs open models on Cloudflare's network, and reaches other labs' models through AI Gateway. Add it to fxbot with an API token and your account ID. Cloudflare’s Workers AI runs open models on Cloudflare’s own network, such as Llama, Qwen, and gpt-oss, and reaches other labs’ models through AI Gateway. Workers AI has a free allocation each day. Its prices past that are on its [pricing page](https://developers.cloudflare.com/workers-ai/platform/pricing/). ## Make a key [Section titled “Make a key”](#make-a-key) Cloudflare’s key is an API token. 1. Open [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens), and sign in or make an account. 2. Choose **Create Token**, then the **Workers AI** template. If it isn’t there, start from scratch, with **Workers AI** › **Read** and **Workers AI** › **Edit** on your account. 3. Choose **Continue to summary**, then **Create Token**. 4. Copy the token. Cloudflare shows it only once. 5. Copy your account ID, from your account’s home page, under **Account details**. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Cloudflare**, under **Clouds**. 2. Paste the **Account ID** and the token, and choose **Add**. fxbot checks the token with Cloudflare first. 3. Pick a model. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | -------------- | ----------------------------------------------------------------------------------------------- | | **Account ID** | Your account’s ID, from its home page, under **Account details**. | | **API key** | The token you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Cloudflare** when you leave it empty. | fxbot fills in the address from the account: `https://api.cloudflare.com/client/v4/accounts/{account}/ai/v1`. That address has no model list, so fxbot checks the token at the account’s Workers AI model search instead. To move to another account, remove the provider and add it again. ## Its models [Section titled “Its models”](#its-models) fxbot lists models.dev’s lists for Workers AI, whose ids start with `@cf/`, and for AI Gateway, whose ids start with their lab, such as `openai/`. Each comes with its context window, tool use, and images. A new model shows once models.dev lists it. ## Quirks [Section titled “Quirks”](#quirks) These come from Cloudflare’s docs. fxbot hasn’t run Cloudflare with a real token yet. * **Other labs’ models need credits.** A model from AI Gateway’s list, such as one starting `openai/`, is paid for with Cloudflare’s Unified Billing credits. Buy them in Cloudflare’s dashboard, under **AI** › **AI Gateway**: **Credits Available** › **Manage** › **Top-up credits**. Cloudflare adds a fee to each purchase. Workers AI’s own `@cf/` models don’t need them. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Cloudflare rejected this key (HTTP 400): it isn’t a key it can read.”** The token was cut short, or changed, when you copied it. Copy it again, or make another. * **“Cloudflare rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and paste that. * **“Cloudflare rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** The token may lack Workers AI’s permissions, or be for another account than the ID. Make one with the **Workers AI** template. * **“Account ID isn’t one fxbot can use.”** Paste the ID alone. * **“Cloudflare rejected this provider’s key. Replace it in Settings › Providers.”** fxbot says this when a chat gets a 401 or a 403, such as after the token was deleted or expired. Make another, and add it with the provider’s **Replace key**. * **A chat fails on another lab’s model.** The account may have no Unified Billing credits. Top them up in **AI** › **AI Gateway**, or pick a `@cf/` model. * **A chat stops with HTTP 429.** You’ve reached Cloudflare’s rate limit for that model. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # DeepInfra > DeepInfra serves open models at low prices, paid as you use them. Add it to fxbot with a key from its dashboard. DeepInfra serves open models at low prices, paid as you use them. Add a card or pay ahead before a key can run a model. [Its pricing](https://deepinfra.com/pricing) lists each model’s rate. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [deepinfra.com/dash/api_keys](https://deepinfra.com/dash/api_keys), and sign in or make an account. 2. Choose **New API Key**. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **DeepInfra**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with DeepInfra first. 3. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **DeepInfra** when you leave it empty. | DeepInfra’s address is `https://api.deepinfra.com/v1/openai`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from DeepInfra’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. fxbot looks for each by its id, then by its name without the maker in front. A model models.dev doesn’t know still lists, without them. ## Quirks [Section titled “Quirks”](#quirks) * **Many of DeepInfra’s model ids differ from models.dev’s.** When the research for this page looked, models.dev knew 55 of the 177 models DeepInfra listed. The rest list in fxbot without a context window, tool use, or images. fxbot hasn’t run DeepInfra with a real key yet. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“DeepInfra rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. * **“DeepInfra rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** The key may lack a permission, or the account may need credit. Add a card or credit in DeepInfra’s billing, then choose **Add** again. * **A chat stops with HTTP 429.** You’ve reached your account’s rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # DeepSeek > DeepSeek serves its own models from its own API. You top up a balance before a key can run one. Add it to fxbot with a key from its platform. DeepSeek makes its own models, and serves them from its own API. You pay as you go, from a balance you top up before a key can run a model. Its prices are on its [pricing page](https://api-docs.deepseek.com/quick_start/pricing). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys), and sign in or make an account. 2. Top up your balance, at [platform.deepseek.com/top_up](https://platform.deepseek.com/top_up). Without one, the key can’t run a model. 3. Choose **Create new API key**. 4. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **DeepSeek**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with DeepSeek first. 3. Pick a model from DeepSeek’s list. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **DeepSeek** when you leave it empty. | DeepSeek’s address is `https://api.deepseek.com`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from DeepSeek’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) This comes from DeepSeek’s docs. fxbot hasn’t run DeepSeek with a real key yet. * **Reasoning goes back with tools.** When a request carries tools, DeepSeek’s docs say each earlier reply’s reasoning, its `reasoning_content`, must go back to the API in full, or the API answers 400. fxbot’s bots have tools, so this applies to every chat. Whether libfx, the agent inside fxbot, sends it back hasn’t been checked. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“DeepSeek rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Check that you copied all of it, or make another and paste that. * **“DeepSeek rejected this provider’s key. Replace it in Settings › Providers.”** The key stopped working, such as after it was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat fails with HTTP 402.** DeepSeek’s docs say this means your balance ran out. Top it up, and send the message again. * **A chat fails with HTTP 400 after a tool call.** It may be the reasoning in **Quirks**. Move the bot to another provider for now, in its **Edit** page, under **Provider**. * **A chat stops with HTTP 429.** You’re sending more than DeepSeek’s rate limit allows. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Fireworks AI > Fireworks AI serves open models fast, and charges by the token. Add it to fxbot with a key from its settings. Fireworks AI serves open models fast, and charges by the token. [Its pricing](https://docs.fireworks.ai/serverless/pricing) lists each model’s rate. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [app.fireworks.ai/settings/users/api-keys](https://app.fireworks.ai/settings/users/api-keys), and sign in or make an account. 2. Choose **Create API Key**. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Fireworks AI**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Fireworks first. 3. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Fireworks AI** when you leave it empty. | Fireworks’s address is `https://api.fireworks.ai/inference/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Fireworks’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. A model models.dev doesn’t know still lists, without them. Fireworks names its models with a path: `accounts/fireworks/models/`, then the model’s name. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Fireworks AI rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached your account’s rate limit, which Fireworks raises as you spend more. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Google Gemini > Google's Gemini API serves the Gemini models, with a free tier. Add it to fxbot with a key from Google AI Studio. Google’s Gemini API serves Google’s Gemini models, with a key from Google AI Studio. Its free tier has lower limits than its paid one, which needs billing set up on the key’s Google Cloud project. Its prices are on its [pricing page](https://ai.google.dev/gemini-api/docs/pricing). To run Gemini in your own Google Cloud project instead, use [Vertex AI](/docs/providers/vertex/). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [aistudio.google.com/apikey](https://aistudio.google.com/apikey), and sign in with a Google account. 2. Choose **Create API key**, and pick or make a Google Cloud project for it. A new AI Studio account gets a project made for it. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Google Gemini**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Google first. 3. Pick a model. fxbot fills in `gemini-flash-latest` when Gemini serves it. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Google Gemini** when you leave it empty. | Gemini’s address is `https://generativelanguage.googleapis.com/v1beta/openai`, Google’s OpenAI compatibility, which Google calls beta. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Gemini’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from Google’s docs, and from how its model list answers. fxbot hasn’t run Gemini with a real key yet. * **A bad key gets 400.** Gemini answers a key it can’t read with 400, not 401. So when you add a key, fxbot counts a 400 as a refusal too. * **Thought signatures.** Gemini 3 and newer fail a tool call on the next turn unless each call’s thought signature comes back with it. Whether libfx, the agent inside fxbot, sends them back hasn’t been checked. If a bot fails right after its first tool call, try a Gemini 2.5 model. * **Unrestricted keys are refused.** The Gemini API rejects a standard key with no restrictions. Keys AI Studio makes now are restricted to the Gemini API from the start. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Google Gemini rejected this key (HTTP 400): it isn’t a key it can read.”** The key is wrong, or was cut short when you copied it. Copy it again, or make another. * **A key that worked stops.** Google blocks standard keys with no restrictions, including ones left unused for a long time. In AI Studio’s **API Keys**, find it marked **Unrestricted**, and choose **Add restrictions**, **Restrict to Gemini API only**, then **Restrict key**. Or make a new key, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 400 from Gemini.** fxbot names a refused key itself only for a 401 or a 403, so a key Gemini stops taking shows as Gemini’s own 400. Make another, and use **Replace key**. * **A chat stops with HTTP 429.** You’ve reached your tier’s rate limit, which is lowest on the free tier. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Grok plans > Run bots on your SuperGrok or X Premium plan. Sign in with a code from fxbot, and your plan's own usage limits apply. Sign in with your SuperGrok or X Premium plan, and bots run on the Grok models it serves. Your plan’s own usage limits apply. For xAI’s API, billed by the token, see [xAI](/docs/providers/xai/). ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Grok**, under **Sign in**. A code shows at once. 2. Open the link on any device: scan its QR code, choose **Copy link**, or follow the **Open** link beside the code. Sign in with the account that has your plan, and enter the code. 3. Leave fxbot’s page open. It finishes on its own, and shows the time left. 4. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. | On the card | What it’s for | | ---------------------------- | -------------------------------------------------------- | | **The code** | What you enter on xAI’s page. | | **QR code** | The link, for a phone, when fxbot is open on a computer. | | **Copy code**, **Copy link** | Copy either one, to paste on another device. | | **Open** | xAI’s page, in a new tab. | fxbot signs in through libfx, with the same xAI client as the fx CLI. It keeps the plan’s tokens sealed, and libfx renews them before they end, checking they still belong to the same xAI account. Your Grok plan and xAI’s terms apply to each chat. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models your plan serves, from Grok’s own list, with each one’s context window and output limit. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“This sign-in expired.”** The code ran out before you entered it. Choose **Start again** for a new one. * **“The sign-in was declined on xAI’s page.”** Choose **Start again**, and approve it this time. * **“xAI could not finish the sign-in.”** Choose **Start again**. * **A chat says “Grok rejected this provider’s key.”** The sign-in no longer works. Use the provider’s **Sign in again**. * **“The provider kept refusing this, with HTTP 429, so it was stopped after 5 minutes.”** You’ve most likely reached your plan’s usage limits, which reset with time ([Providers](/docs/reference/providers/)). # Groq > Groq serves open models very fast, on chips of its own. Its free plan needs no card. Add it to fxbot with a key from its console. Groq serves open models, such as OpenAI’s gpt-oss and Qwen, very fast, on chips of its own. Its free plan needs no card, and has lower rate limits than its paid one. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [console.groq.com/keys](https://console.groq.com/keys), and sign in or make an account. 2. Choose **Create API Key**, and give it a name, such as fxbot. 3. Copy the key. Groq shows it only once. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Groq**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Groq first. 3. Pick a model. fxbot fills in `openai/gpt-oss-120b` when Groq serves it. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Groq** when you leave it empty. | Groq’s address is `https://api.groq.com/openai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Groq’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Groq rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached your plan’s rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Hugging Face > Hugging Face's router reaches open models from many inference providers with one account. Add it to fxbot with a fine-grained token, or sign in. Hugging Face’s router reaches open models from many inference providers, such as Groq, Together, and Cerebras, with one Hugging Face account. It’s pay as you go, at each provider’s own rates. A free account buys credits first, and PRO accounts and Team or Enterprise organizations get a small credit each month ([pricing](https://huggingface.co/docs/inference-providers/pricing)). ## Sign in [Section titled “Sign in”](#sign-in) **Hugging Face** signs in through fxbot’s own app there, which fxbot’s list of providers names. A server that sets [`FXBOT_HF_CLIENT_ID`](/docs/reference/configuration/) uses its own app instead. Or [use a token](#make-a-token). 1. In **Settings** › **Providers**, choose **Add provider**, then **Hugging Face**, under **Sign in**. 2. Choose **Sign in with Hugging Face**. A code shows. 3. Open the link on any device: scan its QR code, choose **Copy link**, or follow the **Open** link beside the code. Sign in to Hugging Face, and enter the code. 4. Leave fxbot’s page open. It finishes on its own, and shows the time left. 5. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. fxbot keeps the sign-in’s tokens sealed, and renews them before they end. ## Make a token [Section titled “Make a token”](#make-a-token) 1. Open [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens), and sign in or make an account. 2. Choose **Create new token**, then **Fine-grained**. 3. Tick **Make calls to Inference Providers**, give the token a name, such as fxbot, and create it. 4. Copy the token. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Hugging Face**, under **Use a key**. 2. Paste the token, and choose **Add**. fxbot checks it with Hugging Face first. 3. Pick a model, and choose **Done**. | Field | What to put there | | ----------- | ----------------------------------------------------------------------------------------------- | | **API key** | The token you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Hugging Face** when you leave it empty. | Hugging Face’s router is at `https://router.huggingface.co/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from the router’s own list, with each one’s context window, tool use, and images, as the providers behind it report them. For each request, the router picks the fastest provider that serves the model. ## Quirks [Section titled “Quirks”](#quirks) * **The token check doesn’t see its permissions.** fxbot checks a pasted token at Hugging Face’s `https://huggingface.co/api/whoami-v2`, which answers any working token. So a token without **Make calls to Inference Providers** is added, and refused at the first message. This wasn’t checked with a real token. * **A model’s context window is its largest provider’s.** A model in the router’s list can have several providers, and fxbot shows the largest context window among them. The provider the router picks may take less. This wasn’t checked with a real token. * **A sign-in’s renewal hasn’t been tried with a real account.** Hugging Face doesn’t say how long its tokens last. ## When it fails [Section titled “When it fails”](#when-it-fails) * **No Hugging Face under Sign in.** fxbot has no Hugging Face app yet. Use a token. * **“Hugging Face rejected this key (HTTP 401): it’s wrong, or it was deleted.”** The token is wrong, or it was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat says “Hugging Face rejected this provider’s key.”** The token lacks **Make calls to Inference Providers**, or it was deleted. Make one with it, and add it with **Replace key**. * **“This sign-in expired.”** The code ran out before you entered it. Choose **Start again** for a new one. * **“Hugging Face did not renew the sign-in.”** Choose the provider’s **Replace key**, then **Sign in with Hugging Face**. * **A chat stops with HTTP 429.** You’ve reached a rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Kimi > Moonshot AI makes the Kimi models, and serves them from its own API, on a global platform and a China one. Add credit, then add it to fxbot with a key. Moonshot AI makes the Kimi models, and serves them from its own API. It has two platforms, a global one at platform.kimi.ai and a China one at platform.moonshot.cn, each with keys of its own. You add credit before a key can run a model. Its prices are on its [pricing page](https://platform.kimi.ai/docs/pricing/chat), and the rate limits your credit brings on its [limits page](https://platform.kimi.ai/docs/pricing/limits). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [platform.kimi.ai/console/api-keys](https://platform.kimi.ai/console/api-keys), and sign in or make an account. For the China platform, go to platform.moonshot.cn instead, which now opens at platform.kimi.com. 2. Add credit. Without it, the key can’t run a model. 3. Choose **Create API Key**. 4. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Kimi**, under **Use a key**. 2. Pick the **Platform** you made the key on, paste the key, and choose **Add**. fxbot checks it with Kimi first. 3. Pick a model from Kimi’s list. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Platform** | **Global (platform.kimi.ai)**, the default, or **China (platform.moonshot.cn)**: the platform you made the key on. A key works only on the platform it was made on. | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Kimi** when you leave it empty. | fxbot fills in the address from the platform: `https://api.moonshot.ai/v1` for Global, and `https://api.moonshot.cn/v1` for China. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Kimi’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from Kimi’s docs. fxbot hasn’t run Kimi with a real key yet. * **Reasoning goes back.** Kimi’s thinking models, Kimi K3 among them, reply with their reasoning in `reasoning_content`. Kimi’s docs say to keep it in every earlier reply of the conversation, and to send back a reply that called a tool whole, as it came. Whether libfx, the agent inside fxbot, does hasn’t been checked. * **A key works on one platform.** Kimi’s docs say a key from the other platform gets 401. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Kimi rejected this key (HTTP 401): it’s wrong, or it was deleted.”** The key may be from the other platform. Pick the platform you made it on, or check that you copied all of it. * **“Kimi rejected this provider’s key. Replace it in Settings › Providers.”** The key stopped working, such as after it was deleted. Make another on the same platform, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** Kimi answers 429 when your credit runs out, as well as for its rate limits. Add credit, or wait. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # LiteLLM > LiteLLM's proxy is a server you run yourself, in front of other providers, with keys of its own. Add it to fxbot at its address, with a virtual key or its master key. LiteLLM’s proxy is a server you run yourself, in front of other providers: clouds, labs, and servers on your own machine, such as Ollama or vLLM. It gives them all one OpenAI-compatible API, with keys of its own. It’s free and open source. The providers behind it bill as they do. ## Start the server [Section titled “Start the server”](#start-the-server) 1. Install it, as LiteLLM’s [quick start](https://docs.litellm.ai/docs/proxy/quick_start) says: ```sh uv tool install 'litellm[proxy]' ``` 2. Write a `config.yaml` that lists its models under `model_list`: for each one, the `model_name` fxbot will show, and under `litellm_params`, the provider’s model and key. LiteLLM’s [config](https://docs.litellm.ai/docs/proxy/configs) page shows how. 3. Start it: ```sh litellm --config config.yaml ``` It listens on port 4000, with an OpenAI-compatible API under `/v1`. Whether a model calls tools depends on the model and the provider behind it. Its keys: * **No master key:** the proxy takes requests with no key. * **A master key,** `master_key` under `general_settings` in `config.yaml`, or `LITELLM_MASTER_KEY`, starts with `sk-`. Every request then needs a key: the master key, or a virtual key. * **A virtual key** is made with the master key, at the proxy’s `/key/generate`. Virtual keys need a Postgres database of LiteLLM’s own, set with `DATABASE_URL`. One made for fxbot can be removed without touching the rest. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**. Under **On your machine**, **LiteLLM** says **Found here** when the proxy is running at its usual address with no master key. fxbot asks each server there for its model list when the page opens, without a key, and gives it half a second to answer. With a master key, the tile doesn’t say so, and the address is filled in all the same. 2. Choose **LiteLLM**. Its address is filled in. 3. Paste a virtual key, or the master key, and choose **Add**. fxbot checks it with the proxy first. 4. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Address** | The proxy’s, with its `/v1`. The usual one, `http://localhost:4000/v1`, is filled in. | | **API key, if the server needs one** | A virtual key, or the master key. Leave it empty when the proxy has no master key. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Context window** | The proxy’s list doesn’t say it. A number here applies to every model behind the proxy, so give the smallest of those you’ll use. | | **Name** | Optional. It’s **LiteLLM** when you leave it empty. | When fxbot runs from a checkout, with `npm run dev`, it runs on the machine itself, and the usual address works as it is. ### In a release install [Section titled “In a release install”](#in-a-release-install) A release install, the one `setup.sh` makes, runs fxbot in a container. There, `localhost` is the container, not your machine, so fxbot doesn’t find the proxy, and the usual address doesn’t reach it. fxbot takes an HTTPS address, or plain HTTP only on localhost. A server on the machine is plain HTTP from inside the container, which fxbot can’t use yet, and the card says so. The same goes for a server on another machine. Put the proxy behind HTTPS, and give fxbot that address. With Tailscale, and [HTTPS turned on](https://tailscale.com/kb/1153/enabling-https) for your tailnet, serve it on a port of its own, such as 8443: ```sh sudo tailscale serve --bg --https=8443 4000 ``` Then give fxbot `https://..ts.net:8443/v1` as the **Address**. fxbot’s own `tailscale serve`, on port 443, stays as it is ([Reach fxbot from other devices](/docs/how-to/reach-it/)). ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from the proxy’s own list, `/v1/models`, by their ids: each `model_name` in its config. The list gives ids only, with no context window, tool use, or images. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“The key check couldn’t reach localhost:4000.”** The proxy isn’t running there. Start it, or give the address it runs at. In a release install, that’s the container’s own localhost: see [In a release install](#in-a-release-install). * **“LiteLLM rejected this key (HTTP 401): it’s wrong, or it was deleted.”** The key isn’t one the proxy knows, or the proxy has a master key and you gave none. * **“baseUrl must use https, or http on localhost.”** The address is plain HTTP to somewhere other than `localhost` or `127.0.0.1`. Give an HTTPS address. * **A chat fails on one model, and not the others.** The provider behind that model is failing, such as with a wrong key in `config.yaml`. The proxy’s log says why. # llama.cpp > llama.cpp's llama-server runs an open model on your own machine, for free. Start it with --jinja, so the model can call tools, and add it to fxbot at its address. llama.cpp runs open models in the GGUF format on your own machine, on its CPU or its GPU. Its `llama-server` serves the model you start it with over an OpenAI-compatible API. It’s free and open source, and your own hardware does the work. ## Start the server [Section titled “Start the server”](#start-the-server) 1. Install llama.cpp, such as with `brew install llama.cpp` on a Mac or Linux, `winget install llama.cpp` on Windows, or from its [releases](https://github.com/ggml-org/llama.cpp/releases). 2. Start `llama-server` with a model, from Hugging Face with `-hf`, or from a GGUF file with `-m`: ```sh llama-server -hf / --jinja ``` * **`--jinja`** uses the model’s own chat template, which tool calls need. Newer builds turn it on by default, and giving it does no harm. Some models need `--chat-template-file` too: see llama.cpp’s [function calling](https://github.com/ggml-org/llama.cpp/blob/master/docs/function-calling.md) page. * **Port 9931** is where fxbot looks, and where newer builds listen unless told otherwise. Older ones, and llama.cpp’s container images, use 8080. * **`-c`**, or `--ctx-size`, sets the context. Without it, llama-server takes the model’s own. * **`--alias`** gives the model the id fxbot shows. Without it, the id is the model file’s path. * **`--api-key`** makes it ask for a key. Without it, it takes none. llama-server listens on `127.0.0.1` unless `--host` says otherwise. `curl http://localhost:9931/props` shows the context it runs with, as `n_ctx`. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**. Under **On your machine**, **llama.cpp** says **Found here** when llama-server is running at its usual address with no key. fxbot asks each server there for its model list when the page opens, and gives it half a second to answer. 2. Choose **llama.cpp**. Its address is filled in, with **Found running on this machine.** under it when fxbot found it. If llama-server runs on another port, change it, such as to `http://localhost:8080/v1` for an older build. 3. Leave **API key, if the server needs one** empty, unless you started it with `--api-key`. Set **Context window**, and choose **Add**. fxbot checks the server first. 4. Pick the model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Address** | llama-server’s, with its `/v1`. The usual one, `http://localhost:9931/v1`, is filled in. | | **API key, if the server needs one** | One of its `--api-key` keys, if you gave any. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Context window** | The context llama-server runs with: its `n_ctx`, or the `-c` you gave it. fxbot can’t read it from llama-server’s list. It applies to every model on this provider. | | **Name** | Optional. It’s **llama.cpp** when you leave it empty. | When fxbot runs from a checkout, with `npm run dev`, it runs on the machine itself, and the usual address works as it is. ### In a release install [Section titled “In a release install”](#in-a-release-install) A release install, the one `setup.sh` makes, runs fxbot in a container. There, `localhost` is the container, not your machine, so fxbot doesn’t find llama-server, and the usual address doesn’t reach it. fxbot takes an HTTPS address, or plain HTTP only on localhost. A server on the machine is plain HTTP from inside the container, which fxbot can’t use yet, and the card says so. The same goes for a server on another machine. Put llama-server behind HTTPS, and give fxbot that address. With Tailscale, and [HTTPS turned on](https://tailscale.com/kb/1153/enabling-https) for your tailnet, serve it on a port of its own, such as 8443: ```sh sudo tailscale serve --bg --https=8443 9931 ``` Then give fxbot `https://..ts.net:8443/v1` as the **Address**. fxbot’s own `tailscale serve`, on port 443, stays as it is ([Reach fxbot from other devices](/docs/how-to/reach-it/)). ## Its models [Section titled “Its models”](#its-models) fxbot lists the model from llama-server’s own list, `/v1/models`, by its id: the model file’s path, or its `--alias`. Newer builds say whether it reads images. The list gives no context window or tool use that fxbot reads, so set **Context window** yourself. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“The key check couldn’t reach localhost:9931.”** llama-server isn’t running there. Older builds listen on 8080: put its port in the address. In a release install, that’s the container’s own localhost: see [In a release install](#in-a-release-install). * **“llama.cpp rejected this key (HTTP 401): it’s wrong, or it was deleted.”** llama-server was started with `--api-key`, and the key you gave isn’t one of them, or you gave none. * **“baseUrl must use https, or http on localhost.”** The address is plain HTTP to somewhere other than `localhost` or `127.0.0.1`. Give an HTTPS address. * **The model writes tool calls as text, or calls none.** Start llama-server with `--jinja`. If it still doesn’t, the model may need `--chat-template-file`, as llama.cpp’s function calling page says. # LM Studio > LM Studio is an app that downloads and runs open models on your own machine, for free. Start its server in the Developer tab, and add it to fxbot at its usual address. LM Studio is an app for finding, downloading, and running open models on your own machine. It’s free, and your own hardware runs the models. Its server gives them to other apps, such as fxbot. ## Start the server [Section titled “Start the server”](#start-the-server) 1. Install LM Studio from [lmstudio.ai](https://lmstudio.ai), and download a model in it. Models with native tool use carry a hammer badge. A bot works best with one of them. 2. Load the model with the context length you want, in the app, or with `lms load`: ```sh lms load --context-length 32768 ``` 3. In the **Developer** tab, turn on **Start server**. Or run `lms server start`. 4. Leave **Require Authentication for each request**, in the **Developer** tab’s **Server Settings**, off. fxbot sends LM Studio no key. LM Studio serves an OpenAI-compatible API under `/v1`. fxbot looks for it on port 1234, the one LM Studio’s own examples use. fxbot also reads LM Studio’s own model list, at `/api/v1/models`, which came with LM Studio 0.4.0. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**. Under **On your machine**, **LM Studio** says **Found here** when its server is running at its usual address. fxbot asks each server there for its model list when the page opens, and gives it half a second to answer. 2. Choose **LM Studio**. Its address is filled in, with **Found running on this machine.** under it when fxbot found it. 3. Choose **Add**. fxbot reads LM Studio’s model list first, to check it’s there. 4. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Address** | LM Studio’s, with its `/v1`. The usual one, `http://localhost:1234/v1`, is filled in. | | **Context window** | Optional. LM Studio says the context each loaded model runs with, so leave it empty unless that’s wrong. A number here overrides what LM Studio reports, for every model on this provider. | | **Name** | Optional. It’s **LM Studio** when you leave it empty. | There’s no key to give: fxbot sends LM Studio none. When fxbot runs from a checkout, with `npm run dev`, it runs on the machine itself, and the usual address works as it is. ### In a release install [Section titled “In a release install”](#in-a-release-install) A release install, the one `setup.sh` makes, runs fxbot in a container. There, `localhost` is the container, not your machine, so fxbot doesn’t find LM Studio, and the usual address doesn’t reach it. fxbot takes an HTTPS address, or plain HTTP only on localhost. A server on the machine is plain HTTP from inside the container, which fxbot can’t use yet, and the card says so. The same goes for a server on another machine. Put LM Studio’s server behind HTTPS, and give fxbot that address. With Tailscale, and [HTTPS turned on](https://tailscale.com/kb/1153/enabling-https) for your tailnet, serve it on a port of its own, such as 8443: ```sh sudo tailscale serve --bg --https=8443 1234 ``` Then give fxbot `https://..ts.net:8443/v1` as the **Address**. fxbot’s own `tailscale serve`, on port 443, stays as it is ([Reach fxbot from other devices](/docs/how-to/reach-it/)). ## Its models [Section titled “Its models”](#its-models) fxbot lists the language models from LM Studio’s own list, by each one’s key, with LM Studio’s name for it. LM Studio says whether each was trained for tool use, whether it reads images, and its context: the context it’s loaded with, or the most it takes when it isn’t loaded. Embedding models are left out. A model that isn’t loaded when fxbot reads the list shows the most it takes, which may be more than LM Studio loads it with. Load it first, or set **Context window**. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“LM Studio’s model list couldn’t reach localhost:1234.”** Its server isn’t on. Turn on **Start server** in the **Developer** tab, or give the port it runs on. In a release install, that’s the container’s own localhost: see [In a release install](#in-a-release-install). * **“LM Studio rejected this key”**, though you gave none. **Require Authentication for each request** is on, and fxbot sends LM Studio no key. Turn it off. * **The model list fails, or is empty.** An LM Studio older than 0.4.0 doesn’t have the list fxbot reads: update it. Or no language model is downloaded yet. * **“baseUrl must use https, or http on localhost.”** The address is plain HTTP to somewhere other than `localhost` or `127.0.0.1`. Give an HTTPS address. # MiniMax > MiniMax makes its own models, and serves them from its own API. Add credit, then add it to fxbot with a key from its platform. MiniMax makes its own models, and serves them from its own API. You pay as you go, from credit you add before a key can run a model. Its prices are on its [pricing page](https://platform.minimax.io/docs/pricing/overview). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [platform.minimax.io/console/keys](https://platform.minimax.io/console/keys), and sign in or make an account. 2. Add credit to your balance. Without it, the key can’t run a model. 3. Choose **Create new secret key**. 4. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **MiniMax**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with MiniMax first. 3. Pick a model from MiniMax’s list. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **MiniMax** when you leave it empty. | MiniMax’s address is `https://api.minimax.io/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from MiniMax’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from MiniMax’s docs. fxbot hasn’t run MiniMax with a real key yet. * **The whole reply goes back.** In a run of tool calls, MiniMax’s docs say each reply must go back to the model whole, its reasoning and tool calls too, and call this essential to the model’s best results. Whether libfx, the agent inside fxbot, sends the reasoning back hasn’t been checked. * **Its international API only.** fxbot offers MiniMax’s international API, at `api.minimax.io`, and not its China one. Make the key on platform.minimax.io. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“MiniMax rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Check that you copied all of it, or make another and paste that. * **“MiniMax rejected this provider’s key. Replace it in Settings › Providers.”** The key stopped working, such as after it was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat fails once your credit runs out.** MiniMax’s docs call this “insufficient balance”, with the code 1008. Add credit, and send the message again. # Mistral > Mistral makes models of its own, and serves them from La Plateforme. Add it to fxbot with a key from Mistral's console. Mistral makes models of its own, and serves them from La Plateforme, which its console now calls Studio. A key works once your workspace has a plan. [Mistral’s pricing](https://mistral.ai/pricing) lists them. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [console.mistral.ai/api-keys](https://console.mistral.ai/api-keys), and sign in or make an account. 2. Pick a plan for your workspace, if it has none. 3. Choose **Create new key**. Give it a name, such as fxbot, and a date for it to expire. 4. Copy the key. Mistral shows it only once. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Mistral**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Mistral first. 3. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Mistral** when you leave it empty. | Mistral’s address is `https://api.mistral.ai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Mistral’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. A model models.dev doesn’t know still lists, without them. ## Quirks [Section titled “Quirks”](#quirks) * **Mistral refuses a request with any field it doesn’t know, with HTTP 422.** libfx, which runs fxbot’s chats, asks for token counts with a field called `stream_options`. If Mistral doesn’t take it, every chat fails with 422. This is what the research for this page found, in Mistral’s API and in libfx’s package. fxbot hasn’t run Mistral with a real key yet. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Mistral rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. * **“Mistral rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** The key may lack a permission, or the account may need credit. Check that its workspace has a plan. * **“Mistral rejected this provider’s key. Replace it in Settings › Providers.”** The key worked when you added it, and stopped. It was deleted, or it reached the date you set for it to expire. Make another, and use **Replace key**. * **A chat fails with HTTP 422.** Mistral refused a field in the request, as **Quirks** describes. Put the bot on another provider until fxbot handles it. * **A chat stops with HTTP 429.** You’ve reached your plan’s rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Nous Portal > Nous Portal is Nous Research's account for Hermes Agent, with models from many labs behind one API. Add it to fxbot with a key from the portal. Nous Portal is Nous Research’s account for Hermes Agent, with models from many labs behind one API. Its Free plan has free models only, and no credit. An API key always spends your credits, pay as you go, rather than a plan’s included usage ([Nous Portal](https://portal.nousresearch.com)). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [portal.nousresearch.com/api-keys](https://portal.nousresearch.com/api-keys), and sign in or make an account. 2. Choose **Create API Key**. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Nous Portal**, under **Use a key**. 2. Paste the key, and choose **Add**. 3. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Nous Portal** when you leave it empty. | Nous Portal’s address is `https://inference-api.nousresearch.com/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Nous Portal’s own list, with each one’s context window, tool use, and images, as the list gives them. ## Quirks [Section titled “Quirks”](#quirks) * **fxbot can’t check the key when you add it.** Nous Portal’s model list answers any key, so a wrong one is added, and shows at the first message. The card says so. * **There’s no sign-in yet.** Nous Portal signs Hermes Agent in with a device code, but only for apps Nous has given a client id. fxbot doesn’t have one yet, so it takes a key. ## When it fails [Section titled “When it fails”](#when-it-fails) * **The first message says “Nous Portal rejected this provider’s key. Replace it in Settings › Providers.”** The key is wrong, or it was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached a rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # NVIDIA > NVIDIA serves open models from many makers at build.nvidia.com, free for development. Add it to fxbot with a key from there. NVIDIA serves open models from many makers at build.nvidia.com. It’s free for development. Signing up makes you a member of NVIDIA’s Developer Program. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys), and sign in or make an account. 2. Choose **Generate API Key**. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **NVIDIA**, under **Use a key**. 2. Paste the key, and choose **Add**. NVIDIA’s model list answers any key, so fxbot can’t check yours here, and the card says so. A wrong key shows at the first message. 3. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. 4. Send a bot on NVIDIA a short message, to find out that the key works. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **NVIDIA** when you leave it empty. | NVIDIA’s address is `https://integrate.api.nvidia.com/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from NVIDIA’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. fxbot looks for each by its id, then by its name without the maker in front. A model models.dev doesn’t know still lists, without them. When the research for this page looked, models.dev knew 25 of the 84 models NVIDIA listed. ## Quirks [Section titled “Quirks”](#quirks) * **NVIDIA’s model list answers any key,** a made-up one or none at all, so it can’t tell fxbot whether yours is right. The first message is the first check. * **NVIDIA doesn’t take the `developer` role,** the name OpenAI’s API now gives a model’s instructions, in place of `system`. If libfx, which runs fxbot’s chats, sends instructions that way, a chat fails. pi, another agent app, marks NVIDIA so. This is what the research for this page found. fxbot hasn’t run NVIDIA with a real key yet. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“NVIDIA rejected this provider’s key. Replace it in Settings › Providers.”** The key is wrong, or it was deleted. fxbot couldn’t check it when you added it, so this is where a wrong key shows. Make another, and use the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached NVIDIA’s rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Ollama > Ollama runs open models on your own machine, for free. Add it to fxbot at its usual address, and set its context window when Ollama runs a shorter one than its models'. Ollama runs open models, such as Qwen and Gemma, on your own machine. It’s free, and your own hardware does the work: how much memory your GPU has decides how big a model, and how long a context, runs well. ## Start the server [Section titled “Start the server”](#start-the-server) 1. Install Ollama from [ollama.com/download](https://ollama.com/download). Its app, or its service on Linux, runs the server. Without either, run `ollama serve`. 2. Pull a model, such as `ollama pull qwen3`. fxbot’s model list says which models can use tools. A bot works best with one that can. 3. Give it room. Ollama picks its context by your GPU’s memory: 4k tokens under 24 GiB, 32k up to 48 GiB, and 256k above. Ollama’s docs suggest at least 64000 for agents. Set it with the context length slider in the Ollama app’s settings, or start the server with `OLLAMA_CONTEXT_LENGTH`: ```sh OLLAMA_CONTEXT_LENGTH=64000 ollama serve ``` `ollama ps` shows the context each loaded model runs with, under `CONTEXT`. Ollama serves an OpenAI-compatible API under `/v1`, on port 11434, with nothing to turn on. It takes no key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**. Under **On your machine**, **Ollama** says **Found here** when it’s running at its usual address. fxbot asks each server there for its model list when the page opens, and gives it half a second to answer. 2. Choose **Ollama**. Its address is filled in, with **Found running on this machine.** under it when fxbot found it. 3. Set **Context window** if Ollama runs a shorter context than its models’, and choose **Add**. fxbot reads Ollama’s model list first, to check it’s there. 4. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Address** | Ollama’s, with its `/v1`. The usual one, `http://localhost:11434/v1`, is filled in. | | **Context window** | Optional. The context Ollama runs with, from `ollama ps`, when it’s shorter than the models’ own. It overrides what Ollama reports, for every model on this provider. | | **Name** | Optional. It’s **Ollama** when you leave it empty. | There’s no key to give: Ollama takes none. When fxbot runs from a checkout, with `npm run dev`, it runs on the machine itself, and the usual address works as it is. ### In a release install [Section titled “In a release install”](#in-a-release-install) A release install, the one `setup.sh` makes, runs fxbot in a container. There, `localhost` is the container, not your machine, so fxbot doesn’t find Ollama, and the usual address doesn’t reach it. fxbot takes an HTTPS address, or plain HTTP only on localhost. A server on the machine is plain HTTP from inside the container, which fxbot can’t use yet, and the card says so. The same goes for a server on another machine. Put Ollama behind HTTPS, and give fxbot that address. With Tailscale, and [HTTPS turned on](https://tailscale.com/kb/1153/enabling-https) for your tailnet: 1. Have Ollama listen on every address, with `OLLAMA_HOST=0.0.0.0:11434`. [Ollama’s FAQ](https://docs.ollama.com/faq) says how to set it on each system. While Ollama listens only on localhost, it turns away a request that comes by another name, as one through `tailscale serve` does. Other devices on your network then reach Ollama too. 2. Serve it on a port of its own, such as 8443: ```sh sudo tailscale serve --bg --https=8443 11434 ``` 3. Give fxbot `https://..ts.net:8443/v1` as the **Address**. fxbot’s own `tailscale serve`, on port 443, stays as it is ([Reach fxbot from other devices](/docs/how-to/reach-it/)). ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Ollama’s own list, `/api/tags`, by the names `ollama ls` shows, such as `qwen3:latest`. For each one, it asks Ollama’s `/api/show` whether the model uses tools and reads images, and how long its context is. It leaves out models that can’t chat, such as embedding models. That context is the model’s own, not the one Ollama runs it with. Set **Context window** when Ollama’s is shorter. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Ollama’s model list couldn’t reach localhost:11434.”** Ollama isn’t running there. Start it, or give the address it runs at. In a release install, that’s the container’s own localhost: see [In a release install](#in-a-release-install). * **“Ollama rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** Ollama takes no key. It turned away the name fxbot came by, such as through `tailscale serve`, because it listens only on localhost. Set `OLLAMA_HOST=0.0.0.0:11434`. * **“baseUrl must use https, or http on localhost.”** The address is plain HTTP to somewhere other than `localhost` or `127.0.0.1`. Give an HTTPS address. * **The model list is empty.** Pull a model first. * **A bot loses track in a long chat.** Ollama may run a shorter context than fxbot knows. Set **Context window** to what `ollama ps` shows, or raise Ollama’s. # OpenAI > OpenAI makes the GPT models, and serves them from its own API. Add credit, then add it to fxbot with a key from its platform. OpenAI makes the GPT models, and serves them from its own API. You add credit before a key can run a model. Its prices are on its [pricing page](https://openai.com/api/pricing/). If you pay for ChatGPT, [ChatGPT and Codex](/docs/providers/chatgpt/) signs in with your plan instead, with no key. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [platform.openai.com/api-keys](https://platform.openai.com/api-keys), and sign in or make an account. 2. Add credit under **Billing** first, or the key can’t run a model. 3. Choose **Create new secret key**, and give it a name, such as fxbot. 4. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **OpenAI**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with OpenAI first. 3. Pick a model. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **OpenAI** when you leave it empty. | OpenAI’s address is `https://api.openai.com/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists models.dev’s list for OpenAI, rather than OpenAI’s own, with each one’s context window, tool use, and images. ## Quirks [Section titled “Quirks”](#quirks) This comes from OpenAI’s docs. * **Chat Completions only.** fxbot talks to OpenAI through Chat Completions. A model OpenAI serves only through its Responses API, such as GPT-5 Pro, is in the list, but fails in a chat. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“OpenAI rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and paste that. * **“OpenAI rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** Check the key’s permissions, and your credit under **Billing**. * **“OpenAI rejected this provider’s key. Replace it in Settings › Providers.”** fxbot says this when a chat gets a 401 or a 403, such as after the key was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached a rate limit, or run out of credit, which OpenAI also answers with 429. Add credit if it’s that. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # OpenCode Zen and Go > OpenCode Zen and OpenCode Go serve models the OpenCode team picked and tested for coding agents. Zen is pay as you go, and Go is a monthly plan. Add either with a key. OpenCode Zen and OpenCode Go are the OpenCode team’s gateways, with models it picked and tested for coding agents. Zen is pay as you go, from credits you add. OpenCode’s docs now call it the OpenCode Console. Go is a monthly plan for open models, as Go, Go Plus, or Go Teams, with usage limits for each model. See [Zen’s](https://opencode.ai/docs/zen/) and [Go’s](https://opencode.ai/docs/go/) pages for prices. Each is a provider of its own in fxbot, with its own card. ## Make a key [Section titled “Make a key”](#make-a-key) For Zen: 1. Open [opencode.ai/console](https://opencode.ai/console). Sign in, and open **API Keys**. 2. Choose **Create API Key**. 3. Copy the key. For Go: 1. Open [opencode.ai/console](https://opencode.ai/console). Sign in, and subscribe to **Go**. 2. Open **API Keys**, and choose **Create API Key**. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **OpenCode Zen** or **OpenCode Go**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with OpenCode first. 3. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **OpenCode Zen** or **OpenCode Go** when you leave it empty. | Zen’s address is `https://opencode.ai/inference/openai/v1`, and Go’s is `https://opencode.ai/inference/go/openai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists each one’s models from [models.dev](https://models.dev)’s copy of its list, with each one’s context window, tool use, and images. It lists only the models models.dev says speak OpenAI’s API. A model too new for the list can still be used: type its id in the model’s search, and choose **Use this id**. ## Quirks [Section titled “Quirks”](#quirks) * **Zen’s free models work only in OpenCode.** OpenCode’s docs say: “Free-tier chat models require OpenCode; use paid models or Go from other clients.” From fxbot, pick a paid model, or use Go. This wasn’t checked with a real key. * **Each chat is a session of its own.** fxbot sends each chat’s session to OpenCode in its `x-opencode-session` header, which Go requires. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“OpenCode Zen rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. Go’s says **OpenCode Go**. * **A chat on Go is refused after heavy use.** Go’s limits are a dollar amount for each model, over 5 hours, a week, and a month. Wait for them to reset, or turn on **Extra Usage** on the **Go** page of OpenCode’s console, which goes on with your pay-as-you-go balance. * **A chat stops with HTTP 429.** You’ve reached a rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # OpenRouter > OpenRouter reaches hundreds of models from many labs with one account. Sign in from fxbot, and OpenRouter makes the key, or paste one of your own. OpenRouter reaches hundreds of models from many labs with one account. Some models are free, up to a number of requests a day that rises once you’ve bought credits. The rest are paid from credits you add ([OpenRouter’s FAQ](https://openrouter.ai/docs/faq)). ## Sign in [Section titled “Sign in”](#sign-in) 1. In **Settings** › **Providers**, choose **Add provider**, then **OpenRouter**, under **Sign in**. 2. Choose **Sign in with OpenRouter**, then **Continue to OpenRouter**. OpenRouter opens in a new tab. 3. Sign in to OpenRouter, and approve fxbot. The tab comes back to fxbot itself: to the model step in first-run setup, or to **Settings** › **Providers**, with OpenRouter added. The page you started from finishes on its own too. 4. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. OpenRouter can come back only to an fxbot whose address is HTTPS, such as a tailnet name, or on localhost. On a plain-HTTP address, such as `http://192.168.1.20:8787`, or after **Didn’t come back? Use a code instead**, the card asks for a code: 1. Choose **Open OpenRouter’s sign-in**, and approve fxbot. 2. Copy the code OpenRouter shows, and paste it into fxbot. 3. Choose **Finish**. Either way, OpenRouter makes a key on your account, and fxbot keeps it sealed. A sign-in has 10 minutes, and the card shows the time left. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys), and sign in or make an account. 2. Choose **Create API Key**, and give it a name, such as fxbot. A credit limit on the key is optional. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **OpenRouter**, under **Use a key**. 2. Under **Or use a key**, paste the key, and choose **Add**. fxbot checks it at `https://openrouter.ai/api/v1/key`, since OpenRouter’s model list answers anyone. 3. Pick a model, and choose **Done**. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **OpenRouter** when you leave it empty. | OpenRouter’s address is `https://openrouter.ai/api/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists OpenRouter’s models from [models.dev](https://models.dev)’s copy of its list, with each one’s context window, tool use, and images. fxbot reads models.dev once a day, so a model OpenRouter added today may not show yet. Type its id in the model’s search, and choose **Use this id**. ## Quirks [Section titled “Quirks”](#quirks) * **fxbot shows among OpenRouter’s apps.** Its requests carry OpenRouter’s attribution headers, `HTTP-Referer: https://fxbot.sh` and `X-OpenRouter-Title: fxbot`, which OpenRouter uses to rank apps on openrouter.ai. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“OpenRouter rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**, which can also sign in again. * **“OpenRouter did not give a key for that code.”** The code was mistyped, already used, or older than 10 minutes. Choose **Start again**. * **“The sign-in took too long. Start again.”** 10 minutes passed. Choose **Start again**. * **The new tab never comes back to fxbot.** Choose **Didn’t come back? Use a code instead**, and paste the code OpenRouter shows. * **A chat says “OpenRouter rejected this provider’s key.”** The key was deleted on OpenRouter. Use the provider’s **Replace key** to sign in again, or to paste a new key. * **A chat stops with HTTP 429.** You’ve reached a rate limit, such as the daily one on free models. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # OrcaRouter > OrcaRouter reaches models from many labs with one account, on a free plan that needs no card. Sign in from fxbot, or paste a key from its dashboard. OrcaRouter reaches models from many labs, such as OpenAI, Anthropic, Google, and DeepSeek, with one account. Its Hacker plan is free and needs no card, and tokens cost what each provider charges. Its model list has a few free models too ([pricing](https://www.orcarouter.ai/pricing)). ## Sign in [Section titled “Sign in”](#sign-in) 1. In **Settings** › **Providers**, choose **Add provider**, then **OrcaRouter**, under **Sign in**. 2. Choose **Sign in with OrcaRouter**. A code shows. 3. Open the link on any device: scan its QR code, choose **Copy link**, or **Open [www.orcarouter.ai](http://www.orcarouter.ai)**. Sign in to OrcaRouter, check that it names fxbot, and approve. 4. Leave fxbot’s page open. It finishes on its own, and shows the time left. 5. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. OrcaRouter makes a key on your account that doesn’t expire, and fxbot keeps it sealed. Nothing needs registering with OrcaRouter first. You can see the key, and revoke it, under **Authorized Apps** in your OrcaRouter account. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [orcarouter.ai/console](https://www.orcarouter.ai/console), and sign in or make an account. 2. Open **API keys** in the dashboard, and create one. A credit limit and an expiry are optional. 3. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **OrcaRouter**, under **Use a key**. 2. Under **Or use a key**, paste the key, and choose **Add**. fxbot checks it with OrcaRouter first. 3. Pick a model, and choose **Done**. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **OrcaRouter** when you leave it empty. | OrcaRouter’s address is `https://api.orcarouter.ai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from OrcaRouter’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) * **Each sign-in makes a new key.** By OrcaRouter’s docs, it makes at most 10 a day for each person, and emails you about each one. Signing in again, from the provider’s **Replace key**, counts too. This wasn’t checked with a real account. * **Approving takes the Developer role,** or higher, in your OrcaRouter workspace. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“The sign-in was declined at OrcaRouter.”** You declined it, or you’ve reached the 10 keys a day, or your workspace’s limit on keys. Revoke an old one under **Authorized Apps**, or paste a key instead. * **“This sign-in expired.”** The code ran out before you entered it. Choose **Start again** for a new one. * **“OrcaRouter rejected this key (HTTP 401): it’s wrong, or it was deleted.”** The key is wrong, it was revoked, or it expired. Make another, and add it with the provider’s **Replace key**, which can also sign in again. * **A chat stops with HTTP 429.** You’ve reached a rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Qwen > Alibaba Cloud Model Studio serves the Qwen models. A key works only in the region it was made in. Add it to fxbot with a key from its console. Qwen is Alibaba’s family of models, served by Alibaba Cloud Model Studio. Model Studio gives new accounts a [free quota](https://www.alibabacloud.com/help/en/model-studio/new-free-quota) for each of many models, in its Singapore region only, for 90 days. After that you pay as you go, at the prices on its [pricing page](https://www.alibabacloud.com/help/en/model-studio/model-pricing). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [Model Studio’s API Key page](https://modelstudio.console.alibabacloud.com/?tab=dashboard#/api-key), and sign in or make an Alibaba Cloud account. 2. Check the region at the top of the console: Singapore or China (Beijing). It must match the **Region** you pick in fxbot. 3. Choose **Create API Key**. The default **Workspace** and **All** permissions are fine. Choose **OK**. 4. Copy the key. Model Studio shows it only once. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Qwen**, under **Use a key**. 2. Pick the **Region** you made the key in, paste the key, and choose **Add**. fxbot checks it with Model Studio first. 3. Pick a model from that region’s list. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Region** | **International (Singapore)**, the default, or **China (Beijing)**: the region you made the key in. A key works only in the region it was made in. | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Qwen** when you leave it empty. | fxbot fills in the address from the region: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` for International, and `https://dashscope.aliyuncs.com/compatible-mode/v1` for China. ## Its models [Section titled “Its models”](#its-models) Each region has its own models. fxbot lists the ones from that region’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from Alibaba’s docs. fxbot hasn’t run Qwen with a real key yet. * **A key works in one region.** Alibaba’s docs say a key is bound to the region it was made in, and another region’s address answers it with 401. * **Two of its regions.** fxbot offers International (Singapore) and China (Beijing). A key from another of Model Studio’s regions, such as US (Virginia), doesn’t work here. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Qwen rejected this key (HTTP 401): it’s wrong, or it was deleted.”** The key may be from another region. Pick the region you made it in, or make a key in the region you picked. * **“Qwen rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** Alibaba’s docs give 403 for an account with an overdue payment. Check your billing in the Alibaba Cloud console. * **“Qwen rejected this provider’s key. Replace it in Settings › Providers.”** A chat got a 401: the key stopped working, such as after it was deleted. Make a key in the same region, and add it with the provider’s **Replace key**. * **“Qwen refused this provider’s key (HTTP 403): it may lack a permission, or the account may need credit or be over its quota.”** Alibaba’s docs give 403 when a model’s free quota is used up, or a payment is overdue, so check those in Model Studio first. * **A chat stops with HTTP 429.** You’ve reached one of Model Studio’s rate limits or quotas. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Together AI > Together AI serves open models from many labs, paid for with credit you buy first. Add it to fxbot with a key from one of your projects. Together AI serves open models from many labs. It has no free trial: you buy credit first, and a key can’t run a model without it. [Its pricing](https://www.together.ai/pricing) lists each model’s rate, and [its billing docs](https://docs.together.ai/docs/billing) say the smallest first purchase. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [api.together.ai/settings/projects/\~current/api-keys](https://api.together.ai/settings/projects/~current/api-keys), and sign in or make an account. It opens the keys of the project you’re in. 2. Choose **Create API Key**, and give it a name, such as fxbot. 3. Copy the key. Together shows it only once. 4. Add credit in Together’s billing settings, if you haven’t yet. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Together AI**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Together first. 3. Pick a model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Together AI** when you leave it empty. | Together’s address is `https://api.together.ai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Together’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. fxbot looks for each by its id, then by its name without the maker in front. A model models.dev doesn’t know still lists, without them. ## Quirks [Section titled “Quirks”](#quirks) * **Together doesn’t take the `developer` role,** the name OpenAI’s API now gives a model’s instructions, in place of `system`. If libfx, which runs fxbot’s chats, sends instructions that way, a chat fails. This is what the research for this page found: pi, another agent app, marks Together so. fxbot hasn’t run Together with a real key yet. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Together AI rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and add it with the provider’s **Replace key**. * **“Together AI rejected this key (HTTP 403): it may lack a permission, or the account may need credit.”** The key may lack a permission, or the account may need credit. Add credit, then choose **Add** again. * **A chat fails after the key was added.** Together stops a key’s access when its balance reaches zero. Add credit in its billing settings. * **A chat stops with HTTP 429.** You’ve reached your account’s rate limit. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Vercel and AI Gateway > Vercel's AI Gateway reaches hundreds of models from many labs, billed to one of your Vercel teams. Sign in with your Vercel account, or add an AI Gateway key. Vercel’s AI Gateway reaches hundreds of models from many labs, billed to one of your Vercel teams. Every team gets a monthly free credit, for some of its models at lower rate limits. Buying credits moves the team to the paid tier, at each provider’s list price ([AI Gateway pricing](https://vercel.com/docs/ai-gateway/pricing)). fxbot takes it two ways: your Vercel account, signed in, or an AI Gateway key. ## Sign in [Section titled “Sign in”](#sign-in) **Vercel’s sign-in is off for now.** fxbot signs in with a device code, and Vercel doesn’t let fxbot’s app use one yet. Meanwhile, [use a key](#make-a-key). A server that sets [`FXBOT_VERCEL_CLIENT_ID`](/docs/reference/configuration/), to a Vercel app that may use device codes, shows the sign-in. You sign in with your own Vercel account, and use your own team’s credit. 1. In **Settings** › **Providers**, choose **Add provider**, then **Vercel**, under **Sign in**. A code shows at once. 2. Open the link on any device: scan its QR code, choose **Copy link**, or follow the **Open** link beside the code. Sign in to Vercel, and enter the code. **Copy code** copies it. 3. Leave fxbot’s page open. It finishes on its own, and shows the time left. 4. Pick a model, and choose **Done**. **Make it the default for new bots** starts new bots on it. fxbot keeps the account’s tokens sealed, and renews them before they end. AI Gateway bills one of the account’s teams. fxbot picks it by itself when the account has one. With more than one, fxbot lists no models until you pick: in **Settings** › **Providers**, choose it under the provider’s **Team**, then set its **Default model**. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [AI Gateway’s API keys](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys), and sign in. 2. Pick the team to bill, then choose **Create key**, and give it a name, such as fxbot. 3. Copy the key. Vercel shows it only once. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **AI Gateway**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with AI Gateway first. 3. Pick a model, and choose **Done**. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **AI Gateway** when you leave it empty. | The key bills the team it was made in, so it needs no **Team**. ## Claude with your own Anthropic key [Section titled “Claude with your own Anthropic key”](#claude-with-your-own-anthropic-key) AI Gateway can bill Claude to your own Anthropic key, at Anthropic’s prices with no markup ([Bring Your Own Key](https://vercel.com/docs/ai-gateway/authentication-and-byok/byok)). On AI Gateway’s **Bring Your Own Key** page, find **Anthropic**, choose **Add**, paste the key, leave **Enabled** on, and choose **Test Key**. fxbot keeps using the AI Gateway key, and AI Gateway’s logs say which key served each request. Through AI Gateway, fxbot’s agent library marks Claude’s prompts for Anthropic’s prompt caching, so a long chat costs less than through the [Anthropic](/docs/providers/anthropic/) provider, whose OpenAI-compatible API has none. From Vercel’s docs: * **It needs the paid tier,** with AI Gateway credits bought. * **A request your key fails is tried again on Vercel’s own credentials,** and billed to the team’s credits. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from AI Gateway’s own list, whichever way you came in. ## When it fails [Section titled “When it fails”](#when-it-fails) * **No Vercel under Sign in.** Its sign-in is off for now, as above. Use an AI Gateway key. * **“Vercel did not issue a device code (HTTP 401): This client is not authorized to use the Device Authorization flow.”** The Vercel app fxbot signs in through isn’t allowed device codes yet. Its owner turns that on in the app’s settings at Vercel. Meanwhile, use an AI Gateway key. * **“Pick a Vercel team for this provider in Settings.”** The account has more than one team, and none is picked yet. Pick one under the provider’s **Team**. * **“This sign-in expired.”** The code ran out before you entered it. Choose **Start again** for a new one. * **“Vercel did not renew the sign-in.”** Use the provider’s **Sign in again**. * **“AI Gateway rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Vercel also turns off the keys a person made when they leave the team. Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** You’ve reached a rate limit, which is lower on the free tier. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Vertex AI > Vertex AI serves Gemini and partner models in your own Google Cloud project. Add it to fxbot with a service account's key file, from which fxbot makes its own tokens. Vertex AI is Google Cloud’s way to run Gemini, and partner models, in your own Google Cloud project, billed to that project. Google now calls it Gemini Enterprise Agent Platform, and its console and docs use that name. Its prices are on its [pricing page](https://cloud.google.com/vertex-ai/generative-ai/pricing). For a key from Google AI Studio instead, with a free tier, use [Google Gemini](/docs/providers/gemini/). ## Make a service account key [Section titled “Make a service account key”](#make-a-service-account-key) Vertex takes no API key here, so fxbot signs in as a service account: an account for software, in your project. 1. In the [Google Cloud console](https://console.cloud.google.com/), pick or make a project. Find the **Agent Platform API** with the console’s search, and choose **Enable**. It was the Vertex AI API. 2. Open [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts), and choose **Create service account**. Give it a name, such as fxbot, and choose **Create and continue**. 3. Give it the **Agent Platform User** role (`roles/aiplatform.user`). It was Vertex AI User. Choose **Continue**, then **Done**. 4. Choose the account’s email, then **Keys** › **Add key** › **Create new key**. Pick **JSON**, and choose **Create**. The file downloads, and Google lets you download it only once. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Vertex AI**, under **Clouds**. 2. Leave **Location** as `global`, or type a region. Choose the JSON file under **Service account key**, then **Add**. fxbot makes its first token from the file, which checks it with Google. 3. Pick a model. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | **Location** | `global`, the default, or a region such as `us-central1`. | | **Service account key** | The JSON file Google downloaded. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Vertex AI** when you leave it empty. | The project comes from the file. fxbot fills in the address from the project and the location: `https://aiplatform.googleapis.com/v1/projects/{project}/locations/global/endpoints/openapi` for `global`, and a region’s own host for a region, such as `https://us-central1-aiplatform.googleapis.com/…`. To move to another location, remove the provider and add it again. ## Its models [Section titled “Its models”](#its-models) Vertex’s endpoint has no model list, so fxbot lists models.dev’s list for Vertex, with each one’s context window, tool use, and images. Each Gemini model has `google/` in front, as Vertex wants it. A partner model keeps its maker’s name in front instead. Claude isn’t on this endpoint, so it isn’t listed. Not every model is served at every location. ## Quirks [Section titled “Quirks”](#quirks) These come from Google’s docs, and from how Vertex answers. fxbot hasn’t run Vertex with a real service account yet. * **No API keys.** Vertex’s OpenAI-compatible endpoint takes only Google Cloud’s own tokens, and answers an API key with “API keys are not supported by this API”. So fxbot makes its own, each an hour long: it signs a request with the account’s key, and trades it at Google’s token endpoint, and no other. It makes a new one 5 minutes before each ends. * **Checked by a token.** Adding checks only that Google makes a token from the file. A missing role, an API that’s off, or a wrong location shows at the first chat. * **Global or a region.** Google says `global` is more available than a single region, and gets fewer 429s. Pick a region when the model must run there. * **Gemini’s thought signatures.** Gemini 3 and newer want each tool call’s thought signature back on the next turn, as on [Google Gemini](/docs/providers/gemini/#quirks). Whether libfx, the agent inside fxbot, sends them back here hasn’t been checked. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“That file isn’t a service account’s JSON key.”** Choose the JSON file from the account’s **Keys**, not another file from Google Cloud. * **“That service account names a token endpoint that isn’t Google’s.”** The file’s `token_uri` was changed. Make a new key in the console, and choose that file. * **“Google refused the service account (HTTP …).”** Google wouldn’t make a token from the file. The key or the account may have been deleted or disabled. Make a new key, and add it with the provider’s **Replace service account**. * **The console won’t make a key.** An organization policy, `iam.disableServiceAccountKeyCreation`, blocks service account keys. Google turns it on for organizations made since May 3, 2024. An organization policy administrator can exempt your project. * **“Vertex AI rejected this provider’s key. Replace it in Settings › Providers.”** fxbot says this when a chat gets a 401 or a 403. With Vertex, a 403 can also mean the account lacks the **Agent Platform User** role, or the API is off in its project. Check those in the console first. You need a new key file only if the old one was deleted. * **A chat can’t reach Vertex, or gets HTTP 404.** The location may be wrong, or the model isn’t served there. Remove the provider, and add it again with another location. * **A chat stops with HTTP 429.** You’ve reached a quota for that model. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # vLLM > vLLM serves open models on your own machine's GPU, for free. Start it with --enable-auto-tool-choice and a --tool-call-parser, so the model can call tools, and add it to fxbot at its address. vLLM serves open models from Hugging Face on your own machine’s GPU, fast, and to many requests at once. It’s free and open source, and runs on Linux. Your own hardware does the work. ## Start the server [Section titled “Start the server”](#start-the-server) 1. Install vLLM, as its [quickstart](https://docs.vllm.ai/en/latest/getting_started/quickstart/) says. 2. Serve a model, with tool calls turned on: ```sh vllm serve Qwen/Qwen2.5-1.5B-Instruct --enable-auto-tool-choice --tool-call-parser hermes ``` * **`--enable-auto-tool-choice`** lets the model call tools when it chooses to, which a bot’s tools need. vLLM leaves it off unless you give it. * **`--tool-call-parser`** says how the model writes its tool calls, which differs by model: `hermes` for Qwen2.5 and Hermes, `llama3_json` for Llama 3.1 and 3.2, `mistral` for Mistral, and `openai` for gpt-oss. vLLM’s [tool calling](https://docs.vllm.ai/en/latest/features/tool_calling.html) page lists the rest, and the models that need a `--chat-template` too. * **`--max-model-len`** sets the context. Without it, vLLM takes the model’s own. * **`--served-model-name`** gives the model the id fxbot shows. Without it, the id is the model’s name, as you gave it. * **`--api-key`**, or `VLLM_API_KEY`, makes it ask for a key. Without either, it takes none. vLLM listens on port 8000, and serves an OpenAI-compatible API under `/v1`. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**. Under **On your machine**, **vLLM** says **Found here** when it’s running at its usual address with no key. fxbot asks each server there for its model list when the page opens, and gives it half a second to answer. 2. Choose **vLLM**. Its address is filled in, with **Found running on this machine.** under it when fxbot found it. 3. Leave **API key, if the server needs one** empty, unless you gave vLLM a key. Choose **Add**. fxbot checks the server first. 4. Pick the model. Tick **Make it the default for new bots** to start each new bot on it. | Field | What to put there | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Address** | vLLM’s, with its `/v1`. The usual one, `http://localhost:8000/v1`, is filled in. | | **API key, if the server needs one** | The key you gave `--api-key` or `VLLM_API_KEY`, if any. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Context window** | Optional. vLLM reports each model’s, so leave it empty unless that’s wrong. A number here overrides what vLLM reports, for every model on this provider. | | **Name** | Optional. It’s **vLLM** when you leave it empty. | When fxbot runs from a checkout, with `npm run dev`, it runs on the machine itself, and the usual address works as it is. ### In a release install [Section titled “In a release install”](#in-a-release-install) A release install, the one `setup.sh` makes, runs fxbot in a container. There, `localhost` is the container, not your machine, so fxbot doesn’t find vLLM, and the usual address doesn’t reach it. fxbot takes an HTTPS address, or plain HTTP only on localhost. A server on the machine is plain HTTP from inside the container, which fxbot can’t use yet, and the card says so. The same goes for a server on another machine. Put vLLM behind HTTPS, and give fxbot that address. With Tailscale, and [HTTPS turned on](https://tailscale.com/kb/1153/enabling-https) for your tailnet, serve it on a port of its own, such as 8443: ```sh sudo tailscale serve --bg --https=8443 8000 ``` Then give fxbot `https://..ts.net:8443/v1` as the **Address**. fxbot’s own `tailscale serve`, on port 443, stays as it is ([Reach fxbot from other devices](/docs/how-to/reach-it/)). ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from vLLM’s own list, `/v1/models`: the one it serves, by its id, with the context window vLLM runs it with, its `--max-model-len`. vLLM’s list doesn’t say whether a model uses tools or reads images. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“The key check couldn’t reach localhost:8000.”** vLLM isn’t running there, or is still loading the model. Wait for it, or give the address it runs at. In a release install, that’s the container’s own localhost: see [In a release install](#in-a-release-install). * **“vLLM rejected this key (HTTP 401): it’s wrong, or it was deleted.”** vLLM was started with a key, and the one you gave isn’t it, or you gave none. * **“baseUrl must use https, or http on localhost.”** The address is plain HTTP to somewhere other than `localhost` or `127.0.0.1`. Give an HTTPS address. * **A chat fails at once, with an error from vLLM about tool choice.** vLLM was started without `--enable-auto-tool-choice` and a `--tool-call-parser`. A bot’s tools need both: start it with them. * **The model writes tool calls as text.** The parser doesn’t match the model. Pick the one vLLM’s tool calling page names for it. # xAI > xAI makes the Grok models, and serves them from its own API. Load credits, then add it to fxbot with a key from its console. xAI makes the Grok models, and serves them from its own API. You load credits before a key can run a model. Its prices are on its [models page](https://docs.x.ai/developers/models). If you pay for SuperGrok or X Premium, [Grok](/docs/providers/grok/) signs in with your plan instead, with no key. ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [console.x.ai/team/default/api-keys](https://console.x.ai/team/default/api-keys), and sign in or make an account. 2. Load credits. Without them, the key can’t run a model. 3. Choose **Create API key**. Leave every model and endpoint allowed. 4. Copy the key. ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **xAI**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with xAI first. 3. Pick a model from xAI’s list. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **xAI** when you leave it empty. | xAI’s address is `https://api.x.ai/v1`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from xAI’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from xAI’s docs, and from how its model list answers. fxbot hasn’t run xAI with a real key yet. * **A bad key gets 400.** xAI’s model list answers a key it can’t read with 400, not 401. So when you add a key, fxbot counts a 400 as a refusal too. * **Chat Completions is legacy there.** fxbot talks to xAI through Chat Completions, which xAI’s docs call legacy and deprecated, with new features going to its Responses API first. * **Reasoning.** xAI’s docs carry a model’s reasoning from one turn to the next only in the Responses API, encrypted. Chat Completions returns none. How that plays out with libfx, the agent inside fxbot, hasn’t been checked. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“xAI rejected this key (HTTP 400): it isn’t a key it can read.”** The key is wrong, or was cut short when you copied it. Copy it again, or make another. * **“xAI rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Make another, and paste that. * **“xAI rejected this provider’s key. Replace it in Settings › Providers.”** The key stopped working, such as after it was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat fails once your credits run out.** Load more in xAI’s console, and send the message again. * **A chat stops with HTTP 429.** You’re sending more than xAI’s rate limit allows. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Z.ai > Z.ai makes the GLM models, and serves them from its own API. Its Flash models are free. Add it to fxbot with a key from its platform. Z.ai makes the GLM models, and serves them from its own API. Its Flash models, such as GLM-4.7-Flash, are free. The others are paid from a balance you top up, at the prices on its [pricing page](https://docs.z.ai/guides/overview/pricing). ## Make a key [Section titled “Make a key”](#make-a-key) 1. Open [z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list), and sign in or make an account. 2. Choose **Create a new API key**. Make one for the standard API, not for the GLM Coding Plan: Z.ai says keys for the two don’t work in each other’s place. 3. Copy the key. 4. For models other than Flash, top up at [Billing](https://z.ai/manage-apikey/billing). ## Add it to fxbot [Section titled “Add it to fxbot”](#add-it-to-fxbot) 1. In **Settings** › **Providers**, choose **Add provider**, then **Z.ai**, under **Use a key**. 2. Paste the key, and choose **Add**. fxbot checks it with Z.ai first. 3. Pick a model from Z.ai’s list. **Make it the default for new bots** starts new bots on it. | Field | What to put there | | ----------- | --------------------------------------------------------------------------------------------- | | **API key** | The key you copied. It goes to fxbot’s server once, sealed, and never comes back to the page. | | **Name** | Optional. It’s **Z.ai** when you leave it empty. | Z.ai’s address is `https://api.z.ai/api/paas/v4`. fxbot fills it in. ## Its models [Section titled “Its models”](#its-models) fxbot lists the models from Z.ai’s own list, with each one’s context window, tool use, and images from [models.dev](https://models.dev), where models.dev knows the model. ## Quirks [Section titled “Quirks”](#quirks) These come from Z.ai’s docs. fxbot hasn’t run Z.ai with a real key yet. * **Tool choice is `auto` only.** Z.ai’s docs say its `tool_choice` takes only `auto`, where the model decides whether to call a tool. A request that asks for anything else, such as forcing a tool, may be refused. * **The GLM Coding Plan is separate.** Its keys are for an address of its own, `https://api.z.ai/api/coding/paas/v4`. fxbot uses the standard API’s. ## When it fails [Section titled “When it fails”](#when-it-fails) * **“Z.ai rejected this key (HTTP 401): it’s wrong, or it was deleted.”** Check that you copied all of it, and that it’s a standard API key. Or make another and paste that. * **“Z.ai rejected this provider’s key. Replace it in Settings › Providers.”** The key stopped working, such as after it was deleted. Make another, and add it with the provider’s **Replace key**. * **A chat stops with HTTP 429.** Z.ai answers 429 both for its rate limit and for a paid model with no balance left. Top up, or pick a Flash model. fxbot tries again by itself, and stops the turn after 5 minutes of nothing but refusals ([Providers](/docs/reference/providers/)). # Changelog > Each release of fxbot, newest first. A release that adds migrations, bumps libfx, or needs a step by hand opens with **Before upgrading**. Lines for the next release collect under Unreleased. GitHub Releases and Settings show a short version of each section. Each release of fxbot, newest first. A release that adds migrations, bumps libfx, or needs a step by hand opens with **Before upgrading**. Lines for the next release collect under Unreleased. GitHub Releases and Settings show a short version of each section. ## 0.10.0 (2026-11-13) [Section titled “0.10.0 (2026-11-13)”](#0100-2026-11-13) **Before upgrading.** Migration `0016_effort` adds an `effort` column to `profiles`, for how hard a bot’s model thinks, and to `plugin_sessions`, for a plugin’s session that thinks at its own level. Every bot starts at its model’s own default, as before. Migration `0017_team_memories` lets a memory have no bot, which makes it the team’s, and adds `by_bot`, the bot that saved one. Every memory there is stays its bot’s own. Migration `0018_idle_compaction` adds idle compaction’s settings to `settings`: on, after 30 minutes, with each bot’s own model. So in the first minutes after the update, each bot’s long chat that has sat idle for 30 minutes or more, however long ago, is summarized once, with that bot’s own model, one bot after another, and so is each long room once Chat rooms is 0.5.0, by its lead. To skip that, turn **Idle compaction** off in **Settings** › **General** as soon as fxbot is back. Update Computer, then remove chat-rooms-computer, in that order: Computer 0.5.0 takes over each room’s computer, while removing chat-rooms-computer first, on Computer 0.4.0, deletes the rooms’ computers and their files. Remove the fresh plugin from **Plugins**, where it shows **Unsupported**: `/fresh` is built in now. Then update Subagents from **Plugins**, for its `thinking` setting, and Chat rooms, to 0.5.0, for a room’s memories and its starting over. * **Choose how hard a bot thinks.** **Thinking**, under **Model** on a bot’s edit screen, offers the levels its model has, such as Low, Medium, High, Extra high, and Max, or the model’s own default. fxbot reads each model’s levels from where its provider lists them: AI Gateway’s catalog, ChatGPT’s and Grok’s lists, models.dev, OpenRouter, Ollama, and LM Studio. A level the model doesn’t offer runs as the nearest lower one, never Off, and the screen says so. The level reaches the model through AI Gateway, Vercel, ChatGPT, and Grok now, and through every other provider with the next libfx release. See [Choose how hard a bot thinks](/docs/how-to/choose-how-hard-a-bot-thinks/). * **Subagents think at a level of their own,** with Subagents 0.2.0: `thinking` in **Settings** › **Subagents** is `same`, the bot’s level, or one such as `high`. * **Team memories.** Notes every one of your bots reads, such as who you are and how you like things done, in **Settings** › **Memory**, where you add, edit, search, and delete them. A bot saves one with `memory_save` and `team` when you ask it to remember something for all your bots, and the list says which bot saved each one. **Share with every bot**, beside each of a bot’s own memories, moves one to the team. They go in every bot’s instructions after its own, and `memory_search` finds them. See [Team memories](/docs/explanation/bots-and-chats/#team-memories). * **A room’s computer is part of the computer,** with Computer 0.5.0. With chat rooms added too, the screen button at the top of a room gives it a computer its bots share, as chat-rooms-computer did, and that plugin leaves fxbot’s list and **Essentials**. On 0.10.0 it shows **Unsupported**, and each room keeps its computer once Computer is updated. See [Give a room a computer](/docs/how-to/give-bots-a-computer/#give-a-room-a-computer). * **`/fresh` is built in.** It works in every bot’s chat, as the fresh plugin’s did, with nothing to add, and the plugin leaves fxbot’s list and **Essentials**. See [Start a chat over with /fresh](/docs/how-to/start-fresh/). * **Idle compaction.** A long chat that sits with no message for 30 minutes is summarized while you’re away, so your next message starts fast: the bot reads the summary and the last messages, not the whole chat again. The chat shows **Compacted while idle**, which opens to the summary, and the earlier messages stay above it. **Idle compaction** in **Settings** › **General** sets the time, or **Off**, and **Summarize with** picks a cheaper model to write the summary. A message you send meanwhile calls it off. See [Idle compaction](/docs/explanation/bots-and-chats/#idle-compaction). * **A chat’s summary stays in its chat.** After a provider switch, `/fresh`, or idle compaction, the summary of a bot’s own chat went into its instructions everywhere it worked: in each room, a routine’s run, and its subagents, which also made them read their whole context again. Now only its own chat gets it. * **An empty summary is no summary.** libfx answers a request that gets no text with “Done.”, which a provider switch or `/fresh` took as the chat’s summary. Now it fails as any summary that didn’t come back does: a switch summarizes from the stored messages instead, and `/fresh` says the chat couldn’t be summarized. * **A room’s own memories,** with Chat rooms 0.4.0: **Memories**, at the top of a room, keeps notes every bot in that room reads there, such as what the room is for and what was decided. The room’s bots save them too, with `chat-rooms_remember`. See [Give a room memories](/docs/how-to/talk-in-a-room/#give-a-room-memories). * **A room starts over, as a bot’s chat does,** with Chat rooms 0.5.0. A long room that sits idle is compacted by the same **Idle compaction** setting, and `/fresh` at the start of a message stops the room’s bots, summarizes the room toward what you wrote next, and starts it over. The room shows **Compacted while idle** or **Started over**, which opens to the summary. One summary serves the whole room, written by its lead unless **Summarize with** names a model, and each bot’s next turn there starts from it. `chat_history` says where a match came from, your own chat or a room, and finds what came before. See [Start a room over](/docs/how-to/talk-in-a-room/#start-a-room-over). * **Send PDFs to a bot.** A PDF of up to 8 MiB attaches as an image or a text file does, and a message’s files can be 8.5 MiB together. The bot reads the text fxbot finds in it, page by page: up to 60,000 characters in your message, and the rest from the library, where `library_read` now reads a long document in parts. A PDF of scanned pages says it has no text. The library keeps the PDF itself, which downloads as it is, and its preview shows the text the bot reads. Search finds a PDF by its words. * **Bots with a soul.** The new **soul** plugin, in **Essentials**, gives each bot a soul: a few lines, in its own words, of who it is, how it sounds, and how it helps you. The first time you open a new bot’s chat, it speaks first: it guesses who it might be from its name, asks what you’d like help with, and writes its soul from your answers. It rewrites it when you ask, in its own chat only, and **Soul** on its edit screen lets you edit it, with every version to go back to. Its skill, `import-profile`, brings a soul and memories over from a Hermes Agent profile or an OpenClaw agent, from files you send, or from Grok Bot, ChatGPT, or Claude through a prompt you paste there. Joining **Essentials** doesn’t add it to an install that has fxbot already: add it from **Plugins**. See [Give a bot a soul](/docs/how-to/give-a-bot-a-soul/). * **For plugins:** an `app.chat` part gets `reload()`, which reads the bot again, so the chat follows a session the plugin started. `fx.chats.newSession(bot, { effort })` gives a session of the plugin’s own a thinking level in place of the bot’s, and `fx.library.save` takes a PDF. A `Memory` has `team` and `savedByBot`; `fx.memories` still reaches only a bot’s own. A message hook’s `startOver` doesn’t count when the message began with `/fresh`, which fxbot runs itself. `fx.compaction()` reads idle compaction’s setting, for a plugin’s own chats. A need marked `"optional": true` names a plugin a plugin works with, without needing it: it loads without it, and its page lists it under **Works with**. * **Claude with prompt caching, through AI Gateway.** The Anthropic provider’s way in has no prompt caching, and its card on Add provider now says how to get it: add Claude through AI Gateway, with your own Anthropic key there, at Anthropic’s prices. See [Claude with your own Anthropic key](/docs/providers/vercel/#claude-with-your-own-anthropic-key). * **Deleting a room while a bot answers there no longer stops fxbot,** with Chat rooms 0.5.0. The reply had no room left to be saved in, and the failure ended the server; now deleting a room stops its turns first. * **web.fxbot.sh connects again after a computer wakes up.** The app there could say **Connecting…** for good after its connection dropped, and a page loaded meanwhile ended on the browser’s error page. Now a stuck attempt gives way to a new one, and the page loads again once the app connects. It’s a change to the app at web.fxbot.sh, so your fxbot needs no update for it. * **No more box around a moving bot in Firefox.** With hardware acceleration on, a bot that leaned after the pointer, such as the one open in the sidebar, could show thin straight lines along its right and bottom edges. The home page’s bots on fxbot.sh had them too ([#16](https://github.com/iammrduncan/fxbot/issues/16)). ## 0.9.0 (2026-11-10) [Section titled “0.9.0 (2026-11-10)”](#090-2026-11-10) **Before upgrading.** Migration `0015_session_labels` adds a `label` column to `plugin_sessions`, for the name a plugin gives a session of its own. Every session you have carries on as it is. Then update Computer from **Plugins**, if you have it. * **Web pairing leaves Essentials.** Add it from **Plugins** when you want your fxbot on your phone. An install that has it keeps it. * **Subagents.** The new **subagents** plugin, in **Essentials**, lets a bot hand work to helpers that run in the background while it carries on talking with you. Each is the bot itself, run again on one task, with its tools, computer, skills, and memories, but not its chat. The subagents one turn starts report back together, in one message from **Subagents**, once the last has ended, and the bot tells you what they found. Each has a name of its own, in its own color in the bot’s panel, which lists them, working and recent, and each opens to its thread, live, with **Stop**. A subagent can tell the bot’s chat what can’t wait, and the bot can message a working subagent, by name. With the plugin on, a bot hands work that takes a lot of digging to subagents by itself, and tells you it’ll come back with the results. A subagent can’t start one of its own, and leaves memories, messages to other bots, routines, and asking you to the bot’s chat. Joining **Essentials** doesn’t add it to an install that has fxbot already: add it from **Plugins**. See [Hand work to subagents](/docs/how-to/hand-work-to-subagents/). * **Diagrams in chat.** The new **mermaid** plugin draws the ` ```mermaid ` code blocks bots write as diagrams, in replies, Markdown pages, rooms, and the library, in the app’s own colors and font, light and dark. A diagram grows as the bot writes it, and one with a mistake shows its code and what’s wrong. Bots get a skill, and `mermaid_check` to try a diagram before they send it. It draws with [Pele](https://pele.run), Obsidian’s Mermaid renderer, loaded with the first diagram. Add it from **Plugins**. See [Draw diagrams in chat](/docs/how-to/draw-diagrams-in-chat/) ([#9](https://github.com/iammrduncan/fxbot/issues/9)). * **A bot’s subagents work on its computer together,** with Computer 0.4.0: each has its name and arrow on the computer’s screen, its own browser tab with the bot’s sign-ins, and turns at the desktop and the terminal, as a room’s bots take turns. * **Bots write pages without being asked.** With Pages 0.3.0, a long answer, such as a report, a comparison, research findings, or a plan, comes as a page, and the bot says in a sentence or two what it covers. What a few sentences answer stays in the chat, and so does anything you ask to have there. * **fxbot’s plugins teach bots how to use them** ([#14](https://github.com/iammrduncan/fxbot/issues/14)). Pages 0.3.0, Subagents, Routines 0.2.0, and Messages 0.2.0 each carry a skill now, as Computer and Chat rooms do: when to use the plugin, and how to use it well, which a bot reads when a task calls for it. Pages’ has the rules for an HTML page and one to start from, Subagents’ how to split work and write a task, Routines’ schedules to copy, and Messages’ how replies go. Computer’s `browser` and `desktop` skills now hold the commands a bot needs, where they sent it to read each tool’s own guide first. Update them from **Plugins**. * **A message you haven’t sent stays in its bot’s box** when you go to another screen, reload, or close the app, until you send it or clear it. Each bot keeps its own, in that browser ([#13](https://github.com/iammrduncan/fxbot/issues/13)). * **For plugins:** `fx.chats.newSession(bot, { label })` names a session of the plugin’s own, and each of its tool calls, and `tool.before` and `tool.after`, get `label`, or null in a bot’s own chat. `fx.chats.send` with `steer` now works in a session of the plugin’s own too, so a message joins a turn running there. On the page, `app.codeBlock(language, Component)` draws a language’s fenced code blocks wherever the app shows Markdown, `ui.Streamdown` included. * **Each of fxbot’s plugins links to its docs.** Its page in **Plugins**, its tab in **Settings**, and its page in the [plugin directory](/plugins/) have **Docs**, which opens its guide on fxbot.sh. The links come with fxbot’s plugin list, which fxbot reads hourly, so a new guide needs no release. For the SDK, a `PackagePlugin` and a `PackageCard` carry `docs`, a path on fxbot.sh, when the list has one. ## 0.8.0 (2026-11-10) [Section titled “0.8.0 (2026-11-10)”](#080-2026-11-10) **Before upgrading.** Migration `0014_provider_fields` adds `fields` and `model_ids` columns to `providers`, for a provider’s region or account and the models you type for it. Every provider you have carries on as it is. The update to 0.8.0 runs 0.7.0’s `fxbot` command, which leaves 0.7.0’s image: `sudo podman rmi ghcr.io/iammrduncan/fxbot:0.7.0`, or `sudo docker rmi` on Docker, takes it away. With the computer, run `sudo fxbot computer on` once after updating: it moves the computer’s lines out of `compose.override.yaml`, into a file of their own. * **A new page for adding a provider.** **Add provider**, in **Settings** › **Providers**, opens a page of providers, each with its logo, sign-ins first, then keys, clouds, and servers on your own machine, with a search over about 200 providers. First-run setup shows the same page, sign-ins first. * **Sign in to OpenRouter and OrcaRouter, with nothing to paste.** OpenRouter’s sign-in comes back to fxbot’s own page, or shows a code to paste where it can’t. OrcaRouter’s is a device code. Each makes a key on your account, which fxbot keeps sealed. Hugging Face signs in by device code too, through fxbot’s own app there. Requests to OpenRouter now name fxbot as the app that sent them. * **A device code shows a QR of its link,** and buttons to copy the code and the link, for an account that lives on your phone. * **Each key, walked through.** A card for each of 23 gateways and labs links straight to the page where its keys are made, says what to pick there, and what it costs to start, then checks the key for real. Groq, Anthropic, Google Gemini, DeepSeek, Z.ai, Qwen, Kimi, MiniMax, xAI, Mistral, Together, Fireworks, DeepInfra, Cerebras, NVIDIA, Hugging Face, and Nous Portal are new. * **Clouds.** Vertex AI with a service account’s file, from which fxbot makes its own short-lived tokens, AWS Bedrock with an API key and a region, Azure OpenAI with a resource and its deployments, and Cloudflare Workers AI with a token and an account. * **More servers on your own machine.** llama.cpp, vLLM, and LiteLLM join Ollama and LM Studio, each with its usual address filled in, and one that’s running is marked as found. * **Custom** takes any server that speaks OpenAI’s Chat Completions, as Other server did, and model ids for a server that lists none. * **Models say what they can do.** The model list comes from the provider itself, with models.dev’s context window, tool use, and images shown for each model, and a good first model filled in after you connect. * **The list of providers updates without a release.** fxbot reads it hourly from fxbot.sh, as it does the plugin list, so a new gateway, or a key page that moved, needs no update. * **Skip for now skips one step** of first-run setup, where it ended the whole setup: plugins go on to the provider, and the provider to your first bot. On the bot step, it ends setup. * **A refused key says which provider, and what to do.** A key refused when you add it says the status and what it most likely means. A chat whose provider refuses its key says “Groq rejected this provider’s key. Replace it in Settings › Providers.”, where it said “Stopped: refused”. * **For the SDK:** `providers.catalog()` and `providers.local()` list what the page offers, and the local servers that answer. `providers.add` takes `fields`, `serviceAccount`, and `modelIds`, and a provider’s `kind` is any entry’s id. A `Provider` gains `label`, `connect`, `docs`, `fields`, and `modelIds`. A `SignIn` gains `way` and `url`, its `verificationUrl` and `userCode` are there only for a device code, and `signIns.code` finishes one that shows a code. A `Provider`’s `kind` is a `string`. `createFxbot` takes `hfClientId`, and the server `FXBOT_HF_CLIENT_ID`. * **Your fxbot on your phone, from anywhere.** The new **web-pairing** plugin, in **Essentials**, opens your own fxbot at [web.fxbot.sh](https://web.fxbot.sh), on a phone or any computer, over a WebRTC connection straight to it. fxbot.sh passes only the sealed handshake, and your fxbot’s own page, plugins and all, comes from your fxbot. It connects to nothing until you pair a device. * **Pair a device once.** **Settings** › **Web pairing** › **Pair a device** shows a code and a QR code. Type the code on the device, check both screens show the same six digits, and approve. A device stays paired until you remove it, reconnects by itself, and can pair another from anywhere. An opt-in passkey pairs a wiped one again with no other device. * **It says what will connect.** **Reachability** checks your fxbot’s network in advance: UDP, its NAT, a mapped port, IPv6, and a container. A device that can’t connect says why after 15 seconds, and links to the fix. Cloudflare’s STUN finds the way by default; add STUN and TURN servers of your own, in your order. fxbot maps its UDP ports on the router by NAT-PMP or UPnP where it can. * **New guides** for reaching fxbot from your phone, pairing another device, what to do when a device can’t connect, forwarding a port, WireGuard, and running your own TURN server, STUN server, or relay, with how it all works. * **For plugins:** `fx.secrets` keeps values a plugin makes itself, such as keys of its own, sealed beside its settings, and `fx.localUrl` is the server’s own address, for requests to fxbot’s own API. * **fxbot installs on more of Linux.** `setup.sh` installs through apt, dnf, zypper, or pacman, so Fedora, AlmaLinux and the other RHEL rebuilds, openSUSE Tumbleweed and Leap, and Arch join Debian and Ubuntu, with the distros built on them. Arch’s support builds on [PR #11](https://github.com/iammrduncan/fxbot/pull/11), thanks to Olen Thompson. On Fedora, RHEL, and openSUSE, SELinux and firewalld stay on: fxbot’s folders are labelled for containers, and podman’s DNS rules come back after a firewalld reload. * **`setup.sh` checks before it changes anything.** It stops, with what to do, on macOS or Windows, without systemd, on a CPU fxbot has no image for, with too little disk, when another program has the port, when Docker is a snap, or when apt would remove a package to install one. With under 1 GB of memory free, it says so and carries on. A new page, [Fix an install that stopped](/docs/how-to/fix-an-install/), has each stop and its fix. * **It takes the engine that’s there.** A Docker that’s running now wins over an installed podman, and `FXBOT_ENGINE` names one. With no engine, it installs podman 4.9 or newer, or Docker’s own `docker-ce` where the distribution’s podman is older, as on Debian 12 and Ubuntu 22.04, and never Ubuntu’s `docker.io` again. It shows the images downloading, and lists each package it installs in `/etc/fxbot/packages`. * **Another port than 8787.** `curl -fsSL https://fxbot.sh/setup.sh | sudo FXBOT_PORT=8780 bash` installs on 8780, the same port inside the app’s container as out. * **The computer runs on every engine.** Its engine is rootless podman wherever the distribution has 4.9 or newer, beside whichever engine fxbot runs on, so Ubuntu 24.04 with `docker.io` gets a computer, where its setup stopped before. Where podman is older, it’s the machine’s own Docker, run rootless. A computer already set up keeps its engine. It stops, changing nothing, on cgroups v1 or without user namespaces. Its compose file is its own now, `compose.computer.yaml`, so `compose.override.yaml` is yours alone. The computer plugin goes to 0.3.2. * **The computer’s setup works without systemd-resolved,** as on a plain Debian, where it stopped on reading resolved’s file. And a computer home that’s a disk of its own is the user’s, and emptied on `--remove`. * **`sudo fxbot backup`** writes the database and the plugins’ files into a folder `fxbot restore` takes. [Back up fxbot](/docs/how-to/back-up/) uses it, and has how to move to a new machine. * **`sudo fxbot uninstall`** takes fxbot off the machine, after one question: its containers, volumes, and images, the computer, the units, and the command. It keeps a backup, the key, and the `fxbot` user, so you can install again on them, unless you add `--purge`. It names the packages `setup.sh` installed, with the command to remove them. See [Uninstall fxbot](/docs/how-to/uninstall/). * **On podman with ufw,** each start lets the containers’ DNS in on their bridge, so an install behind ufw’s default deny no longer fails on `EAI_AGAIN db`. The update from 0.7.0 starts fxbot with 0.7.0’s command, so run `sudo fxbot up` once after it. * **Updates from this release on take the old release’s images away** once the new one runs, and a GPU trial that finds no GPU takes its 4 GB image away too. * **`fxbot status` says whether fxbot answers,** and `fxbot logs` ends when it’s piped, as when an agent runs it. * **A wrong OpenRouter key is refused when you add it.** OpenRouter’s model list answers anyone, so fxbot took any key there, and the key failed only at the first message. fxbot now checks it where OpenRouter refuses a bad one. ## 0.7.0 (2026-11-09) [Section titled “0.7.0 (2026-11-09)”](#070-2026-11-09) **Before upgrading.** Migration `0011_onboarding` adds `onboarding_step` and `onboarded_at` columns to `settings`. An install with a bot, a plugin, or a provider is marked done, so it never sees first-run setup. Migration `0012_looks` adds `mood`, `head`, `face`, `outfit`, and `tint` columns to `profiles`. Every bot keeps its shape and its color, drawn the new way. Migration `0013_bot_order` adds a `position` column to `profiles`, for the order you drag bots into. Until you do, they keep the order they had. Then update your plugins from **Plugins**: each of fxbot’s shows **Update available** once. Chat rooms 0.3.1 adds a `position` column to its rooms, and Messages 0.1.1 an `asked` column to its conversations, when they update. * **Bots have a new look.** Big dark eyes, soft color, and more shapes: the fourteen you know and eighteen more, such as toast, cat, frog, and ghost. * **A feeling, and things to wear.** Give a bot a feeling, from bright to doubtful, and something for its head, its face, and its body, each cut to fit its shape, in the bot’s own color, black, or white. A blazer on a heart sits as well as a blazer on a circle. * **A bot shows what it’s doing.** It focuses and hops while it works, looks at you and bobs while a call waits on an answer, smiles when it finishes, and sleeps when it has no provider. Its head seems to turn as it watches the pointer, and a click gets a squish and a smile. With reduced motion on, it holds still. * **A new bot screen.** Pick from tabs for **Shape**, **Color**, **Feeling**, **Head**, **Face**, and **Body**, with each choice drawn on your bot, or tap **Surprise me**. It’s the same in first-run setup, on a phone the bot and the tabs stay in view as you scroll, and **Change look** on a bot’s edit page opens it with a **Save look** of its own. * **A bot’s edit page keeps Save in view,** however long the page gets. * **A menu on each bot.** Right-click a bot in the sidebar, or hold it on a phone, to edit it, pin or unpin it, make it the default bot, or delete it. The default bot wears a small star in the sidebar. * **Your own order for bots and rooms.** Drag one in the sidebar to move it, with a mouse, or with a finger after a moment’s hold, so a swipe still scrolls. Pinned bots move among themselves. Chat rooms 0.3.1 orders rooms the same way. * **For plugins:** a page’s `ui` has `useReorder`, the app’s drag to reorder a list. * **Chat rooms 0.3.1, Messages 0.1.1, and Permissions 0.1.1** show each bot’s whole look, and so does Pages. Update them from **Plugins**. * **A bot knows when a request is yours.** When you ask one bot for something and it asks another, the other gets your own words with the message, quoted by fxbot from your chat rather than from the bot’s message, and so does any bot it asks in turn. It can tell the work is yours, and that what it’s asked fits what you said. What it would ask you about first still needs your OK. Messages 0.1.1 does this on 0.6.0 as well. * **Auto asks about what’s risky, not everyday work.** Its reviewer allows editing files, builds, tests, installs, starting services, and the like, whether or not you asked for that step. It asks you before what’s risky, unless you plainly asked for it: deleting what can’t be put back, changing something outside the bot’s own computer, such as a remote API, a deploy, or a push, touching secrets, weakening security, and spending money. It also counts what you asked another bot that passed the work on, which needs fxbot 0.7.0. In Permissions 0.1.1. * **For plugins:** `fx.chats.send` takes `asked`, the owner’s own words a message carries on, and the `message`, `turn.start`, and `turn.end` hooks get it. * **The message box is whole when a chat opens.** With the Messages plugin, a chat opened from the sidebar showed its box’s hint and cursor too low, cut off at the bottom, until you typed. Messages 0.1.1 fixes it on 0.6.0 as well. * **For plugins:** pass a whole bot to `Blob`, as in ``, and it shows what the bot wears and is doing, and an older fxbot ignores what it doesn’t know. `waiting` on a bot is true while a `tool.before` hook’s `{ wait }` holds one of its calls. * **For the SDK:** a `Profile` gains `mood`, `head`, `face`, `outfit`, `tint`, and `waiting`, and `moods`, `heads`, `faces`, `outfits`, and `tints` list what each takes. `shapes` has 32, and `colors` keeps its names with softer values. * **Pages.** A bot writes a report, a guide, or a plan to read outside the chat, from the new `pages` plugin, in **Essentials**. A card in its chat opens the page, and the library keeps it, with every version. When a page needs more than text, such as a chart with filters, the bot writes it in HTML, in a frame of its own. A task list has boxes you tick, and the bot sees them. An HTML page saves what you do on it, a routine can send it new numbers without rewriting it, once you allow it, and a button on a page can draft a message to the bot. * **First-run setup.** A new install walks through plugins, a provider and a model, and a first bot, then opens its chat. It saves each step, so a restart comes back to it, and **Skip for now** is on every step. * **Essentials.** A pack of what most people want from fxbot, at the top of **Browse**, with **Add all**, or **Add the other** few you don’t have. Each plugin in it stays its own. * **fxbot knows which plugins can run on it.** A plugin that needs a newer fxbot says so on its page, and **Add** stays off. A newer version that needs a newer fxbot shows **Needs fxbot** in place of **Update available**, and the one you have keeps running. * **Unsupported.** When a release breaks something a plugin uses, the plugin doesn’t run, its tab says why and how to fix it, and the rest of fxbot starts as usual. Its files, settings, and tables are kept, and an update that fits brings it back. * **Settings warns before an update,** naming the plugins that wouldn’t run on the new release. * **A plugin’s page that fails to load says so** on its tab, where before only the browser’s console knew. * **Each of fxbot’s plugins says the oldest fxbot it runs on,** so they show **Update available** once, with nothing to do but update. * **For plugins:** `fx.library.replace` changes a document in place, unless another bot holds it too or the owner sent it, the `library.removed` hook says an item went, and `app.libraryItem` is a place in an item’s preview. A plugin can be named `pages`, though not have a route at its root. See the [plugin API](/sdk/reference/plugin-api/). * **For the SDK:** `profiles.order(ids)` and `PUT /api/profiles/order` set the sidebar’s order. `Settings` gains `onboarded` and `onboardingStep`, and `UpdateStatus` gains `wontRun`, from `plugins.wontRun(next)`. A plugin gains `unsupported`, its mark can be `{ kind: "needs" }`, a plugin’s preview `unfit` and `needsFxbot`, and a package search `essentials`, with a `note` on each card. * **For plugins:** `minFxbot` in `plugin.json` is the oldest fxbot a plugin runs on, and fxbot publishes what each release broke in [plugin-breaks.json](/plugin-breaks.json). See [Which fxbot it runs on](/sdk/reference/plugin-api/#which-fxbot-it-runs-on). It adds no migration. ## 0.6.0 (2026-11-06) [Section titled “0.6.0 (2026-11-06)”](#060-2026-11-06) **Before upgrading.** Migrations `0009_time_zone` and `0010_turns_at_once` add `time_zone` and `turns_at_once` columns to `settings`. A time zone set in dreams moves to **Settings** › **General**: the first browser to open fxbot sets it there, so check it if yours should be another. * **Choose what each bot can do alone,** from the new permissions plugin, on fxbot’s list. Each bot has a mode: **Ask** asks you before anything but a safe tool, **Auto** has a reviewer model check risky calls against what you said, and **Yolo** runs everything. A call that needs you shows a card above the message box, with the exact action, and **Approve once**, **Always allow**, and **Deny**. A card from work you didn’t start expires after 30 minutes, and the action doesn’t happen. The reviewer can be another provider and model. It adds no core migration. See [Choose what a bot can do alone](/docs/how-to/choose-what-a-bot-can-do-alone/). * **Removing a provider stops what’s running on it.** A turn stuck on a provider could go on calling it with the old key until fxbot restarted, and **Remove** could hang. Now it ends those turns first, deleting a bot ends all its turns, in rooms and routines too, and a key that’s replaced or removed stops working at once. * **A bot stuck on a provider that keeps refusing says so.** A turn that gets only refusals, such as a rate limit, ended up silent for as long as fxbot ran. After 5 minutes it now stops, with the reason in the chat. A slow model that refuses nothing isn’t touched. * **More bots can work at once.** Up to 32 turns run together, up from 4, so four long commands no longer stop your other bots. **Turns at once** in **Settings** › **General** changes it, from the next time fxbot starts. * **Routines,** from the new routines plugin, on fxbot’s list. Ask a bot “every weekday at 8, summarize my calendar”, and it saves a routine, which runs on time in a session of its own with everything the bot has: its computer, MCP servers, skills, memories, and library. It tells you in its chat, with the files it saved, and stays quiet when there’s nothing to say. Each bot’s settings list its routines and their runs, with a switch, **Run now**, **Stop**, and **Remove**, and **Settings** › **Routines** has the limits, such as how long a run takes. See [Give a bot a routine](/docs/how-to/give-a-bot-a-routine/). * **A time zone** in **Settings** › **General**, which the first browser to open fxbot sets, and plugins use. * **Dreams 0.2.0** uses that time zone, in place of a setting of its own. Update it from **Plugins**. * **Bots work together,** from the new messages plugin, on fxbot’s list. A bot messages another with one tool, and the message lands in the other’s own chat, where it joins what the bot is doing or wakes it, so you see the work where it happens. A reply is a message too: a bot can say “got it”, do the work, and send the result. A conversation has a budget of 20 messages, a no-reply message can’t be answered, and **Open conversations**, in **Settings** › **Messages**, shows each conversation as one thread, with **Stop**. It adds no core migration. See [Let bots work together](/docs/how-to/let-bots-work-together/). * **Bots’ messages stay out of your way.** A message between bots is a small pill in the chat, with the bot’s face, such as **2 received, 1 sent · Philly**, that stacks up between what you and the bot say, and opens with a click. What a bot says to you stays in view. * **Tag any bot.** With the messages plugin, `@` in a bot’s chat lists the bots it can reach, and the one you pick is a chip with its face, right in your message, as in a room. The bot then knows exactly which one you mean, even with two of one name. * **A message to a working bot joins what it’s doing.** You no longer wait for a turn to finish: your words reach the bot where it is, and show there in the chat, among its steps. A message waits for a running tool, and a picture of yours ends the turn and runs next. * **Stop in a bot’s chat.** While a bot works and the box is empty, the send button is **Stop**. It doesn’t wait for a running tool, and what you’d sent that the bot hadn’t read runs next. * **`chat_history` has the whole chat.** A bot can now search and read its own thinking and tool calls with their results, in the order they happened, as well as what was said, and each result says who it’s from, so another bot’s words don’t read as yours. Older chats keep what they had: messages. It adds no migration. * **Your messages are readable in every bot’s color.** A bubble keeps the bot’s hue, in a shade dark enough for white text, in place of dark text on mid-tones such as blue and green. * **Each plugin has a tab in Settings.** Everything about a plugin is on one page: its switch, bots, settings, log, updates, and **Remove**, with a plugin’s MCP servers and their tools right there. The pencil on each row in **Plugins** is gone, along with the dialogs it opened: a plugin’s name still opens its page, whose **Settings** goes to its tab. For plugins: `app.settings` now draws at the top of that tab, which every plugin has. * **Computer 0.3.1:** its part of Settings drops a heading its tab now has, a cancelled turn now really stops its command, which went on running until its own timeout, and a page open while fxbot restarts keeps the computer in the bot’s panel. Update it from **Plugins**. * **For plugins:** `fx.timeZone()` answers the owner’s time zone, `fx.bots.on(bot)` says whether the plugin is on for a bot, and `fx.library.list(bot, session)` answers what one chat saved. `fx.chats.send` takes `shown`, what the chat shows in place of the text the model gets, and tool calls and the tool hooks carry the `messageId` of their turn. A plugin in `FXBOT_PLUGIN_DIRS` keeps its MCP servers when fxbot starts again. Before, they came loose from it, showing as plugins of their own, and stayed when it was removed. * **For plugins:** `fx.chats.send` takes `label`, who the chat says a message is from, and `steer`, to join a running turn, and answers `joined`. `fx.chats.cancel(bot)` with no session stops a turn the plugin started in the bot’s own chat. `turn.end` says `cancelled`, and in a bot’s own chat `turn.start` comes when a turn that waited behind another starts. The stream has a `user_message` line for a message that joined a turn. For the SDK, `profiles.stop(id)` and `POST /api/profiles//stop`. * **For plugins:** a `tool.before` hook can answer `{ wait }`, for what takes longer than a hook may, and gets `callId`, `description`, and `safe`. A tool can say it’s `safe`. `fx.models.ask` makes one tool-free request, `fx.chats.ownerSaid` reads what the owner wrote, `app.chat` draws above the message box, and a page’s `ui` has `ModelField` and `NativeSelect`. `app.box` replaces the message box in a bot’s chat, `app.said` draws part of a message, and `app.fold` folds messages into a pill. * **Set up with your AI agent.** The home page offers a line to give your agent, which sets fxbot up from [agent-setup.txt](/agent-setup.txt): it checks the machine, asks before it installs anything, and leaves your keys and sign-ins to you. **Copy all docs**, on each page of the docs, copies them all in one go, and [Set up with your AI agent](/docs/tutorials/set-up-with-an-agent/) lists `llms.txt` and `llms-full.txt`, as the home page’s footer does. * **Reach it over SSH.** [Reach it from other devices](/docs/how-to/reach-it/#over-ssh) has a way in for a machine with no screen. ## 0.5.0 (2026-11-05) [Section titled “0.5.0 (2026-11-05)”](#050-2026-11-05) **Before upgrading.** Migration `0008_default_bot` adds a `default_profile` column to `settings`. The update starts the database container again once, with your data, because its health check changed. On Docker, a start takes about a minute: until your next update on Docker 25 and newer, and always below 25. If `setup.sh` stopped on your machine, run it again. * **A default bot.** Pick one in Settings › General, and launching fxbot opens its chat, where it left off. For the SDK, `Settings` gains `defaultProfile`, and each `Profile` `isDefault`. * **Plugin icons.** Each plugin has an icon of its own, a soft shape on a tinted tile in two hues, drawn from who made it and its name, so it looks the same everywhere: in **Plugins**, in Settings, and in the sidebar. For the SDK, each plugin and card has `iconKey`, and `@fxbot/sdk/client` exports `pluginIcon(key)`, which draws it. A plugin’s `app.nav` button with no `icon` shows the plugin’s icon. * **A plugin directory** at [fxbot.sh/plugins/](/plugins/): the plugins fxbot vets, with a search box, a card each with its icon, and a page each that says what it carries and how to add it. * **Stopping takes 30 seconds at most.** fxbot gives running chats 30 seconds to finish, then exits, and a chat still running goes on where it stopped when it starts again. Before, a reply that never ended kept fxbot from stopping, and in a checkout kept `npm run dev` from restarting its API. Plugins now stay on until the running chats finish, so their tools work to the end. For the SDK, `close()` closes the agents before the plugins and MCP connections. * **Plugins:** each plugin’s row in Installed and Browse shows a line about it under its name: the first sentence of its description, up to 100 characters and two lines. Browse lists only the plugins you haven’t added, and an installed plugin’s name opens its page, as Browse shows one, read from the files it runs, with **Settings** in place of **Add**. For the SDK, `plugins.contents(id)` and `client.plugins.contents(id)` answer an installed package’s page, and a `PackagePreview`’s `source` can be a local folder. * **Settings in tabs:** General, Providers, Memory, Plugins, and About, each at its own address, and a tab for each plugin that draws in Settings, such as Computer. About has the version, updates, and links. * **/fresh starts a chat over,** from the new fresh plugin, on fxbot’s list. `/fresh` and where you want to go, in a bot’s chat, has the bot summarize the chat, keeping what bears on your words, and start a new chat from it with your message. The chat shows a **Started over** card, and the old chat stays above it. See [Start a chat over with /fresh](/docs/how-to/start-fresh/). * **A provider switch** now stops a reply still running in the old chat, and pages open on the bot follow it to the new chat without a reload. A summary that fails gives up after 2 minutes, not 4. * **A computer for a chat room.** The new chat-rooms-computer plugin, on fxbot’s list, gives a room a computer its bots share, taking turns, from a screen button at the top of the room. It needs the computer and chat rooms at 0.3.0: update them from **Plugins**. See [Give a room a computer](/docs/how-to/give-bots-a-computer/#give-a-room-a-computer). * **Computer 0.3.0:** the Computer screen draws an arrow where each bot last pointed, and other plugins can name computers of their own. Its screen is at `/computer/computers/`, and the old address still works. * **Chat rooms 0.3.0:** other plugins can ask which room a session is for, and add to a room’s header. * **Bots dream,** from the new dreams plugin, on fxbot’s list. Each night a bot goes over its day: it saves what’s worth remembering as its own memories, citing the turns they came from, and writes a way of working that worked down as a skill, at most one a night. **Dreams**, in each bot’s settings, is a journal of each change, with **Undo**, and **Dream now**. Its tables are its own: core has no migration for it. See [Let bots dream](/docs/how-to/let-bots-dream/). * **`setup.sh` takes the machine it finds.** It reads the versions of podman, Docker, and Compose, and sets up what’s missing, so it works beside Compose v1 and podman-compose, on Debian 12 and Ubuntu 22.04, and on distros built on Debian or Ubuntu. fxbot needs Compose 2.26 or newer: the machine’s, the distro’s package, or Compose’s own release, which it downloads into `/opt/fxbot` and checks against its hash. Where the distro’s podman is older than 4, it installs Docker. An install that stopped before its first start starts over from the newest release. `fxbot up` now says why it failed, and `fxbot compose` runs Compose on the install’s files. * **A new install works on stock Debian and Ubuntu again.** Their Compose packages refused `start_interval` on podman, and podman’s network parts weren’t installed. `start_interval` moved to `compose.docker.yaml`, which the `fxbot` command adds on Docker 25 and newer. * **fxbot runs on Docker again.** From 0.4.0, the app stopped as it started on Docker, with `uv_os_homedir returned ENOENT`. * **For plugins:** `app.settings` makes a tab, at `/settings/plugins/`. A `message` hook can answer `{ startOver: { ask } }`, to start the bot’s own chat over before the message runs, and `plugin.json` can list `commands` for the `/` list. `fx.provide` and `fx.need` let one plugin use another it names under `needs`, and `app.slot` fills a place another plugin’s page leaves with `Slot`. `fx.memories` reads, saves, and removes a bot’s memories as the bot’s own, and `fx.skills.set` gives one bot skills the plugin writes. `turn.end` carries `error` when the provider answered with an error, too. * **For the SDK:** a chat that starts over ends its streams with a `moved` line naming the new session, and `stream` and `client.stream` take `session`, the session a cursor is in. ## 0.4.1 (2026-11-04) [Section titled “0.4.1 (2026-11-04)”](#041-2026-11-04) * **Chat rooms: tag bots, and let them hand work on.** The chat-rooms plugin goes to 0.2.0; update it from **Plugins**. * **Tagging:** in a room, `@` lists its bots and **Everyone**, and a pick becomes a chip with the bot’s avatar. * **Who answers:** a message wakes the bots it tags. One that tags no one goes to the room’s lead, which can bring others in. * **Handing on:** a bot that tags another hands it the conversation. The room limits bot replies to one message of yours, 10 by default, and **Stop** ends them. * **Skills:** three skills teach bots how to work in a room. * **The sidebar** shows each room’s bots, stacked. * **Rooms made in 0.4.0** keep every bot answering a message that tags no one. * See [Talk with several bots in a room](/docs/how-to/talk-in-a-room/). * **Each computer is named for its bot.** The computer plugin goes to 0.2.2; update it from **Plugins**. Its hostname is the bot’s name and `-computer`, such as `bob-computer`, so bots in a room can tell their computers apart. A computer takes it the next time it starts. * **License notices.** The computer plugin ships the notices of what its page bundles: xterm.js, under MIT, and noVNC, under MPL-2.0, with where noVNC’s source is. Chat rooms ships ProseMirror’s. * **herdr leaves fxbot’s plugins,** to be planned again. It’s off fxbot’s list and out of the repository. An install that added it keeps it as it was, until it’s removed in **Plugins**. * **For plugins:** `fx.chats.cancel` stops a turn running in one of the plugin’s own sessions, and `@fxbot/app` gains React’s `createPortal`. ## 0.4.0 (2026-11-04) [Section titled “0.4.0 (2026-11-04)”](#040-2026-11-04) **Before upgrading.** Migration `0006_plugins` adds a `plugin` column to `sent` and a `plugin_sessions` table. Migration `0007_one_kind_of_plugin` renames the add-ons’ tables: `addons` to `plugins`, `addon_secrets` to `plugin_secrets`, `profile_addons` to `profile_plugins`, and `skills.addon_id` to `plugin_id`. Your MCP servers and skills carry over as plugins. Only the plugins fxbot vets show from now on: to search GitHub’s MCP registry and skills.sh, or add by address or repository, turn on **Show unvetted plugins** in Settings. For SDK users, the add-on calls and routes are renamed: see the last item. Chats move into the database on the first start. fxbot backs up once, before the migrations, into a folder named `-before-0006_plugins`, then copies each chat from `FXBOT_DATA/sessions` into tables of its own, at about 6,000 lines a second, and renames the folder `sessions.moved`. Delete that folder once you’re sure: `sudo rm -r /var/lib/fxbot/data/sessions.moved`. To go back to 0.3, restore that backup: it holds the database before the migrations and the chats’ old files. A chat that can’t be moved stops the start and names it, with its files untouched, and the update goes back to the release before. * **One kind of plugin.** Add-ons are plugins now, with one page, **Plugins**, where the Skills, MCP, and Plugins tabs are one **Browse**. A plugin carries any mix of code, MCP servers, and skills, and each row and card says what it carries. The MCP servers and skills you have show as plugins that carry one thing. * **Vetted by default.** Browse shows fxbot’s picks, tagged **fxbot**. **Show unvetted plugins**, in Settings, adds GitHub’s MCP registry, the official one, skills.sh, adding a server by address, and any plugin on GitHub. While it’s off, fxbot asks none of those, and refuses to add from them. * **Plugins with code.** A plugin’s code runs inside fxbot: it can hook into each message, each chat’s instructions, every tool call, and each turn’s start and end, and add tools, routes, tables of its own, settings, and places in the app, from a screen and a sidebar group to a control beside the message box. Its page shows the code that runs before you add it, and it stays pinned to that commit until you update it. Its MCP servers show in its settings, and follow its switch and its bots. For writing one in a checkout, `FXBOT_PLUGIN_DIRS` loads plugin folders, again each time they change. * **Chat rooms**, fxbot’s first plugin with code: rooms where several of your bots talk with you, each answering every message once, in turn. * **herdr**, its second: bots see the coding agents [herdr](https://herdr.dev) runs, and read what their panes show. * **A computer for each bot**, a plugin: a Linux machine where the bot runs commands, keeps files, and saves what it makes to its library. Computers run in the machine’s own podman or docker, rootless for a user of their own, start on a bot’s first call, and stop when idle; a firewall keeps them to the internet. Two fxbots on one machine share the engine, and each leaves the other’s computers be. See [Give bots a computer](/docs/how-to/give-bots-a-computer/). * **The computer sets itself up.** Adding the computer plugin is all you do: the machine sets up its engine, a rootless podman or docker for a user of its own with a firewall, and starts fxbot again, while Settings shows it working. The machine’s `fxbot` command gains `fxbot computer on|off`, which does it, and the plugin API gains `fx.machine`, through which the plugin asks. A checkout run as root sets up the same way; one run as another user still shows the command. * **A desktop on each computer.** Each bot’s computer has a desktop, with Chromium, a file manager, and a terminal. Its Computer screen shows the desktop live, and the terminal the bot types in. **Take over** gives you the mouse and keyboard, and **Hand back** returns them. A bot that needs you for a sign-in asks with `computer_ask_owner`, and carries on when you hand back. The computer’s new tools: `computer_desktop` clicks, types, and takes screenshots, which show in the reply; `computer_terminal` answers programs that ask; and `computer_write_file` changes one place in a file. Bots drive Chromium with agent-browser, and desktop apps by their accessibility trees with agent-desktop, and the computer’s three skills and a few lines in each chat’s instructions say which to use when. `$computer`, or the screen button beside the message box, points a message at it. A bot’s panel shows its computer’s screen, small and live, above **Details** and **Library**, or **Idle** with a button that starts it. The image grows to about 1.2 GB. * **Plugins that need others.** A plugin’s `plugin.json` can name plugins it needs, each with an object for that one. Its page says so, and Add waits for them; a plugin others need can’t be removed while they’re added. The plugin API gains `fx.dependents()` and its event, `fx.library.read` and `save`, `fx.skills.files`, and `fx.socket`, a WebSocket of the plugin’s own; and on the page, `app.botPanel`, and a composer control’s `setDraft` that takes a function. A plugin at the root of its repository can be added too. * The docs have [Add a plugin](/docs/how-to/add-a-plugin/), and the SDK’s pages [Write a plugin](/sdk/how-to/write-a-plugin/) and the [Plugin API](/sdk/reference/plugin-api/). Core and add-ons is now [Core and plugins](/docs/explanation/core-and-plugins/). * **The docs on Starlight.** fxbot.sh’s docs and the SDK’s pages gain search, and each page **Copy Markdown** and **Open** in ChatGPT or Claude. `llms.txt` lists the pages for models, and `llms-full.txt` has them all in full. * **Health checks every 30 seconds**, not every 3. Each one cost podman about 30 ms of CPU, so an idle install spent about 3% of a core on them. Starts are as quick as before: `fxbot` runs the checks every 2 seconds while it waits. The update to this release, run by the earlier `fxbot`, waits about 30 seconds longer for it to start. * **Chats in the database.** Each chat moves from files into Postgres, through Workflow’s Postgres World, so a long chat costs no more than a short one. On a chat of 25,000 lines, two open pages cost the server about a quarter of a core while nothing happened, and now cost nothing. A message is accepted in about 25 ms instead of 1.2 s, the chat loads in under a second instead of 3, and it takes about a tenth of the disk. The page also closes its stream while it’s hidden, in a background tab, a minimized window, or a locked phone, and catches up when it’s shown. fxbot’s image grows by about 60 MB, for Workflow’s packages. * **A chat opens at its end.** Opening a chat used to scroll through every turn as its lines arrived, for seconds on a phone. It now appears once, whole and at its end, instead of filling in piece by piece, with the newest 20 turns, and 20 earlier ones each time you scroll near the top. The rest of the app appears with it. The chat’s lines are gzipped on the way, about 8 times smaller for a real chat. For the SDK, `client.stream` takes `onCaughtUp`, `fxbot.streamEnd` gives a chat’s newest cursor, and the stream’s `x-fxbot-end` header carries it. * **Memories moved** to the bot’s edit screen, under its settings. The bot’s panel keeps **Details** and **Library**. * The SDK’s `close()` waits for the save of a reply that just finished, so a script can close right after a turn. A reply that can’t be saved, such as one whose bot was just deleted, is logged instead of stopping the process. * **Renamed, for the SDK and the HTTP API.** `fxbot.addons.*` and `client.addons.*` are `fxbot.plugins.*` and `client.plugins.*`. `/api/addons/…` is `/api/plugins/…`, and `/api/profiles/:id/addons/:id` is `/api/profiles/:id/plugins/:id`. The types follow: `Addon` is `Plugin`, `McpAddon` `McpPlugin`, `SkillAddon` `SkillPlugin`, `AddonRef` `PluginRef`, `AddonPreview` `McpPreview`, `AddonCard` `McpCard`, `AddonSearch` `McpSearch`, `AddonSecrets` `PluginSecrets`, `AddonMark` `PluginMark`, `AddonInfo` `RegistryInfo`, `AddonFrom` `RegistryFrom`, and `AddonTool` `McpTool`. Settings gain `unvetted`. ## 0.3.0 (2026-11-02) [Section titled “0.3.0 (2026-11-02)”](#030-2026-11-02) **Before upgrading.** fxbot now runs as containers, and Settings’ Update in 0.1 or 0.2 can’t make that move. Run `setup.sh` again instead, the command under Install: it stops the old service, copies its database into the database container, and starts the containers on the same chats, key, and settings. The old files and database stay until you remove them, and `sudo fxbot status` says how, or how to go back. Migration `0005_memories` adds memories and vectors, and needs pgvector, which the database container has: on the machine’s own Postgres, it stops and says to run `setup.sh`. The local embedder downloads its 310 MB model on its first start, holds about 380 MB, and fills in vectors for existing messages in the background. A checkout moves its database too: see the README’s Run from a checkout. * **Containers.** `setup.sh` installs fxbot as containers, with podman, or docker when only docker is installed: fxbot’s image from ghcr.io, for amd64 and arm64, pgvector’s Postgres image, and the local embedder. It no longer installs Node or the distro’s Postgres. `sudo fxbot` runs them: `status`, `logs`, `update`, `up`, `down`, `restore`, `rotate-key`, and `embedder`. * **Updates through the machine.** Settings’ Update asks the machine, which starts the new release and waits until it answers. If it doesn’t, the old release comes back by itself, on the backup taken before the new one’s migrations, and Settings shows why. The database keeps running, and running chats finish first. * **Memories.** Each bot keeps what it learns: it saves one fact at a time with `memory_save`, finds them with `memory_search`, and removes wrong ones with `memory_forget`, which the chat shows as sentences. The newest are in its instructions on every turn, within 2% of the model’s context window, and the owner sees, adds, edits, and deletes them in the bot panel’s Memories tab. * **Memory search by meaning.** Memory search and `chat_history` match by meaning as well as by words. The vectors come from a local embedder (EmbeddingGemma 2 on the CPU, or Qwen3-Embedding on an NVIDIA GPU), from a provider’s embedding model, or from none, picked in Settings’ Memory search, or with `sudo fxbot embedder`. Chat messages get vectors too, from their first 8,000 characters, which Settings can change or turn off. * `sudo fxbot rotate-key` seals every stored key and token again under a new key, and keeps the old key until you remove it. * A checkout’s database and local embedder run from `deploy/compose.dev.yaml`. `npm run update` is gone: a checkout updates with git. * The server listens on `FXBOT_HOST`, 127.0.0.1 by default. * fxbot reads its own lists of MCP servers and skills from its site, , every hour, so new picks show up between releases. Before, it read them only with `FXBOT_LISTS_URL` set, which now points it at another site. * The website’s top bar and the README link to the Hackers in the Loop community on [Discord](https://discord.gg/3Qs2uejUf9). ## 0.2.1 (2026-11-02) [Section titled “0.2.1 (2026-11-02)”](#021-2026-11-02) A website release. The app is the same as 0.2.0. * A link to fxbot.sh shares as a preview card, with the bots, the heading, and the site’s address. * Each page of the site names its canonical address and has Open Graph and Twitter tags. The site has a sitemap and a `robots.txt`, and its link check covers them. ## 0.2.0 (2026-11-02) [Section titled “0.2.0 (2026-11-02)”](#020-2026-11-02) **Before upgrading.** Migration `0002_model_lists` adds a table that keeps each provider’s model list, `0003_registry_entries` adds two that keep a copy of GitHub’s MCP registry, and `0004_skills` adds one for skills. Chats and add-ons carry on. * **Skills.** Bots use [Agent Skills](https://agentskills.io): instructions for a kind of task, read only when a task needs them. The Add-ons page’s Skills tab lists fxbot’s own picks (show-me, frontend-design, and grilling), tagged **fxbot**, and searches skills.sh, tagged **skills.sh**. A skill installs as skills.sh installs it, from its GitHub repository at the commit its page showed. Each bot’s instructions list its skills, within 1% of the model’s context window, and a `skill` tool reads one, which the chat shows as “Read a skill”. In a chat, `$`, or `/` at the start, lists the bot’s skills: the one picked goes with the message as a chip, so the bot has it without deciding to. Skills go to all bots or chosen ones, like MCP servers, and are marked **Update available** when their files change upstream. Nothing in a skill runs. * The Add-ons page is a search above four tabs: Installed, Skills, MCP, and Plugins. MCP searches GitHub’s MCP registry, which fxbot mirrors every hour, and **Search everything** adds the official registry’s unmoderated results. Each entry opens on a page that shows its host (in red when it isn’t on the publisher’s domain), how it signs in, the keys it needs, and where it comes from, before **Add**. Adding by address is still there, under MCP. Plugins says they aren’t in fxbot yet. * fxbot ships with its own list of MCP servers, starting with alphaXiv and Keiro, tagged **fxbot** and listed first. With `FXBOT_LISTS_URL` set to the site that publishes it (the website’s `mcp-registry.json`, beside `skills-registry.json`), fxbot reads it every hour, so the lists can grow between releases. Other cards are tagged **GitHub registry** or **Official registry**, and a server on more than one shows once, as fxbot’s. * An installed server from a registry is marked **Update available**, **Deprecated**, or **Removed from the registry**, and nothing changes by itself. **Update to** shows what the newer version changes, and moves only on **Update**. * Past 40 tools reaching the bots, the Add-ons page says how many. * A server still connecting when fxbot stops no longer writes to the database after it closes. * Model lists outlast restarts. fxbot keeps each provider’s list in Postgres and answers with it at once, fetching a fresh one behind the answer when it is over 5 minutes old; a failed refresh keeps the old list ([#5](https://github.com/iammrduncan/fxbot/issues/5)). * The chat shows how each reply came about, in order: thinking, tool calls, and text between them. A tool call reads as a sentence, such as “Searched the library” or “Ran linear_create_issue”, and opens on its input and result; a failed one says so in red. Two or more steps in a row fold under one line, such as “Thought and used 2 tools”, open while the bot works. Before, tool calls didn’t show at all, and the thinking showed as one block. * The model field is a picker that opens on the provider’s whole list, the current model marked, and narrows as you type. Before, the browser’s suggestions showed only the model already chosen. A model id the list lacks can still be typed in, and Clear empties the field. * `setup.sh` stops, and says why, when another fxbot already holds its names: a database `fxbot`, a key in `/etc/fxbot`, or port 8787. * A checkout’s `npm run dev` runs its API on port 8788, so it runs beside a release install on one machine. * The README shows how to serve fxbot at its own tailnet name, such as `bot..ts.net`, as a Tailscale Service. * fxbot has a website with its docs, in `packages/website`. `npm run build-site` builds it into `out/` and checks its links. ## 0.1.0 (2026-11-02) [Section titled “0.1.0 (2026-11-02)”](#010-2026-11-02) The first release. * **Bots and chats.** Bots drawn as animated blobs, each with a streaming chat that survives reloads and restarts, image and text attachments, and a `chat_history` tool that searches its own past. * **Providers.** ChatGPT, Grok, and Vercel accounts by device code, API keys, and local model servers, with every key and token sealed in Postgres. * **The library.** Every file the chats hold, searchable, for people and bots. * **An installable app** for phones and desktops. * **MCP servers.** Tools from any remote MCP server, signed in with OAuth or a key, for all bots or chosen ones, with only the tools you allow. * **Releases.** `setup.sh` installs a release, and Settings or `npm run update` moves to the next one. The database migrates forward, with a backup first. Each release is also on [GitHub Releases](https://github.com/iammrduncan/fxbot/releases), with a short version of its section here. # Commands > The commands for an install: setup.sh, the machine's fxbot command, and a checkout's npm scripts. ## setup.sh [Section titled “setup.sh”](#setupsh) ```sh curl -fsSL https://fxbot.sh/setup.sh | sudo bash curl -fsSL https://fxbot.sh/setup.sh | sudo bash -s -- curl -fsSL https://fxbot.sh/setup.sh | sudo FXBOT_PORT=8780 bash ``` Installs fxbot as containers, as root, through whichever of apt, dnf, zypper, or pacman the machine has. It reads the versions the machine has, and sets up what’s missing. **It checks first,** and stops before it changes anything, with what to do, when: * the system isn’t Linux, such as macOS or Windows * the machine has none of the four package managers, or installs software as a whole image (Fedora Silverblue or CoreOS, openSUSE MicroOS) * it runs without systemd * its CPU isn’t x86_64 or arm64 * another program listens on the port * `docker` is a snap * `/var/lib` has under 3 GB free, for a new install * pacman has no package lists With under 1 GB of memory free, it says so and carries on. [Fix an install that stopped](/docs/how-to/fix-an-install/) has each stop and its fix. **The engine,** for a new install, is the first of: 1. `FXBOT_ENGINE`, when set 2. a Docker that’s running 3. podman 4 or newer, when it’s installed 4. a Docker that’s installed, which it starts 5. podman from the distribution, when it has 4.9 or newer, so the computer can run on it too 6. Docker’s own `docker-ce`, from Docker’s repository, with its signing key checked against its SHA-256, on Debian, Ubuntu, and the distros built on them An install keeps the engine it has. `setup.sh` never installs Ubuntu’s `docker.io`, which can’t also run the computer. A `docker` from `podman-docker` counts as podman. When the engine is docker and no Docker is installed, it installs `docker-ce` on apt. **Compose:** 2.26 or newer. When the machine’s is older, or is v1, or `podman compose` would run one of those, it installs the distribution’s package if that’s new enough, and otherwise downloads Compose’s own release into `/opt/fxbot` and checks it against its hash. podman-compose isn’t used: it can’t wait for health. **The images** download before fxbot starts, showing Compose’s own progress. What it creates is in [What setup.sh creates](/docs/reference/install-layout/). | Input | What it is | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `` | The release to install, such as `v0.3.0`. Default: the newest stable release. A prerelease installs only by name. | | `FXBOT_ENGINE` | `podman` or `docker`, for a new install. | | `FXBOT_PORT` | The port fxbot listens on, on the machine’s loopback, for a new install. Default 8787. It’s kept in `/opt/fxbot/.env`. | | `FXBOT_FILES` | Where each release’s `deploy/` files are downloaded from, by tag. Default `https://raw.githubusercontent.com/iammrduncan/fxbot` | | `FXBOT_IMAGE` | The app’s image, without its tag. Default `ghcr.io/iammrduncan/fxbot` | | `FXBOT_RELEASES_URL` | Where the newest release is read, in the shape of GitHub’s `releases/latest`. Default `https://api.github.com/repos/iammrduncan/fxbot/releases/latest` | | `FXBOT_COMPOSE_FILES` | Where Compose’s own release is downloaded from, when the machine needs it. Default `https://github.com/docker/compose/releases/download` | | `FXBOT_DOCKER_FILES` | Where Docker’s repository is, when it installs `docker-ce`. Default `https://download.docker.com` | `FXBOT_FILES`, `FXBOT_IMAGE`, and `FXBOT_RELEASES_URL` point an install at a fork or a mirror. When set, they are kept in `/opt/fxbot/.env`, for updates. * Run again, it finishes an install that stopped, and leaves a working one alone, on the release it has. An install that stopped before its first start has nothing to keep, so it starts over from the newest release, with its old settings left as `/opt/fxbot/.env.stopped`. * With `/opt/fxbot` gone but the database’s volume still there, it starts on that database, with the key left in `/etc/fxbot`. * On an install of 0.2, it moves it into containers: see [Update from 0.2](/docs/how-to/update/#from-02). * Each package it installs, and Docker’s repository’s files when it adds them, go in `/etc/fxbot/packages`, which `fxbot uninstall` names. * apt can remove a package to install another. When it would, `setup.sh` stops instead. ### Where it runs [Section titled “Where it runs”](#where-it-runs) Each checked with a fresh install, its lifecycle, and the computer: | Distro | Packages | fxbot runs on | The computer runs on | | ------------------------------- | -------- | -------------------------------------- | -------------------- | | Debian 13 | apt | podman 5.4 | rootless podman | | Debian 12 | apt | Docker’s own `docker-ce` | rootless `docker-ce` | | Ubuntu 24.04 | apt | podman 4.9, or the Docker that’s there | rootless podman | | Ubuntu 22.04 | apt | Docker’s own `docker-ce` | rootless `docker-ce` | | Fedora 45 | dnf | podman 6.1 | rootless podman | | AlmaLinux 9 and 10 | dnf | podman 5.8 | rootless podman | | openSUSE Tumbleweed and Leap 16 | zypper | podman 6.1 and 5.4 | rootless podman | | Arch | pacman | podman 6.1 | rootless podman | The distros built on them install the same way, through the same package manager. ## fxbot [Section titled “fxbot”](#fxbot) The command for an install made by `setup.sh`: `/opt/fxbot/fxbot`, linked as `/usr/local/bin/fxbot`. Run it as root. It runs `podman compose` or `docker compose`, as `FXBOT_ENGINE` in `/opt/fxbot/.env` says, in `/opt/fxbot`, or the binary `FXBOT_COMPOSE` names there, when `setup.sh` found those too old. | Command | What it does | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sudo fxbot status` | The version, the engine, the local embedder, whether fxbot answers, and the containers. After a move from 0.2, it also prints the commands that remove what 0.2 left. | | `sudo fxbot logs []` | The containers’ last 100 lines, followed in a terminal. Piped, as an agent runs it, it prints them and ends. `` is `fxbot`, `db`, or `embed`. | | `sudo fxbot compose ` | Compose itself, on this install’s files, with its engine and profile, such as `sudo fxbot compose ps`. | | `sudo fxbot update []` | Moves to the newest stable release, or the one named. See below. | | `sudo fxbot up` | Starts the containers, and waits up to 5 minutes until the app is healthy. The embedder may still be downloading its model. `fxbot.service` runs it at boot. | | `sudo fxbot down` | Stops and removes the containers. The database’s volume stays. | | `sudo fxbot apply` | Carries out the app’s requests in `/var/lib/fxbot/control/requests`. `fxbot-control.service` runs it. | | `sudo fxbot backup []` | Backs up the database and the data folder. See below. | | `sudo fxbot restore ` | Puts a backup in place of the database, and unpacks its data folder. See below. | | `sudo fxbot rotate-key` | Seals every stored secret again under a new key. See below. | | `sudo fxbot embedder cpu\|gpu\|off` | Runs memory search’s local embedder on the CPU, on a GPU, or not at all. See below. | | `sudo fxbot computer on\|off` | Sets up the computer plugin’s engine, or takes it away. See below. | | `sudo fxbot uninstall [--purge] [--yes]` | Takes fxbot off the machine. See below. | ### fxbot update [Section titled “fxbot update”](#fxbot-update) Moves to the newest stable release, or the one named, such as `0.3.1` or `0.4.0-rc.1`. In order, it: 1. downloads the release’s `compose.yaml`, its GPU file for the engine, its `fxbot` command, and on Docker its `compose.docker.yaml`, and pulls the images it doesn’t have yet 2. writes the new version into `/opt/fxbot/.env`, and puts the new files in place 3. recreates the containers that changed, and waits up to 5 minutes for the app to be healthy. The new app backs up and migrates the database as it starts. Running chats get 30 seconds to finish, and one still running goes on in the new release. The database keeps running. Each step goes to `/var/lib/fxbot/control/status.json`, which Settings shows. Another update waits for the one running. It refuses, and changes nothing, when: * the version isn’t one such as `0.3.0` * the release is the running one, or older (going back is a [restore](/docs/how-to/go-back/)) * a file or an image doesn’t download If the new app isn’t healthy in time, it goes back to the old compose file, command, and version, and, when the new release ran migrations, restores the backup taken before them. Settings then shows why, from the new app’s last log lines. Once the new release runs, it removes the images the old release’s compose files named and the new one’s don’t. After a failed update, it keeps them. ### fxbot backup [Section titled “fxbot backup”](#fxbot-backup) ```sh sudo fxbot backup ~/fxbot-backup ``` Stops the app, writes the database as `database.dump`, in pg_dump’s custom format, and the data folder as `data.tar.gz` into the folder, and starts the app again if it was running. With no folder, it’s `/var/lib/fxbot/backups/-by-hand`, where fxbot keeps only the five newest. A folder elsewhere belongs to the user who ran `sudo`. `fxbot restore` takes the folder as it is. Keep `/etc/fxbot/secret.key` apart from it: the backup’s keys and tokens open only with that key. See [Back up fxbot](/docs/how-to/back-up/). ### fxbot restore [Section titled “fxbot restore”](#fxbot-restore) ```sh sudo fxbot restore /var/lib/fxbot/backups/-before- ``` Stops the app, starts the database if it isn’t running, drops the database, and makes it again from the folder’s `database.dump`. When the folder has a `data.tar.gz`, it unpacks it into `/var/lib/fxbot/data`. `sudo fxbot up` then starts the app. A relative folder is taken from where you run the command. ### fxbot rotate-key [Section titled “fxbot rotate-key”](#fxbot-rotate-key) Seals every stored key and token again, providers’ and MCP servers’ alike, under a new key, for when the old one may have leaked. It stops the app, makes a new `/etc/fxbot/secret.key`, seals everything again in one transaction, and starts the app. The old key stays beside it as `/etc/fxbot/secret.key.old`: remove it once fxbot works. If sealing fails, nothing changes, and the old key still works. ### fxbot embedder [Section titled “fxbot embedder”](#fxbot-embedder) ```sh sudo fxbot embedder gpu ``` Runs the local embedder for memory search on the CPU (`cpu`), on an NVIDIA GPU (`gpu`), or not at all (`off`), and writes the choice into `/opt/fxbot/.env` as `FXBOT_EMBEDDER`. For `gpu`, it first makes a trial run, `nvidia-smi` in llama.cpp’s CUDA image with the GPU, and changes nothing when no GPU answers. Then it recreates the `embed` container on the new compose files, or, for `off`, removes it. Its state goes to `/var/lib/fxbot/control/embedder-status.json`, which Settings shows. **Memory search**, in Settings › Memory, asks for the same through a request, which `fxbot apply` carries out. It changes what the machine runs, not where the app takes its vectors from: after `off`, pick **Off** in Settings as well. A new embedder is a new model, so the app gives every memory and message a new vector. See [Choose where memory search’s vectors come from](/docs/how-to/memory-search/). ### fxbot computer [Section titled “fxbot computer”](#fxbot-computer) ```sh sudo fxbot computer off ``` Sets up the [computer](/docs/reference/computer/) plugin’s engine (`on`), or takes it away (`off`). It downloads the computer’s setup script from the running release’s own files into `/opt/fxbot/computer-setup.sh`, and runs it: `on` makes the `fxbot-computer` user, its rootless engine, and the firewall, and gives fxbot’s container the engine’s socket; `off` removes them, with every computer and its home. Either starts fxbot again. Its state goes to `/var/lib/fxbot/control/computer-status.json`, which **Settings** › **Computer** shows. Adding the computer plugin asks for `on` through a request, which `fxbot apply` carries out, so you don’t run it yourself. Remove the plugin before `off`, or it asks again when fxbot starts. ### fxbot uninstall [Section titled “fxbot uninstall”](#fxbot-uninstall) ```sh sudo fxbot uninstall sudo fxbot uninstall --purge ``` Says what it removes and keeps, then asks once, `[y/N]`. With **y**, it stops `fxbot-control.path`, backs up into `/var/lib/fxbot/backups/-uninstall`, takes the computer away with its saved setup script (no network needed), and removes the units, the containers, the volumes, fxbot’s images at every version, ufw’s rules marked `fxbot`, `/opt/fxbot`, and the `fxbot` command. It keeps the backup, `/etc/fxbot` with the key, and the user `fxbot`, so `setup.sh` and `fxbot restore` bring it back. A failed backup stops it before it removes anything. | Option | What it does | | --------- | -------------------------------------------------------------------------------------- | | `--purge` | Takes no backup, and also removes `/var/lib/fxbot`, `/etc/fxbot`, and the user `fxbot` | | `--yes` | Asks nothing. With no terminal and no `--yes`, it stops. | It never removes podman, Docker, their other containers, or the packages `setup.sh` installed: it names those, from `/etc/fxbot/packages`, with the package manager’s command to remove them. Run again after one that stopped partway, it finishes. See [Uninstall fxbot](/docs/how-to/uninstall/). ## npm scripts [Section titled “npm scripts”](#npm-scripts) Run from a checkout’s root. | Command | What it does | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `npm run dev` | Vite on `127.0.0.1:5173`, with the API on 8788, or on `FXBOT_PORT` when the shell sets it. The API restarts when the server or the SDK changes. | | `npm run server` | The API and the last build of the page, on `FXBOT_HOST` (default `127.0.0.1`) at `FXBOT_PORT` (default 8787) | | `npm run prod` | `npm run build`, then `npm run server` | | `npm run build` | Builds the page and its service worker into `packages/ui/dist/` | | `npm run typecheck` | `tsc --noEmit` in each workspace | | `npm run build-site` | Builds this site into `out/`, and checks its links | | `npm run rotate-key -- ` | Seals every stored secret again under a new key. See below. | The API that `npm run dev`, `npm run server`, and `npm run prod` start, and `npm run rotate-key`, read `.env` in the repository root when it exists. ### npm run rotate-key [Section titled “npm run rotate-key”](#npm-run-rotate-key) For a checkout; a release install uses [`fxbot rotate-key`](#fxbot-rotate-key). Seals every stored key and token again, providers’ and MCP servers’ alike, under the key in ``: 32 random bytes in base64, such as `openssl rand -base64 32` makes. It reads `FXBOT_DATABASE_URL`, and `FXBOT_SECRET_KEY_FILE` for the old key. Stop the server first, and afterwards point `FXBOT_SECRET_KEY_FILE` at the new file. # The computer > The computer plugin's tools, skills, desktop, settings, setup, and image, and what a computer reaches. The computer plugin’s tools, skills, desktop, settings, setup, and image, and what a computer reaches. To add it, see [Give bots a computer](/docs/how-to/give-bots-a-computer/). ## Tools [Section titled “Tools”](#tools) Bots the plugin is on for get seven tools. A relative path starts at `/root`. | Tool | Input | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `computer_shell` | `command`, and `timeout` in seconds: 120 unless given, 600 at most | Runs one bash command in a new shell in `/root`, and answers `exit ` and its output. A command still running at its timeout is stopped, with its process group, and the output says so. It reaches the desktop, so `agent-browser` and `agent-desktop` work from it. | | `computer_terminal` | `text`, typed as is; `keys`, named, such as `Enter`, `Tab`, `Escape`, `Up`, or `C-c`; `wait`, in seconds: 1 unless given, 30 at most | Sends them to the terminal, the tmux session `main`, waits, and answers its last 200 lines. For a program that asks and waits: a REPL, an installer’s prompts, `ssh`, `top` | | `computer_desktop` | `action`, and what it needs, below | One action on the screen, then a screenshot | | `computer_read_file` | `path`, `offset` (the first line, from 1), `limit` (lines, up to 2,000) | Text, 2,000 lines or 60 KB at a time, saying where the next part starts. An image (PNG, JPEG, GIF, or WebP, up to 3.75 MiB) comes back as an image, which the bot sees. | | `computer_write_file` | `path`, and `text` (up to 1 MiB) or `library` (a `library:`); or `old_text` and `new_text` | Writes the text, or the library item’s bytes, making the folders it needs. With `old_text`, which must be in the file exactly once, changes that one place to `new_text`. Either way, a file that was there keeps its mode. | | `computer_to_library` | `path`, and `name` | Saves an image (up to 3.75 MiB) or a text file (up to 1 MiB) to the bot’s library, tagged for the chat, and answers its `library:` | | `computer_ask_owner` | `reason`, in one line | Hands the desktop to the owner for a step only they can do, as **Take over** does, and shows them the reason | `computer_desktop`’s actions, in the screenshot’s own pixels: | `action` | Needs | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `screenshot`, `cursor_position` | Nothing | | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click` | `coordinate`, `[x, y]`, or the cursor where it is; `text` for keys held during the click, such as `shift` or `ctrl+shift` | | `mouse_move` | `coordinate` | | `left_click_drag` | `start_coordinate` and `coordinate` | | `scroll` | `scroll_direction`, `up`, `down`, `left`, or `right`; `scroll_amount`, 3 unless given; `coordinate` | | `type` | `text` | | `key` | `text`, a key or combination, such as `Return` or `ctrl+l` | | `wait` | `duration` in seconds, 1 unless given, 30 at most | | `zoom` | `region`, `[x1, y1, x2, y2]`: that part of the screen at its own size | Each answer says what it did, the screen’s size, the active window’s title, and the cursor, with the screenshot, a PNG, or a JPEG when a PNG would be over 3.75 MiB. `screenshot: false` leaves out the image. A model that can’t see images gets the text, and libfx’s note that the image wasn’t sent. In a reply, a `computer_desktop` call shows its screenshot; fxbot keeps each bot’s last 50 in memory, so a reply from before fxbot restarted shows its text only. While the owner has a computer, after **Take over** or `computer_ask_owner`, `computer_desktop` and `computer_terminal` answer that the owner has it. The shell and file tools go on. When the owner hands back after the bot asked, the bot’s chat gets a message from the computer, and the bot’s turn starts again. * **Long output.** Output over 60 KiB comes back as its first 4 KiB and last 56 KiB, with a line saying how much was cut, and where the whole of it is, in `/tmp/fxbot/`. A tool’s result can be at most 64 KiB. * **Servers.** A command started with `setsid cmd > log 2>&1 &` keeps running after its call, until the computer stops. * **Calls at once.** A reply’s shell commands run one at a time, and its reads and writes run together. Different actors’ calls, such as a bot’s subagents’, run at once. * **Skills.** When a bot reads a skill with files besides `SKILL.md`, its files are copied to `/skills//` on the bot’s computer before its next call, and the skill’s text says so. ## Skills and instructions [Section titled “Skills and instructions”](#skills-and-instructions) Each chat of a bot the computer is on for has a few lines in its instructions: which part of the computer to use for what, cheapest first, and to ask the owner before it sends, buys, signs in, or deletes. Other bots’ chats have none. The plugin has three skills: | Skill | What it covers | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `computer` | Which tool for which job, and how to act on a screen and check what happened. `$computer` in a message, or the screen button beside the message box, sends it with the message. | | `browser` | Web pages with `agent-browser` 0.41.1, the version on the computer: how to open, read, fill, click, wait, and take screenshots, what to leave as it is on this computer, and what to do when a step fails. `agent-browser skills get core` has the rest. | | `desktop` | Desktop apps with `agent-desktop` 1.1.0, by their accessibility trees: the commands, refs, when it’s safe to try a step again, and when to use `computer_desktop` instead. `agent-desktop skills get desktop` has the rest. | ## The desktop [Section titled “The desktop”](#the-desktop) Each computer is named for its bot, as its hostname, such as `bob-computer`, and runs a desktop: XFCE on an X display, `:1`, with a panel, the Thunar file manager, Chromium, and a terminal window on the tmux session `main`. Its VNC server listens on a unix socket in the computer, `/tmp/fxbot/vnc.sock`, and no computer listens on a TCP port. * **The Computer screen**, `/computer/computers/`, shows the desktop through [noVNC](https://novnc.com) and the terminal through [xterm.js](https://xtermjs.org), over WebSockets at `/api/plugins/computer/desktop/` and `/api/plugins/computer/terminal/`. A bot’s key is its id, and `/computer/bots/`, from before 0.3.0, opens the same screen. The desktop is view-only until **Take over**; the terminal takes typing always. For a stopped computer, the screen has **Start it**. * **Cursors.** Over the desktop, each bot, or each of a bot’s labelled sessions, that pointed at something has an arrow in its colour, with its name, what it last did, and how long ago. The newest is solid, and the others faded. A bot that last used the browser or an app’s accessibility tree, which move no pointer, shows as a label at the top left. They come from `computer_desktop`’s clicks, moves, drags, and scrolls, kept in memory, and cleared when the computer stops or is reset. Since 0.3.0. * **The browser** is Chromium, run as root without its sandbox, with its profile in `/root/.config/chromium`, so sign-ins last. The `agent-browser` command starts it on the desktop when it isn’t running, brings its window to the front, and drives it over DevTools on `127.0.0.1:9222`, inside the computer. * **A bot’s sessions at once,** such as its [subagents](/docs/how-to/hand-work-to-subagents/), since 0.4.0. A session a plugin labelled is an actor of its own on the bot’s computer, named “ · ”, such as “Ann · Curie”: * Its arrow and its pill carry that name, and a `computer_desktop` result names the others while more than one of the bot’s actors has used the computer in the last 10 minutes. * **Turns at the desktop and the terminal.** An actor holds each from its call until 20 seconds after its last, or its turn’s end. Another actor’s call waits for its turn, up to a minute, then answers “Ann · Curie is using the desktop…”. A room’s bots take turns already, so they never wait. * **A tab each.** Its `computer_shell` calls get `AGENT_BROWSER_SESSION`, a name of its own, and `AGENT_BROWSER_PIN_TAB=1`, so its agent-browser commands stay on a tab of their own, which no one else’s take, with the bot’s sign-ins. * **The shell** runs every actor’s calls at once. * **Accessibility** is on for every app, so `agent-desktop` reads their trees. * **Fonts** are DejaVu and Noto, which cover most scripts, but not Chinese, Japanese, Korean, or color emoji. ## A computer for another plugin [Section titled “A computer for another plugin”](#a-computer-for-another-plugin) Since computer 0.3.0, a plugin that needs the computer can name computers of its own, such as [a room’s](/docs/how-to/give-bots-a-computer/#give-a-room-a-computer). Each is named by a key, a word, a dash, and more, such as `room-1a2b3c4d`, which a bot’s id never is. The plugin provides, with `fx.provide`: ```ts type ComputerProvider = { /** The computer for a chat, or null for the bot's own. `name` makes its hostname: `-computer`. */ computerFor(call: { bot: string; session: string }): Promise<{ key: string; name: string } | null>; /** Every computer it keeps, with its name; null while it can't tell. */ computers(): Promise<{ key: string; name: string }[] | null>; }; ``` * **Which computer a call uses.** Before each call, the computer asks each such plugin, in turn, for the chat the call is in. The first that names one wins; otherwise the bot’s own is used. * **Its container and home** are `fxbot-computer-`, labelled `fxbot.by=`. * **Keeping it.** A plugin’s computer goes when that plugin is removed, or when it runs and its `computers()` doesn’t list the key. One added but not running, or whose `computers()` answers null, keeps its own. * **Shared.** The bots it names it for share it, taking turns. A `computer_desktop` result there says where the others last pointed: “Others on this computer: Ann clicked (412, 300) 2 min ago.” **Take over** pauses every bot’s desktop and terminal tools on it, and **Hand back** sends nothing: the owner tells the bot that asked to go on. * **Routes,** under `/api/plugins/computer/computers//`, for the page: `state`, `cursors`, `start`, `stop`, `reset`, and `takeover`. A key no running plugin lists, and no bot’s id, gets 404. ## Settings [Section titled “Settings”](#settings) On its tab in **Settings**: | Setting | Default | What it is | | ------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `engine` | `/run/fxbot-computer/engine.sock`, then `/var/lib/fxbot-computer/run/engine.sock` | The engine’s socket | | `memoryMiB` | 2048 | Memory for each computer, in MiB | | `cpus` | 2 | CPUs for each computer | | `idleMinutes` | 15 | Minutes without a call before a computer stops. One someone watches doesn’t stop. | | `screen` | `1280x800` | The desktop’s size, width x height in pixels | Each computer also has at most 512 processes, and 512 MiB of shared memory for browsers. A computer made with other sizes, or another screen, is made again with the new ones when it next starts; its home stays. ## The setup [Section titled “The setup”](#the-setup) The computer’s engine is set up by `host/setup.sh`, in the plugin’s files, run as root. When the plugin loads and finds no engine, it has the script run, once each time fxbot starts: | fxbot runs | Who runs the script | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | From a release install | The machine’s `fxbot` command, with `fxbot computer on`, which the plugin asks for through fxbot’s requests. It runs the script from the release’s own files, not the plugin’s folder, then starts fxbot again. | | From a checkout, as root | The plugin, with `--user root` | | From a checkout, as another user | Nobody: **Settings** › **Computer** shows the command, to run as root | **Settings** › **Computer** shows the setup while it works, and why it failed, with **Try again**. `FXBOT_COMPUTER_NAME` names another user than `fxbot-computer`, for checks beside a real install. The script’s options, for running it by hand: | Option | What it does | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | none | A release install in `/opt/fxbot`, and `compose.computer.yaml` there, which gives fxbot’s container the socket’s folder and the user’s group. Before 0.3.2 it wrote `compose.override.yaml`: it takes its own lines out of that, and leaves yours. | | `--user ` | A checkout: `` joins the user’s group, to reach the socket | | `--engine podman` or `--engine docker` | This engine. Otherwise the one the user already runs rootless; then podman, when the distribution has 4.9 or newer; then the machine’s own Docker, when its packages run it rootless | | `--name ` | Another user than `fxbot-computer` | | `--install ` | Another release install than `/opt/fxbot` | | `--remove` | Takes it all away: the user, its computers and files, the firewall, and `compose.computer.yaml`. The packages stay. | What it sets up: | Thing | Where | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Packages | Through apt, dnf, zypper, or pacman, each listed in `/etc/fxbot/packages`: `nftables`, and `curl` and `util-linux` when they’re missing; on apt, `uidmap` and `dbus-user-session`; with podman, `podman` and `passt`, and `slirp4netns` for podman 4; with docker, `docker-ce-rootless-extras` beside Docker’s `docker-ce`, `rootlesskit` beside Debian’s `docker.io`, `moby-engine-rootless-extras` beside Fedora’s `moby-engine`, or `docker-rootless-extras` beside openSUSE’s `docker`, and `slirp4netns`; where SELinux runs, `policycoreutils-python-utils` | | The user | `fxbot-computer`, home `/var/lib/fxbot-computer`, 65,536 subordinate ids, lingering on | | Limits | `/etc/systemd/system/user@.service.d/fxbot-computer.conf` delegates cpu, memory, and pids to it | | The engine | Its socket at `/var/lib/fxbot-computer/run/engine.sock`. Podman starts when called and stops 5 seconds after; Docker’s rootless daemon runs all the time, and holds about 180 MB. | | The firewall | `/etc/fxbot/fxbot-computer.nft`, loaded at boot by `fxbot-computer-firewall.service` | | SELinux | Where it runs, podman’s storage in the user’s home takes `/var/lib/containers`’ labels (`semanage fcontext -e`), and fxbot’s container runs with its labels off, to reach the socket | It stops before it changes anything when the machine runs cgroups v1, without which the limits would do nothing, or keeps its users from making user namespaces. Where podman is older than 4.9 and Docker can’t run rootless, as with Ubuntu 22.04’s `docker.io`, it stops with the fix: [Fix an install that stopped](/docs/how-to/fix-an-install/#the-computer). ## What a computer reaches [Section titled “What a computer reaches”](#what-a-computer-reaches) The firewall matches the connections of the user `fxbot-computer`, which are every connection its computers make. | Reached | Refused | | ------------------------------------ | ---------------------------------------------------------------------------------------------------- | | The internet | This machine, at any of its addresses | | DNS, through the machine’s resolvers | Its tailnet, `100.64.0.0/10` and `fc00::/7` | | | Private networks: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, and `fe80::/10` | | | Loopback, multicast, and fxbot’s containers | A refused connection fails at once. To let a computer reach one address on your network, add a rule before the others in the `computers` chain of `/etc/fxbot/fxbot-computer.nft`, such as `ip daddr 192.168.1.20 tcp dport 8080 accept`, then run `sudo systemctl restart fxbot-computer-firewall`. ## The image [Section titled “The image”](#the-image) Every computer runs from one image, `localhost/fxbot-computer:-`, about 1.2 GB, made from Debian 13 slim with: * `ca-certificates curl git python3 procps ripgrep jq unzip xz-utils` * the desktop: TigerVNC’s `Xvnc`, XFCE, Thunar, `xfce4-terminal`, `tmux`, `xdotool`, `scrot`, and the accessibility bus * `chromium`, and fonts: DejaVu and Noto * [agent-desktop](https://github.com/vercel-labs/agent-desktop) 1.1.0 and [agent-browser](https://github.com/vercel-labs/agent-browser) 0.41.1, each checked against its SHA-256 A running computer holds about 120 MB at idle, and about 330 MB with a page open in Chromium. **Two fxbots on one machine,** such as a checkout beside a release, share the engine. Each labels the computers, homes, and images it makes with an id of its own, kept in the plugin’s table, and lists, stops, deletes, and prunes only its own. A computer another fxbot made for a bot is left alone, and a call for it says so. A plugin that needs the computer adds setup steps, which run as root with the network, in name order, after the computer’s own. The computer’s files go in last, so a step can’t replace them. The image is made again in the background when such a plugin is added, updated, or removed; a running computer moves to it the next time it starts. An image no computer uses is removed. # Configuration > fxbot's server reads its settings from environment variables. The key that seals secrets is a file, named by FXBOT_SECRET_KEY_FILE. fxbot’s server reads its settings from environment variables. The key that seals secrets is a file, named by `FXBOT_SECRET_KEY_FILE`. ## Where they are set [Section titled “Where they are set”](#where-they-are-set) | Install | Where | Read by | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | A release, from `setup.sh` | `/etc/fxbot/fxbot.env`, for optional settings such as `FXBOT_LISTS_URL`. The release’s compose file sets the rest. | The app’s container, through compose’s `env_file`. A change takes effect at the next `sudo systemctl restart fxbot`. | | A checkout | The environment, or `.env` in the repository root. The environment wins. | The server and its commands. Vite reads no `.env`. | In a release, the compose file sets these for the app, with the database password from `/opt/fxbot/.env`: ```sh FXBOT_DATABASE_URL=postgres://fxbot:@db/fxbot FXBOT_SECRET_KEY_FILE=/run/secrets/fxbot_key FXBOT_DATA=/var/lib/fxbot/data FXBOT_BACKUPS=/var/lib/fxbot/backups FXBOT_CONTROL=/var/lib/fxbot/control FXBOT_EMBED_URL=http://embed:8080/v1 ``` These win over the same names in `fxbot.env`. The image sets `FXBOT_HOST=0.0.0.0` inside the container, and compose publishes its port on the machine’s 127.0.0.1. `/opt/fxbot/.env` holds the install’s own settings for compose, not the app’s: see [What setup.sh creates](/docs/reference/install-layout/). In a checkout, `FXBOT_EMBED_URL` names the local embedder that `deploy/compose.dev.yaml` runs, `http://127.0.0.1:8081/v1`. Without it, there is no local embedder, and memory search uses words alone unless Settings picks a provider’s embedding model ([Choose where memory search’s vectors come from](/docs/how-to/memory-search/)). ## Variables [Section titled “Variables”](#variables) | Variable | What it is | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FXBOT_DATABASE_URL` | Required. fxbot's Postgres, such as `postgres://fxbot:@127.0.0.1:5433/fxbot_dev` from `deploy/compose.dev.yaml` | | `FXBOT_PORT` | The API's port. Default 8787, a release install's; `npm run dev` uses 8788 unless this is set in the shell | | `FXBOT_HOST` | The address the API listens on. Default 127.0.0.1. fxbot's image sets 0.0.0.0, and compose publishes the port on the machine's 127.0.0.1 | | `FXBOT_SECRET_KEY_FILE` | Required. A file outside the repo with 32 random bytes in base64. It seals every key and token fxbot stores | | `FXBOT_VERCEL_CLIENT_ID` | Optional. fxbot's own Vercel OAuth app, for signing in with a Vercel account, in place of the one fxbot's list of providers names | | `FXBOT_HF_CLIENT_ID` | Optional. fxbot's own Hugging Face OAuth app, a public one with no secret, for signing in with Hugging Face, in place of the one fxbot's list of providers names | | `FXBOT_DATA` | Plugins' files. Chats from before 0.4.0, in its `sessions/`, move into the database on the first start, which renames the folder `sessions.moved`. Default `./data` | | `FXBOT_CLIENT_METADATA_URL` | Optional. The project's published OAuth client document, for MCP servers that sign in with one. Without it, fxbot registers itself with each server | | `FXBOT_MCP_REGISTRY` | Optional. The MCP registry that fxbot mirrors hourly for search, and that registry entries come from. Default GitHub's, `https://api.mcp.github.com` | | `FXBOT_MCP_EVERYTHING` | Optional. The registry that Search everything asks, once per search. Default the official one, `https://registry.modelcontextprotocol.io` | | `FXBOT_LISTS_URL` | Optional. The site that publishes fxbot's own lists of the plugins it vets: MCP servers, skills, and packages. fxbot reads its `mcp-registry.json`, `skills-registry.json`, and `plugins-registry.json` hourly, its list of providers, `providers-registry.json`, and `plugin-breaks.json`, what each release broke, and keeps the lists the release shipped with until a read succeeds. Default fxbot's site, `https://fxbot.sh` | | `FXBOT_BACKUPS` | Where the database and `FXBOT_DATA` are backed up before migrations run. Default `./backups`. The backup uses `pg_dump`, which must be Postgres 17's | | `FXBOT_CONTROL` | Set by a release install's compose file: the folder where the app asks the machine for updates. Without it, Settings doesn't update | | `FXBOT_EMBED_URL` | Optional. The local embedder for memory search, an OpenAI-style address such as `http://127.0.0.1:8081/v1` from `deploy/compose.dev.yaml`. A release install's compose file sets it. Without it, there is no local embedder | | `FXBOT_PLUGIN_DIRS` | Optional, for writing a plugin in a checkout. Plugin folders, separated by `:`, that fxbot adds on first sight and loads at start, unpinned. It loads one again a moment after its files change | | `FXBOT_UPDATE_CHECK` | `off` stops the daily check for a newer release, which asks GitHub about the repository in `package.json` | | `FXBOT_RELEASES_URL` | Optional. Where that check reads the newest release, in the shape of GitHub's `releases/latest`, for a fork or a mirror | ## The site [Section titled “The site”](#the-site) `npm run build-site` reads one variable of its own: | Variable | What it is | | ----------------- | ----------------------------------------------------------------- | | `FXBOT_SITE_BASE` | The path the site is served under, such as `/fxbot/`. Default `/` | # What setup.sh creates > An install made by setup.sh. fxbot runs as three containers, from one compose file, under podman or docker: the app, its database, and the local embedder for memory search, which can be turned off. An install made by [`setup.sh`](/docs/reference/commands/#setupsh). fxbot runs as three containers, from one compose file, under podman or docker: the app, its database, and the local embedder for memory search, which can be turned off. ## Files and folders [Section titled “Files and folders”](#files-and-folders) | Path | What it is | Owner, mode | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | `/opt/fxbot/` | The install | `root`, 755 | | `/opt/fxbot/compose.yaml` | The release’s compose file: the app, its database, and the local embedder | `root` | | `/opt/fxbot/compose.gpu.podman.yaml` or `compose.gpu.docker.yaml` | The release’s GPU file for the engine, which runs the local embedder on an NVIDIA GPU. The `fxbot` command adds it when `FXBOT_EMBEDDER` is `gpu`. | `root` | | `/opt/fxbot/compose.docker.yaml` | On Docker: a check every 2 seconds while a service starts. The `fxbot` command adds it on Docker 25 and newer. | `root` | | `/opt/fxbot/compose.computer.yaml` | The computer’s: it gives the app the computer’s engine socket and group, and, where SELinux runs, turns the app’s labels off. Its setup script writes it. | `root` | | `/opt/fxbot/compose.override.yaml` | Yours, when you write one, such as to publish web pairing’s ports. The `fxbot` command adds it last, and nothing writes over it. | | | `/opt/fxbot/computer-setup.sh` | The computer’s setup script, as `fxbot computer on` last ran it, which `fxbot uninstall` runs to take the computer away | `root` | | `/opt/fxbot/docker-compose` | Compose’s own release, when the machine had no Compose new enough and its packages had none. | `root`, 755 | | `/opt/fxbot/.env` | The install’s settings for compose: `FXBOT_VERSION`, `FXBOT_UID` and `FXBOT_GID` (the `fxbot` user’s), `FXBOT_ENGINE` (`podman` or `docker`), `FXBOT_EMBEDDER` (`cpu`, `gpu`, or `off`: where the local embedder runs), `FXBOT_PORT` (the port on the machine’s loopback), `FXBOT_COMPOSE` (the Compose binary to run, when `podman compose` or `docker compose` would run one too old), and a random `FXBOT_DB_PASSWORD` | `root`, 600 | | `/opt/fxbot/fxbot` | The [`fxbot` command](/docs/reference/commands/#fxbot), linked as `/usr/local/bin/fxbot` | `root`, 755 | | `/opt/fxbot/.update.lock` | Held while an update runs, so a second one waits | `root` | | `/etc/fxbot/` | The settings and the key | `root`, 755 | | `/etc/fxbot/secret.key` | 32 random bytes in base64, which seal every stored secret. Compose mounts it into the app, read-only, at `/run/secrets/fxbot_key`. | `fxbot`, 400 | | `/etc/fxbot/packages` | What `setup.sh` and the computer’s setup installed: the package manager on the first line, then a package, or a file of Docker’s repository, on each, for `fxbot uninstall` to name | `root` | | `/etc/fxbot/fxbot.env` | The app’s optional [settings](/docs/reference/configuration/), such as `FXBOT_LISTS_URL` | `root` | | `/var/lib/fxbot/` | The `fxbot` user’s home | `fxbot`, 700 | | `/var/lib/fxbot/data/` | Plugins’ files (`FXBOT_DATA`). An install from before 0.4.0 also has `sessions.moved`, its chats’ old files, which the first start of 0.4.0 moved into the database. Delete it once you’re sure of the move. | `fxbot`, 700 | | `/var/lib/fxbot/backups/` | Backups taken before migrations change a database in use, the last five (`FXBOT_BACKUPS`) | `fxbot`, 700 | | `/var/lib/fxbot/control/` | The app’s requests, in `requests/`, for an update or a new place for the local embedder. The machine’s answers: `status.json`, which Settings shows during an update, and `embedder-status.json`, for a switch of the embedder (`FXBOT_CONTROL`) | `fxbot`, 755 | | `/etc/systemd/system/fxbot.service` | Starts the containers at boot | `root` | | `/etc/systemd/system/fxbot-control.path` and `fxbot-control.service` | Run `fxbot apply` when the app writes a request | `root` | The app sees the three folders in `/var/lib/fxbot` at the same paths. Each mount takes `:z`, which labels it for containers where SELinux runs, as on Fedora, RHEL, and openSUSE, and does nothing where it doesn’t. Each backup is a folder named `-before-`, holding `database.dump`, in pg_dump’s custom format, and `data.tar.gz`, the data folder. A start backs up once, before its first change. When only the tables that hold the chats change, the folder is named `-before-world-postgres-`. The update to 0.4.0 took `-before-0006_plugins`, whose `data.tar.gz` holds the chats’ old files. A 0.2 install that `setup.sh` moved into containers also has `-move-to-containers`, with the 0.2 database. ## The containers [Section titled “The containers”](#the-containers) The compose project is `fxbot`, with three services: | Service | What it is | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fxbot` | The app: `ghcr.io/iammrduncan/fxbot:`, for amd64 and arm64, with Node 22, the server, the built page, and Postgres 17’s `pg_dump`. It runs as the `fxbot` user’s ids, and listens on `127.0.0.1:8787` on the machine, or the port `FXBOT_PORT` names, the same inside the container as outside. `GET /api/health` answers `{"ok":true,"version":""}`. | | `db` | The database: `pgvector/pgvector:0.8.7-pg17-trixie`, Postgres 17 with pgvector. Its database and role are both `fxbot`, with the password in `/opt/fxbot/.env`. Its data is in the named volume `pgdata`, not a folder on the machine. It has no port on the machine, and the app reaches it as `db`. | | `embed` | The local embedder for memory search: llama.cpp’s server, `ghcr.io/ggml-org/llama.cpp:server-b12033`, with EmbeddingGemma 2 (`ggml-org/embeddinggemma-2-GGUF:Q8_0`). On its first start, it downloads the model, 310 MB, into the named volume `models`. It holds about 380 MB of memory, and runs at a low CPU weight (`cpu_shares: 256`), so it gives way to the rest. It has no port on the machine, and the app reaches it at `http://embed:8080/v1` (`FXBOT_EMBED_URL`). With the GPU file, it runs `server-cuda-b12033` with Qwen3-Embedding-0.6B (`Qwen/Qwen3-Embedding-0.6B-GGUF:Q8_0`) instead. With `FXBOT_EMBEDDER=off`, it doesn’t run. | | Setting | Value | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Restarts | After a crash (`restart: unless-stopped`) | | Stops | The app gives running chats 30 seconds to finish, and one still running goes on when it starts again. The container is stopped after 90 seconds at most, and the database after a minute | | Health | The app when its port answers, which it opens after its migrations. The database when `pg_isready` answers. The embedder when its `/health` answers. The app doesn’t wait for the embedder, and searches by words until it answers. | | Log | `sudo fxbot logs`, or one container’s, such as `sudo fxbot logs fxbot`, `sudo fxbot logs db`, or `sudo fxbot logs embed` | ## The services [Section titled “The services”](#the-services) | Unit | What it does | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fxbot.service` | Runs `fxbot up` at boot, after the network and podman’s socket (or docker), and `fxbot down` when it stops. `sudo systemctl restart fxbot` restarts fxbot. | | `fxbot-control.path` | Watches `/var/lib/fxbot/control/requests`, and starts `fxbot-control.service` when the app writes a request | | `fxbot-control.service` | Runs `fxbot apply` | The user `fxbot` is a system user, with its home in `/var/lib/fxbot` and no login shell. The app’s container runs as its ids, so the files the app writes are the user’s. ## Packages [Section titled “Packages”](#packages) Through whichever of apt, dnf, zypper, or pacman the machine has: * `ca-certificates`, and `curl` when there’s none * **an engine,** when the machine has neither podman 4 or newer nor Docker: `podman` when the distribution has 4.9 or newer, or else Docker’s own `docker-ce`, `docker-ce-cli`, `containerd.io`, and `docker-compose-plugin`, from Docker’s repository, added as `/etc/apt/sources.list.d/docker.sources` with its key in `/etc/apt/keyrings/docker.asc` * **with podman,** `netavark`, `aardvark-dns`, and `nftables`, which containers find each other by name through and podman only recommends, and `golang-github-containernetworking-plugin-dnsname` for a podman that has run on CNI, as Debian 12’s does out of the box * **Compose,** when the machine has none 2.26 or newer: the distribution’s package when it’s new enough (`docker-compose-plugin`, `docker-compose-v2`, or `docker-compose`), or else Compose 2.40.3 from its releases, as `/opt/fxbot/docker-compose`, checked against its SHA-256 apt installs without its recommends, after `apt-get update`, and `setup.sh` stops instead when apt would remove a package. dnf and zypper install without weak dependencies, and pacman with `--needed`, on the package lists the system has. Each package that wasn’t there before goes in `/etc/fxbot/packages`. With podman, `setup.sh` enables `podman.socket`, which Compose reaches podman through. It installs nothing for a GPU: the local embedder on one needs NVIDIA’s driver and container toolkit, which you install yourself ([On a GPU](/docs/how-to/memory-search/#on-a-gpu)). ## Firewalls [Section titled “Firewalls”](#firewalls) On podman, the containers ask their network’s own DNS server for each other’s names, on the bridge’s port 53. Each `fxbot up`: * **with ufw active,** lets port 53 in on podman’s bridge for fxbot’s network, as a rule marked `fxbot` * **with firewalld running,** turns on `netavark-firewalld-reload.service`, which puts podman’s rules back after each `firewall-cmd --reload` Docker needs neither. `fxbot uninstall` removes the ufw rules marked `fxbot`, and leaves netavark’s unit on, for podman’s other networks. `sudo fxbot uninstall` removes all of this but `/var/lib/fxbot`, `/etc/fxbot`, and the user `fxbot`, which `--purge` removes too, and the packages, which it names: see [Uninstall fxbot](/docs/how-to/uninstall/). ## After a move from 0.2 [Section titled “After a move from 0.2”](#after-a-move-from-02) `setup.sh` leaves what 0.2 used until you remove it: `/opt/fxbot/repo`, `/opt/fxbot/releases`, `/opt/fxbot/current`, the 0.2 unit and settings kept as `/opt/fxbot/fxbot-0.2.service` and `/opt/fxbot/fxbot-0.2.env`, and the machine’s Postgres with its `fxbot` database. `sudo fxbot status` prints the commands that remove them. # Providers > Every provider on Add provider, in Settings › Providers: how each connects, its address, where its models come from, and where its key is checked. Each bot runs on one provider. Every provider on **Add provider**, in **Settings** › **Providers**, and in first-run setup. Each bot runs on one provider. To add one, see [Add a provider](/docs/how-to/add-a-provider/), and each provider’s own page. | Provider | Connects with | Address | Models from | Key checked at | | --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------- | | [Vercel](/docs/providers/vercel/) | Sign in by device code, then a team | AI Gateway | AI Gateway’s list | No key: a sign-in | | [ChatGPT and Codex](/docs/providers/chatgpt/) | Sign in by device code | ChatGPT’s Codex API | The Codex model list | No key: a sign-in | | [Grok](/docs/providers/grok/) | Sign in by device code | Grok’s API | Grok’s model list | No key: a sign-in | | [AI Gateway](/docs/providers/vercel/) | A key | AI Gateway | AI Gateway’s list | Its model list | | [OpenAI](/docs/providers/openai/) | A key | `https://api.openai.com/v1` | models.dev | Its model list | | [Anthropic](/docs/providers/anthropic/) | A key | `https://api.anthropic.com/v1` | Its own list | Its model list | | [Google Gemini](/docs/providers/gemini/) | A key | `https://generativelanguage.googleapis.com/v1beta/openai` | Its own list | Its model list | | [OpenCode Go](/docs/providers/opencode/) | A key | `https://opencode.ai/inference/go/openai/v1` | models.dev | `https://opencode.ai/inference/go/v1/models` | | [DeepSeek](/docs/providers/deepseek/) | A key | `https://api.deepseek.com` | Its own list | Its model list | | [OpenRouter](/docs/providers/openrouter/) | Sign in, back to fxbot’s page or with a code; or a key | `https://openrouter.ai/api/v1` | models.dev | `https://openrouter.ai/api/v1/key` | | [Z.ai](/docs/providers/zai/) | A key | `https://api.z.ai/api/paas/v4` | Its own list | Its model list | | [Qwen](/docs/providers/qwen/) | A key, with its region | `https://{endpoint}/compatible-mode/v1` | Its own list | Its model list | | [Kimi](/docs/providers/kimi/) | A key, with its platform | `https://{host}/v1` | Its own list | Its model list | | [MiniMax](/docs/providers/minimax/) | A key | `https://api.minimax.io/v1` | Its own list | Its model list | | [xAI](/docs/providers/xai/) | A key | `https://api.x.ai/v1` | Its own list | Its model list | | [Mistral](/docs/providers/mistral/) | A key | `https://api.mistral.ai/v1` | Its own list | Its model list | | [Groq](/docs/providers/groq/) | A key | `https://api.groq.com/openai/v1` | Its own list | Its model list | | [Together AI](/docs/providers/together/) | A key | `https://api.together.ai/v1` | Its own list | Its model list | | [Fireworks AI](/docs/providers/fireworks/) | A key | `https://api.fireworks.ai/inference/v1` | Its own list | Its model list | | [DeepInfra](/docs/providers/deepinfra/) | A key | `https://api.deepinfra.com/v1/openai` | Its own list | Its model list | | [Cerebras](/docs/providers/cerebras/) | A key | `https://api.cerebras.ai/v1` | Its own list | Its model list | | [NVIDIA](/docs/providers/nvidia/) | A key | `https://integrate.api.nvidia.com/v1` | Its own list | Not before a chat | | [Hugging Face](/docs/providers/huggingface/) | Sign in by device code; or a key | `https://router.huggingface.co/v1` | Its own list | `https://huggingface.co/api/whoami-v2` | | [Nous Portal](/docs/providers/nous/) | A key | `https://inference-api.nousresearch.com/v1` | Its own list | Not before a chat | | [OrcaRouter](/docs/providers/orcarouter/) | Sign in by device code; or a key | `https://api.orcarouter.ai/v1` | Its own list | Its model list | | [OpenCode Zen](/docs/providers/opencode/) | A key | `https://opencode.ai/inference/openai/v1` | models.dev | `https://opencode.ai/inference/v1/models` | | [Vertex AI](/docs/providers/vertex/) | A service account’s JSON key, with its location | `https://aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/endpoints/openapi` | models.dev | Google makes a token from it | | [AWS Bedrock](/docs/providers/bedrock/) | A key, with its region | `https://bedrock-runtime.{region}.amazonaws.com/openai/v1` | models.dev | `https://bedrock-mantle.{region}.api.aws/v1/models` | | [Azure OpenAI](/docs/providers/azure/) | A key, with its resource name | `https://{resource}.openai.azure.com/openai/v1` | The ids you type | Its model list | | [Cloudflare](/docs/providers/cloudflare/) | A key, with its account id | `https://api.cloudflare.com/client/v4/accounts/{account}/ai/v1` | models.dev | `https://api.cloudflare.com/client/v4/accounts/{account}/ai/models/search?per_page=1` | | [Ollama](/docs/providers/ollama/) | Its address | `http://localhost:11434/v1` by default | The server: `/api/tags`, and `/api/show` for each model | Its model list | | [LM Studio](/docs/providers/lmstudio/) | Its address | `http://localhost:1234/v1` by default | The server: `/api/v1/models` | Its model list | | [llama.cpp](/docs/providers/llamacpp/) | Its address, and a key if it needs one | `http://localhost:9931/v1` by default | Its own list | Its model list | | [vLLM](/docs/providers/vllm/) | Its address, and a key if it needs one | `http://localhost:8000/v1` by default | Its own list | Its model list | | [LiteLLM](/docs/providers/litellm/) | Its address, and a key if it needs one | `http://localhost:4000/v1` by default | Its own list | Its model list | | [Custom](/docs/how-to/add-a-provider/#custom) | Its address, and a key if it needs one | Yours | Its own list | Its model list | **Search** also finds about 175 more hosts from [models.dev](https://models.dev): those that speak OpenAI’s Chat Completions at a fixed HTTPS address. Each takes a key, at models.dev’s address for it, and its models come from its own list, or models.dev’s when it has none. They haven’t been tried with fxbot. ## The list of providers [Section titled “The list of providers”](#the-list-of-providers) * fxbot ships its list of providers, `providers-registry.json`, with each release, and reads it again every hour from fxbot.sh, as it does the plugin list ([`FXBOT_LISTS_URL`](/docs/reference/configuration/)). A new provider, or a key page that moved, needs no release. * An entry that needs something this fxbot can’t do, such as a way to sign in it doesn’t know, is left out. * A provider keeps what it needs to run when it’s added: its address, its fields, and the model ids typed for it. One whose entry later leaves the list carries on. ## Keys and sign-ins [Section titled “Keys and sign-ins”](#keys-and-sign-ins) * A key is checked with the provider when it is added: where the table says, or at its model list. It is refused when the provider answers 401 or 403, or a status the entry names, such as xAI’s and Gemini’s 400. A 404 passes, which a server with no list at `/models` gives. * A provider whose list answers any key, such as NVIDIA’s, can’t be checked before a chat. Its card says so, and a wrong key shows at the first message. * A chat whose provider refuses its key with 401 says which provider, and to replace the key in **Settings** › **Providers**. A 403 says the key may lack a permission, or the account may need credit or be over its quota, since providers use it for all of those. * A field, such as a region or an account, fills in the provider’s address. A field with options takes one of them, and any other field takes a name, with nothing that could change the address’s shape. * A key goes to the server once and is never sent back. A provider in the list says only whether it holds a key or a sign-in. * A sign-in runs on the server. The page gets the link and the code, or the page to open, and when it expires. * **Device code:** ChatGPT, Grok, Hugging Face, and OrcaRouter, and Vercel where its sign-in shows. Open the link on any device, and enter the code. * **OpenRouter** comes back to fxbot’s own page when the page’s address is HTTPS or on localhost. On a plain-HTTP address, or when asked, it shows a code to paste instead. * **Vercel and Hugging Face** need fxbot’s own app at each, which fxbot’s list of providers names, or [`FXBOT_VERCEL_CLIENT_ID` and `FXBOT_HF_CLIENT_ID`](/docs/reference/configuration/) in its place. A sign-in whose app isn’t set doesn’t show. Vercel’s isn’t, since Vercel doesn’t let fxbot’s app use a device code yet. * **Vertex AI** takes a service account’s JSON key. fxbot makes its own hour-long tokens from it, and a new one 5 minutes before each ends. * Keys and tokens are stored sealed. See the [security model](/docs/explanation/security/). A new key works from the next request, even for a turn already running. **Remove** ends whatever is still running on a provider first, in any chat, and its key stops working at once. When a provider keeps refusing, such as with a rate limit, libfx tries again by itself. After 5 minutes of nothing but refusals, fxbot stops the turn, and the chat says why. A model that’s only slow is left alone. ## Model lists [Section titled “Model lists”](#model-lists) * A provider’s models come from its own list, with [models.dev](https://models.dev)’s context window, tool use, images, and [thinking levels](#thinking-levels) for each model it knows: by its id, then by its id without a vendor, then by models.dev’s canonical id. A model models.dev doesn’t know lists without them. * Where the provider has no list, its models are models.dev’s, as the table says. Where you typed model ids, such as Azure’s deployments, those are the list. * fxbot keeps each provider’s model list in Postgres and answers with it at once. A list older than 5 minutes is fetched again behind that answer, and a failed fetch keeps the old list. * A list is dropped when its source changes: a new key, address, team, sign-in, or model ids. * models.dev is read at most once a day. * The model picker takes a model id that the list lacks. * A provider’s **Context window**, on a server on your machine or **Custom**, overrides what the server reports, for every model it serves. ## Thinking levels [Section titled “Thinking levels”](#thinking-levels) A model’s thinking levels, which **Thinking** on a bot’s edit screen offers, come from where its provider lists them: | Provider | Where its models’ levels come from | A bot’s level reaches the model | | ---------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | | AI Gateway, Vercel | AI Gateway’s catalog, the one the agent checks a level against | Now. Max goes as Extra high, the most the gateway’s route takes | | ChatGPT | ChatGPT’s model list | Now. Minimal goes as Low | | Grok | Grok’s model list | Now | | OpenRouter, and servers with OpenRouter’s list | Each model’s `supported_efforts` | With a coming update | | Ollama | Each model’s `thinking` values | With a coming update | | LM Studio | Each model’s reasoning options: its off is Off | With a coming update | | Every other provider by key | [models.dev](https://models.dev)’s reasoning options for each model | With a coming update | * **Model’s default** sends no level, on every provider. * **A level the model doesn’t offer** runs as the nearest lower one it offers, never as Off, and the server’s log says so once. With no lower level, the model’s own default runs. * **“With a coming update”** is libfx’s: version 0.0.16 sends a level only for AI Gateway, ChatGPT, and Grok. Its next release lets a custom provider’s models offer levels. Until then, fxbot sends none for them, so no turn fails for one. ## Embeddings [Section titled “Embeddings”](#embeddings) Memory search can take its vectors from a provider’s embedding model, picked in **Settings** › **Memory** ([Choose where memory search’s vectors come from](/docs/how-to/memory-search/)). | Provider | Embeddings from | | --------------------------------------------- | --------------------------------------------------------------------------- | | OpenAI, OpenRouter, Ollama, LM Studio, Custom | `/embeddings` under its address | | AI Gateway, Vercel | `https://ai-gateway.vercel.sh/v1/embeddings`. A Vercel account is untested. | | Any other | None | * The model’s id is typed in, as the provider names it. * Picking one embeds a test string first. If that fails, the old setting stays. * Removing the provider turns search by meaning off, until another is picked. # Under the hood > What fxbot runs as, where its data lives, how it updates, and the ways in, at a glance. It's one small app with its database, on a machine of your own, made for one person. What fxbot runs as, where its data lives, how it updates, and the ways in, at a glance. It’s one small app with its database, on a machine of your own: the computer under your desk, a home server, or a small VPS. | Part | What it is | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Install | One command, [`setup.sh`](/docs/reference/commands/#setupsh). It checks the machine first, and adds podman or docker when neither is there. See [what it runs on](/docs/tutorials/first-fxbot/) and [what it creates](/docs/reference/install-layout/). | | Runs as | Three containers: fxbot, Postgres with pgvector, and a local embedder for memory search | | Agents | [libfx](https://fx.sh/docs/lib), one agent per provider | | Data | Bots, chats, files, and keys, in Postgres on the machine, with every key and token sealed. Each message goes only to the provider its bot uses, or stays on your network with a local model server. | | Updates | From **Settings**, with a backup first, and the release before when one doesn’t start. See [Update to a new release](/docs/how-to/update/). | | Ways in | `127.0.0.1:8787` on the machine. From other devices, web pairing, the recommended way, or Tailscale, SSH, or a proxy of your own. See [Reach fxbot from other devices](/docs/how-to/reach-it/). | | Hosting | None. There’s no hosted version, and no account to make. | | People | One. fxbot has no login of its own, so whatever is in front of it decides who reaches it, and everyone who does sees every bot and every chat. See [Security](/docs/explanation/security/#loopback-only-with-no-login). | # Web pairing > The web-pairing plugin's settings, defaults, and limits, and what web.fxbot.sh serves. The web-pairing plugin’s settings, defaults, and limits, and what web.fxbot.sh serves. [How web pairing works](/docs/explanation/web-pairing/) explains the design. ## Settings › Web pairing [Section titled “Settings › Web pairing”](#settings--web-pairing) The plugin keeps its settings itself, sealed with its keys in fxbot’s database, rather than as plugin settings. | Setting | Default | What it does | | ------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Remote access** | on | Off closes the relay connection and every device’s connection, and refuses new ones. | | **ICE servers** | `stun:stun.cloudflare.com:3478` | The STUN and TURN servers, in order, for fxbot and every device. fxbot’s own WebRTC library uses the first STUN and the first TURN server. | | **Relay** | `wss://web.fxbot.sh/signal` | Where fxbot listens, and what its pairing links carry when it isn’t the default. | | **UDP ports** | 8790–8799 | The ports for WebRTC: 2 to 100, from 1024 up. | | **Map the ports on the router** | on | Asks the router for the ports by NAT-PMP, then UPnP, while fxbot listens. Off in a container. | ### ICE servers [Section titled “ICE servers”](#ice-servers) | Kind | What you give | What a device gets | | ------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | STUN server | `stun:` or `stuns:` addresses | The addresses | | TURN server | `turn:` or `turns:` addresses, a username, and a password | The same | | TURN with a shared secret | `turn:` or `turns:` addresses, and coturn’s or eturnal’s shared secret | A username and password fxbot makes for each connection, good for 24 hours: the username is the expiry time and `fxbot`, and the password the base64 of its HMAC-SHA1 under the secret | | Cloudflare TURN key | A TURN key’s id and API token | Credentials fxbot asks Cloudflare for, good for 24 hours, kept for 12 | Passwords, secrets, and tokens never go back to the page. Add `?transport=tcp` to an address for TCP. Several addresses go in one entry, separated by spaces. ## Pairing [Section titled “Pairing”](#pairing) | What | Value | | --------------------- | ------------------------------------------------------------------------------------------------------------------- | | A pairing’s life | 10 minutes, and until its first failure, and until fxbot restarts | | Open pairings at once | 3 | | A code | `N-DDDD-DDDD`: a number from 1 to 999 that finds fxbot at the relay, then eight digits | | A code’s guesses | 1 | | The lockout | 3 wrong codes in 15 minutes lock pairing for 15 minutes. Restarting fxbot ends it. | | The link | `https://web.fxbot.sh/pair#1.
...`, with the relay at the end when it isn’t fxbot.sh’s | ## Devices [Section titled “Devices”](#devices) Each paired device is a row in the plugin’s own table, `plugin_web_pairing.devices`: its id, name, kind, public key, when and how it was paired, where that was approved, when it was last seen, and the last counter it connected with. A passkey is a row in `plugin_web_pairing.passkeys`: its credential id, public key, algorithm, the device that added it, and when it was last used. | What | Value | | ---------------------------------- | ----------------------------------- | | Connections at once | 20 | | A connection that never connects | ends after 20 seconds | | A connection that drops | ends after 30 seconds | | A request’s body, through a device | fxbot’s own limits; 256 MiB at most | Removing the plugin deletes its keys, its devices, and its passkeys. Every device then pairs again. ## The relay [Section titled “The relay”](#the-relay) The plugin connects only while a pairing is open, a device is paired, or a passkey is added, and remote access is on. It pings every 30 seconds, and after a drop reconnects with jitter, from 1 second up to 60. Opening a pairing reconnects at once. | Limit | Value | | -------------------- | ------------------------------------------------------- | | A message | 16 KB | | Messages in one call | 64 | | Calls to one fxbot | 30 a minute | | A nameplate | 10 minutes | | A listener’s proof | Ed25519 over its address and the time, within 2 minutes | ## What web.fxbot.sh serves [Section titled “What web.fxbot.sh serves”](#what-webfxbotsh-serves) | Address | What | | ----------------------------------------------------- | ------------------------------------------------------- | | `https://web.fxbot.sh/` | The app, with its own service worker for its files only | | `https://web.fxbot.sh/pair` | The same app, opened at pairing | | `https://web.fxbot.sh/licenses.txt` | The licenses of what the app bundles | | `wss://web.fxbot.sh/signal/…` | The relay | | `https://.fxbot.sh/__fxbot/start` | A frame’s first page, which only the app can frame | | `https://.fxbot.sh/__fxbot/frame.js`, `/sw.js` | The frame’s script and service worker | Nothing else: every other address in a frame comes from your fxbot, through the connection. The Worker uses no storage, no alarms, and no logs. Its source is `packages/web-app/` in fxbot’s repository, and `node build.mjs` there writes each file’s SHA-256 to `dist/hashes.txt`. # Your first fxbot > In this tutorial you install fxbot on a machine of yours, make a bot, put fxbot on your phone, and chat with the bot there. In this tutorial you install fxbot on a machine of yours, make a bot, put fxbot on your phone, and chat with the bot there. You need: * a Linux machine with systemd, where you can use `sudo`: Debian 12 or 13, Ubuntu 22.04 or 24.04, Fedora, AlmaLinux 9 or 10, openSUSE Tumbleweed or Leap 16, Arch, or a distro built on one of them. On Windows, WSL 2’s Ubuntu works, with systemd on ([how](/docs/how-to/fix-an-install/)). On a Mac, use a Linux VM. It needs an x86_64 or arm64 CPU, 3 GB free in `/var/lib`, and 1 GB of memory free, more for each bot’s computer. * a browser on that machine, or, for a server with no screen, SSH to it from your computer * a phone, for the last part * an account to sign in with, such as a ChatGPT plan or OpenRouter, or a key from a provider such as OpenAI or Groq ## Install fxbot [Section titled “Install fxbot”](#install-fxbot) On the machine, run: ```sh curl -fsSL https://fxbot.sh/setup.sh | sudo bash ``` The script checks the machine first, and stops with what to do if it can’t install there ([Fix an install that stopped](/docs/how-to/fix-an-install/)). Then it names each step in bold as it goes: the container engine, Compose, the fxbot user and its key, the release, the images, and the services. fxbot runs as three containers: the app, its database, and the local embedder for memory search. The script uses the engine that’s there, a Docker that’s running or podman, and with neither, it installs podman, or Docker’s own `docker-ce` where the distro’s podman is too old. Downloading the three images can take a few minutes, with their progress shown, and the embedder downloads its model, 310 MB, on its first start. It ends with: ```plaintext fxbot runs on http://127.0.0.1:8787 Open it there, or reach it: from your phone: add Web pairing in Plugins (https://fxbot.sh/docs/how-to/reach-it-from-your-phone/) from your computer, over SSH: ssh -N -L 8787:127.0.0.1:8787 @ with Tailscale: sudo tailscale serve --bg 8787 Settings shows each new release, with an Update button. To uninstall: sudo fxbot uninstall ``` Ask it whether it is up: ```sh curl http://127.0.0.1:8787/api/health ``` It answers `{"ok":true,"version":""}`. fxbot is running, but only this machine can reach it. To see its containers: ```sh sudo fxbot status ``` It names the version, the engine, and where the local embedder runs, then lists three containers, `fxbot`, `db`, and `embed`. ## Open it [Section titled “Open it”](#open-it) On the machine, open `http://127.0.0.1:8787` in a browser. fxbot shows **Set up fxbot**. On a server with no screen, run this on your computer instead, and keep it running: ```sh ssh -N -L 8787:127.0.0.1:8787 @ ``` While it runs, open `http://127.0.0.1:8787` on your computer. ## Set up fxbot [Section titled “Set up fxbot”](#set-up-fxbot) The first time you open it, fxbot shows **Essentials**: the plugins most people want, each with what it gives you. One of them, the computer, sets up a computer engine on this machine, then restarts fxbot, and it says so there. Web pairing, which puts fxbot on your phone, isn’t among them: you’ll add it at the end. Tap **Set up Essentials**. fxbot adds them one by one, and moves on by itself. To pick your own instead, tap **Choose my own**, where they’re already ticked, and untick what you don’t want. Plugins you leave out are under **Plugins** for later. ![First-run setup, on Essentials: the plugins most people want, each with what it gives you](/shots/setup-choose-desktop-light.png) ![First-run setup, on Essentials: the plugins most people want, each with what it gives you](/shots/setup-choose-desktop-dark.png) ### Connect a model [Section titled “Connect a model”](#connect-a-model) fxbot lists the providers it can connect to, with sign-ins first. Tap **ChatGPT and Codex**, under **Sign in**. fxbot shows a code, and a QR of its link. Open the link, or scan the QR with your phone, sign in to ChatGPT, and enter the code. The page moves on by itself once you have. With a key instead, tap the provider under **Use a key**, such as **OpenAI** or **OpenRouter**. Its card links to the page where its keys are made. Paste the key, and tap **Add**. fxbot checks the key with the provider before it keeps it. Then pick the model your bots use, and tap **Continue**. ![First-run setup, on Connect a model, with sign-ins first](/shots/setup-provider-desktop-light.png) ![First-run setup, on Connect a model, with sign-ins first](/shots/setup-provider-desktop-dark.png) ### Make a bot [Section titled “Make a bot”](#make-a-bot) Name the bot `Scout`, pick how it looks, or tap **Surprise me**, and tap **Create**. As you choose, the bot watches. fxbot says where plugins live for later. Tap **Start chatting**, and Scout’s chat opens. If you leave partway, fxbot comes back to the same step. **Skip for now** skips the step it’s on, and on the bot step, the last, it ends setup. Everything a step does is still there later: **Plugins** at the foot of the sidebar, **Settings** › **Providers**, and **New bot**. ![First-run setup, on Make a bot, with the look picker](/shots/setup-bot-desktop-light.png) ![First-run setup, on Make a bot, with the look picker](/shots/setup-bot-desktop-dark.png) ## Put it on your phone [Section titled “Put it on your phone”](#put-it-on-your-phone) Before you say hello, put fxbot on your phone. Web pairing opens your fxbot at [web.fxbot.sh](https://web.fxbot.sh), on your phone, over a connection straight to it, away from home too. 1. In fxbot, open **Plugins**, find **Web pairing**, and add it. 2. On your phone, open web.fxbot.sh and install it: * **iPhone:** in Safari, tap **Share**, then **Add to Home Screen**. Open fxbot from the Home Screen. * **Android:** in Chrome, tap **Install app** in its menu, and open the app. 3. In fxbot, open **Settings** › **Web pairing**, and choose **Pair a device**. It shows a code and a QR code. 4. On your phone, in the app, choose **Pair a device**, and type the code. On Android, **Scan the QR code** scans it instead. 5. Both screens show six digits. Check they’re the same, then choose **Approve** in fxbot. The phone says **Paired**. Tap **Open**: your fxbot fills the screen, with your bots, plugins, and settings. Open Scout’s chat. To check it’ll connect away from home, see **Settings** › **Web pairing** › **Reachability**. A network that won’t connect directly has [other ways](/docs/how-to/when-a-device-cant-connect/). ## Chat [Section titled “Chat”](#chat) On your phone, send `Hello! What can you do?`. The reply streams in as it is written, and the same chat on the machine shows it too. Now close the app and open it again. The chat is still there, because it lives on your fxbot, not in the app. A reply still being written when you leave carries on without you. ## Give it instructions [Section titled “Give it instructions”](#give-it-instructions) Open the bot panel with the button at the top right of the chat, then **Edit**. Under **Instructions**, write `Answer in one short paragraph.` and tap **Save**. Ask Scout something else, and notice the shorter reply. ## What you have now [Section titled “What you have now”](#what-you-have-now) A release of fxbot, on your machine and paired with your phone, with a provider and a bot that keeps its chat. From here: * [Put fxbot on your computer too](/docs/how-to/reach-it-from-your-computer/), as an app of its own. * [Add a skill](/docs/how-to/add-a-skill/) to give your bots instructions for a kind of task. * [Add an MCP server](/docs/how-to/add-an-mcp-server/) to give your bots tools. * [Pair another device](/docs/how-to/pair-another-device/), so a phone that loses its pairing can pair again from anywhere, or [reach it another way](/docs/how-to/reach-it/), such as Tailscale. * Read about [bots, chats, memories, and the library](/docs/explanation/bots-and-chats/), and the [security model](/docs/explanation/security/). # Set up with your AI agent > Give your AI agent one line, and it sets fxbot up on your machine. Or give it all the docs as plain text. Give your AI agent one line, and it sets fxbot up on your machine. Or give it all the docs as plain text. ## Set up fxbot [Section titled “Set up fxbot”](#set-up-fxbot) On the machine you want fxbot on, tell your agent: ```text Set up fxbot on this computer for me: follow https://fxbot.sh/agent-setup.txt ``` It checks the machine, asks before it installs anything, and leaves your keys and sign-ins to you. When it’s done, carry on from [Set up fxbot](/docs/tutorials/first-fxbot/#set-up-fxbot), which then [puts fxbot on your phone](/docs/tutorials/first-fxbot/#put-it-on-your-phone). ## Give it the docs [Section titled “Give it the docs”](#give-it-the-docs) **Copy all docs**, at the top of each page on a computer, copies them all, to paste into a chat. Or point your agent at the plain text: | File | What’s in it | | ----------------------------------- | ---------------------------------------- | | [agent-setup.txt](/agent-setup.txt) | The steps for an agent to install fxbot | | [llms.txt](/llms.txt) | A short index of the docs, to start from | | [llms-full.txt](/llms-full.txt) | All the docs in one file, about 400 KB | Every page has a Markdown twin too, at its address with `.md` in place of the last slash, such as [/docs/how-to/update.md](/docs/how-to/update.md). **Copy Markdown**, at the top of each page, copies it. # fxbot SDK > @fxbot/sdk is the agent system that fxbot is built on, for building bot applications of your own: a chat in a terminal, a bot on a messaging service, a page of your own design, or a backend that gives your product bots that remember. fxbot's own server and page are one app built on it. `@fxbot/sdk` is the agent system that fxbot is built on, for building bot applications of your own: a chat in a terminal, a bot on a messaging service, a page of your own design, or a backend that gives your product bots that remember. fxbot’s own server and page are one app built on it. New to it? Start with the tutorial, [Build a terminal chat](/sdk/tutorials/terminal-chat/). The SDK’s pages are in four parts, each for a different need. ## What it gives your app [Section titled “What it gives your app”](#what-it-gives-your-app) * **Bots with lasting chats.** Each bot is a profile with a name, instructions, a provider, and a model, and one durable chat that survives restarts. A turn runs on [libfx](https://fx.sh/docs/lib), the agent from fx. * **Providers.** About 40, from a list fxbot.sh keeps up to date: accounts signed in by device code or a way back, such as ChatGPT, Grok, and OpenRouter, keys for gateways, labs, and clouds, and local model servers such as Ollama and LM Studio. * **Replies as they’re written.** Each chat is a stream of lines: text, thinking, and tool calls, in the order they happen, which a small function folds into turns. * **Tools.** Every bot searches its own past chats, keeps [memories](/sdk/how-to/memories/), and reads and saves files in the library. Remote MCP servers and skills add more. * **Plugins.** Code that changes fxbot itself, with hooks into each turn and tool call, tools, routes, tables, settings, and screens of its own. See [Write a plugin](/sdk/how-to/write-a-plugin/). * **Records in Postgres.** Bots, chats, files, memories, and settings live in Postgres, with every key and token sealed under a key your app holds. The database moves forward through numbered migrations when your app starts. ## Two entries [Section titled “Two entries”](#two-entries) | Entry | Runs in | What it is | | ------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `@fxbot/sdk` | Your backend, on Node 22.18 or newer | `createFxbot()`: the bots, their chats, providers, tools, and records, over your Postgres. It holds the key that seals secrets. | | `@fxbot/sdk/client` | A page or a script | A typed client for an fxbot server’s HTTP API, with the stream reader and the function that folds stream lines into turns. It carries no credentials. | ## A look [Section titled “A look”](#a-look) ```ts import { readFileSync } from "node:fs"; import { createFxbot } from "@fxbot/sdk"; const fxbot = await createFxbot({ databaseUrl: process.env.FXBOT_DATABASE_URL!, secretKey: readFileSync("secret.key", "utf8") }); const provider = await fxbot.providers.add({ kind: "ollama", model: "qwen3:8b" }); const bot = await fxbot.profiles.create({ name: "Scout", provider: provider.id }); await fxbot.send(bot.id, { text: "Hello!", messageId: crypto.randomUUID() }); // The reply streams in on fxbot.stream(bot.id). ``` ## What you need [Section titled “What you need”](#what-you-need) * Node 22.18 or newer, which runs the SDK’s TypeScript as it is. * Postgres with the pgvector extension. fxbot’s own compose file runs one, with the local embedder for memory search, under podman or docker. * A model: a local server such as Ollama, an API key, or an account. The SDK isn’t on npm yet. It’s TypeScript source in fxbot’s repository, and an app uses it through an npm workspace: see [Use the SDK in a project](/sdk/how-to/set-up/). ## Tutorials A first app on the SDK, from an empty folder to a chat with your bot. * [Build a terminal chat](/sdk/tutorials/terminal-chat/) ## How-to guides Steps for one task in your own app. * [Use the SDK in a project](/sdk/how-to/set-up/) * [Stream replies](/sdk/how-to/stream-replies/) * [Connect providers](/sdk/how-to/providers/) * [Give bots tools](/sdk/how-to/tools/) * [Work with memories](/sdk/how-to/memories/) * [Build a page on the client](/sdk/how-to/web-page/) * [Write a plugin](/sdk/how-to/write-a-plugin/) ## Reference The SDK's calls, options, and types, the server's HTTP API, and the plugin API. * [createFxbot](/sdk/reference/create-fxbot/) * [The fxbot object](/sdk/reference/server-api/) * [The client](/sdk/reference/client/) * [HTTP API](/sdk/reference/http-api/) * [Plugin API](/sdk/reference/plugin-api/) ## Explanation How the SDK works under an app, and why. * [How the SDK works](/sdk/explanation/how-it-works/) # How the SDK works > @fxbot/sdk runs bots for your app: their chats, their providers, their tools, and their records. This page is about what happens under the calls, and why the SDK is shaped the way it is. fxbot's own architecture is the same story, told for the app. `@fxbot/sdk` runs bots for your app: their chats, their providers, their tools, and their records. This page is about what happens under the calls, and why the SDK is shaped the way it is. fxbot’s own [architecture](/docs/explanation/architecture/) is the same story, told for the app. ## Two entries [Section titled “Two entries”](#two-entries) The SDK has two entries, for two places. `@fxbot/sdk` runs in your backend, on Node. `createFxbot()` connects to Postgres, brings the database up to date, starts one agent per provider, and runs any turn that a stopped process left open. It holds the key that seals secrets, and every call that touches a key, a token, or a model goes through it. `@fxbot/sdk/client` runs in a page or a script. It talks to a server over HTTP, and has the two pieces a chat needs: a stream reader that reconnects, and `applyLine`, which folds stream lines into turns. It imports nothing from the server side, only the shared types, so a page that bundles it gets no server code and no key. The split is the line between what holds secrets and what shows them. A page can do everything fxbot’s page does, and a key it sends up never comes back to it. ## One agent per provider, one chat per bot [Section titled “One agent per provider, one chat per bot”](#one-agent-per-provider-one-chat-per-bot) A turn runs on [libfx](https://fx.sh/docs/lib), the agent from fx. libfx gives an agent one provider, and a session runs only on the agent that started it. So the SDK starts one libfx agent per provider, and the bots on that provider share it. Each bot has one durable session, its chat. libfx keeps the session in Postgres, step by step, so a turn survives a restart, through [Workflow’s Postgres World](https://workflow-sdk.dev/worlds), in schemas of its own. The SDK keeps everything else in Postgres too: the bots, providers, settings, plugins, the library, memories, and a plain-text copy of every message, which `chat_history` and memory search read. libfx keeps no model or instructions with a session. So each time the SDK opens a bot’s chat, it passes them: the bot’s model, its instructions, in its own chat the summary from a provider switch or a start-over, its newest memories, the team’s, and the list of its skills, within libfx’s 64 KiB. It also passes the bot’s id, which every tool reads to know whose chat it runs in. Moving a bot to another provider can’t move its session, so the bot starts a new one there, from a summary of the old. See [Moving a bot to another provider](/docs/explanation/bots-and-chats/#starting-a-chat-over). ## A turn, end to end [Section titled “A turn, end to end”](#a-turn-end-to-end) 1. `send(id, { text, messageId })` checks the message. On a bot’s first message, it saves a new session id to the bot first, so a restart finds the chat. Files go into the library, and a skill named with `$name` goes along with the text. 2. libfx stores the prompt. The SDK records the message in Postgres, and `send` resolves. The same `messageId` again reaches the same turn and runs nothing new. 3. libfx runs the turn: it asks the model, calls tools as the model asks, and writes each step to the session’s files. 4. `stream(id, cursor)` reads the session’s lines from the cursor on, as libfx writes them, and stays open for more. libfx’s `turn_start` line carries a message only when it was plain text, so the SDK puts back the text and files of a message that sent more. 5. When the turn ends, the SDK records the reply’s text in Postgres, and the start of it as the bot’s `preview`. 6. Each message recorded nudges the embeddings loop, which gives it a vector in the background. Nothing in the turn waits for the page. A reader that leaves and comes back picks up from its cursor, and a turn left open by a stopped process runs again when `createFxbot` starts, with a `turn_resume` line. ## The tools every bot gets [Section titled “The tools every bot gets”](#the-tools-every-bot-gets) Every agent gets the same tools: `chat_history`, the three memory tools, the three library tools, the `skill` tool once there are skills, and the allowed tools of each MCP server, named after it. libfx fixes an agent’s tools when it is made. So a change to them, such as a new MCP server, makes every agent again, one change at a time, after its running turns finish. Since one agent serves every bot on its provider, a tool can’t know its bot from the agent. It reads the bot’s id from the session, never from what the model asks. A memory tool reaches only that bot’s memories, the library tools only its items, and an MCP tool refuses to run in a bot it wasn’t given to. ## Migrations at start [Section titled “Migrations at start”](#migrations-at-start) The schema is a set of numbered SQL files in the SDK, each run once, in order. `createFxbot` runs the ones the database hasn’t seen, in one transaction, under a lock, so two processes starting at once take turns, and a failure keeps none of them. When the database already holds records, it first backs them up: the database with `pg_dump`, and `dataDir` as a tarball, into a folder of `backupsDir`. It keeps the newest five. A database that a newer release has migrated is refused, since its schema may not suit this one. This is why updating the SDK is a pull and a restart. The app needs no migration step of its own. ## Sealed secrets [Section titled “Sealed secrets”](#sealed-secrets) API keys, sign-in tokens, and an MCP server’s header values and OAuth tokens are sealed in the SDK before they reach Postgres. Postgres holds only the ciphertext. The key that seals them is the `secretKey` your app passes to `createFxbot`, so it stays in your backend, and the database never holds it. `rotateSecrets` seals everything again under a new key. Opened secrets stay in the process’s memory, for the requests that need them. The SDK’s answers don’t carry them: a listed provider says only whether it holds a key or a sign-in. Device code and OAuth sign-ins run in the backend too, and hand out only a link, a code, and an id to check on. The security model behind this is in [Security model](/docs/explanation/security/). ## Memories and the embeddings loop [Section titled “Memories and the embeddings loop”](#memories-and-the-embeddings-loop) Each bot keeps memories in Postgres. The newest go into its instructions on every turn, and `memory_search` finds the rest. Search matches words, with Postgres’s full-text search, and meaning, with vectors in pgvector, and fuses the two lists. The vectors come from one loop in the SDK. A saved memory, a recorded message, or a new setting nudges it, and it fills in what’s missing: memories first, then messages, newest first, 32 to a request. They come from the local embedder at `embedUrl`, from a provider’s embedding model, or from nowhere, as the settings say. Each model has vectors of its own, and search compares only the current model’s, so a new model never mixes sizes. The loop never holds up a turn. When the embedder is down, the loop tries again a minute later, and a search that gets no vector within 5 seconds uses words alone. How search ranks: [Search by words and by meaning](/docs/explanation/bots-and-chats/#search-by-words-and-by-meaning). ## TypeScript source in a workspace [Section titled “TypeScript source in a workspace”](#typescript-source-in-a-workspace) The SDK is TypeScript, run as it is. Its package points at `.ts` files, and Node 22.18 and newer strips the types as it loads them, so there is no build step. fxbot’s server runs the same way. Node won’t strip types in a file under `node_modules`. So an app takes the SDK as an npm workspace: `node_modules/@fxbot/sdk` is a link to fxbot’s `packages/sdk`, and Node loads the files from there. Putting the SDK on npm would need a build step, so for now an app takes it from fxbot’s repository, at a release. ## fxbot is one app on it [Section titled “fxbot is one app on it”](#fxbot-is-one-app-on-it) fxbot’s own server and page are built on the SDK, as yours would be. * `packages/server` adds HTTP and nothing more: routes over the SDK’s calls, body limits, the check that a write comes from the page’s own origin, and the page’s files. In a release install, it also asks the machine for updates. A bad input throws an `Error` with a `status`, such as 400 or 404, and the server answers with it. * `packages/ui`, the page, imports only `@fxbot/sdk/client`. So whatever fxbot’s page does, a page of yours can do through the same client, against the same server. And whatever fxbot’s server does, a backend of yours can do through the same SDK. # Work with memories > A bot keeps what it learns as memories: one fact each, in a sentence that stands on its own, of at most 1,000 characters. Bots save their own during turns. Your app can list them, add its own, change them, and remove them, through fxbot.profiles.memories, and keep the team's, which every bot reads, through fxbot.memories. How bots use them: Memories. A bot keeps what it learns as memories: one fact each, in a sentence that stands on its own, of at most 1,000 characters. Bots save their own during turns. Your app can list them, add its own, change them, and remove them, through `fxbot.profiles.memories`, and keep the team’s, which every bot reads, through `fxbot.memories`. How bots use them: [Memories](/docs/explanation/bots-and-chats/#memories). ## See what a bot remembers [Section titled “See what a bot remembers”](#see-what-a-bot-remembers) ```ts const newest = await fxbot.profiles.memories.list(bot.id); for (const m of newest) console.log(`mem:${m.id} ${m.savedBy} ${m.updatedAt.slice(0, 10)} ${m.text}`); ``` The list is newest first, 200 by default, and `limit` takes up to 500. Each memory has its `id`, `text`, `savedBy` (`bot` or `owner`), and when it was made and last changed. A memory the bot saved also has `messageId`: the stored message of the turn it was saved in, which `chat_history` reads as `msg:`. It isn’t the `messageId` your app sent. To search, give a `query`. The best matches come first, by words and, with vectors on, by meaning: ```ts const found = await fxbot.profiles.memories.list(bot.id, { query: "coffee or tea" }); ``` ## Add, change, or remove one [Section titled “Add, change, or remove one”](#add-change-or-remove-one) ```ts const memory = await fxbot.profiles.memories.add(bot.id, "The owner drinks tea, not coffee."); await fxbot.profiles.memories.update(bot.id, memory.id, "The owner drinks green tea, not coffee."); await fxbot.profiles.memories.remove(bot.id, memory.id); ``` * Adding text the bot already has, in other case or spacing, answers with the memory already there. * A change that says what another memory says merges the two: that other memory stays, and comes back. * An id works as `12` or as `mem:12`. * The bot sees the change on its next turn. Its newest memories are in its instructions on every turn, and `memory_search` finds the rest. Text that is empty or over 1,000 characters fails with status 400, and a memory the bot doesn’t have with 404. ## Keep team memories [Section titled “Keep team memories”](#keep-team-memories) Team memories are notes every bot reads, after its own, such as who the owner is, or what the household is. Since 0.10.0, `fxbot.memories` keeps them, with the same calls and checks as a bot’s: ```ts const cats = await fxbot.memories.add("The household has two cats, Miso and Tofu."); const team = await fxbot.memories.list(); // newest first; { query } searches await fxbot.memories.update(cats.id, "The household has two cats: Miso and Tofu."); await fxbot.memories.remove(cats.id); ``` * **Each has `team: true`,** and `savedByBot`: the bot that saved it, when one did, or null for one you added or one whose bot is deleted. * **A bot saves one** with `memory_save` and `team: true`, when the owner asks it to remember something for every bot. * **One of a bot’s own becomes the team’s** with `fxbot.profiles.memories.share(bot.id, memory.id)`. It leaves the bot’s list. If the team already says the same, the bot’s copy goes, and the team’s comes back. * **The same text** can be both a bot’s own and the team’s. A duplicate is the same text in the same set. ## Watch a bot save its own [Section titled “Watch a bot save its own”](#watch-a-bot-save-its-own) During a turn, a bot calls `memory_save`, `memory_search`, and `memory_forget`. They show on the chat’s stream as tool calls, with what the bot passed in `input`, such as the `text` that `memory_save` saves: ```ts if (line.type === "tool_start" && line.name?.startsWith("memory_")) console.log(line.name, line.input); ``` Reading the stream: [Stream replies](/sdk/how-to/stream-replies/). ## Choose where vectors come from [Section titled “Choose where vectors come from”](#choose-where-vectors-come-from) Search by meaning needs vectors from an embedding model. Pick where they come from in the settings: ```ts await fxbot.settings.update({ embedder: "local" }); // the default: the embedder at embedUrl await fxbot.settings.update({ embedder: "remote", embeddingProvider: openai.id, embeddingModel: "text-embedding-3-small" }); await fxbot.settings.update({ embedder: "off" }); // words only ``` * `local` uses the embedder you gave `createFxbot` as `embedUrl`, such as the one that fxbot’s compose file runs. * `remote` uses a provider’s embedding model. The provider must serve embeddings: OpenAI, OpenRouter, AI Gateway, a Vercel account, Ollama, LM Studio, or another OpenAI-style server. The SDK embeds a test string first. If that fails, `update` fails with status 400, and the old setting stays. * `messageVectors` is how many characters of each chat message get a vector, 8,000 by default. `0` gives vectors to memories only. A new model means new vectors for everything. They fill in behind your app, memories first, then messages, newest first. Search keeps working meanwhile, with the vectors the model has made, and with words. ## Check how far vectors have got [Section titled “Check how far vectors have got”](#check-how-far-vectors-have-got) ```ts const status = await fxbot.settings.embedding(); console.log(`${status.model ?? "Off"}: ${status.memoriesWithVectors} of ${status.memories} memories, ${status.withVectors} of ${status.messages} messages`); if (status.error) console.error(status.error); ``` `model` is null when vectors are off, or when the local embedder isn’t answering. `error` is the last thing that went wrong, until vectors fill in again. ## From a page [Section titled “From a page”](#from-a-page) The client has the same calls over fxbot’s HTTP API: `client.profiles.memories.list(id, query)`, `add`, `update`, `remove`, and `share`, `client.memories.list(query)`, `add`, `update`, and `remove` for the team’s, then `client.settings.update(...)` and `client.settings.embedding()`. See [Build a page on the client](/sdk/how-to/web-page/). ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The status says this fxbot has no local embedder.** `createFxbot` got no `embedUrl`. Pass it, or pick `remote` or `off`. * **The status says the local embedder isn’t answering yet.** On its first start, it downloads its model, 310 MB. Until it answers, search uses words alone, and the vectors wait. * **`update` says the embedding model didn’t answer.** The test string failed. Check the model’s id, and that the provider serves it. Ollama must have pulled it first, as with `ollama pull nomic-embed-text`. * **`update` says that provider serves no embeddings.** ChatGPT and Grok plans, and OpenCode keys, serve none. Pick another provider. * **`update` asks for a provider and an embedding model.** `remote` needs both. # Connect providers > A provider is where a bot's model runs. Your backend adds one with fxbot.providers, or with fxbot.signIns for an account. Every provider, and what fxbot reads from it, is in Providers. A provider is where a bot’s model runs. Your backend adds one with `fxbot.providers`, or with `fxbot.signIns` for an account. Each is an entry in fxbot’s list of providers, and its `kind` is the entry’s id. Every provider, and what fxbot reads from it, is in [Providers](/docs/reference/providers/). To see what there is to add, as a page would show it, ask for the list: ```ts const { providers, more } = await fxbot.providers.catalog(); // providers: entries with their group, fields, key page, and steps; more: models.dev's other hosts, for search ``` ## A server on your network [Section titled “A server on your network”](#a-server-on-your-network) For `ollama`, `lmstudio`, `llamacpp`, `vllm`, `litellm`, and `custom`, which is any server with an OpenAI-style Chat Completions API. ```ts const local = await fxbot.providers.add({ kind: "ollama", model: "qwen3:8b" }); ``` * Ollama and LM Studio default to their usual address on this machine. Give `baseUrl` for another, such as `http://192.168.1.20:11434/v1`. A `custom` server needs one. * An address must use `https`, or `http` on localhost. * `apiKey` is for a server that wants a key. Ollama and LM Studio take none. * `modelIds` are model ids for a `custom` server that lists none. * `contextWindow` overrides the context window the server reports, for every model it serves. The server must be running: `add` asks it for its models first. ## An API key [Section titled “An API key”](#an-api-key) For every entry that takes a key, such as `openai`, `groq`, `deepseek`, or `gateway`, and for models.dev’s hosts in `more`, by their id. ```ts const openai = await fxbot.providers.add({ kind: "openai", apiKey: process.env.OPENAI_API_KEY!, model: "gpt-6.1-sol" }); ``` An entry with fields takes them in `fields`, which fill its address: ```ts const bedrock = await fxbot.providers.add({ kind: "bedrock", apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK!, fields: { region: "us-west-2" } }); const azure = await fxbot.providers.add({ kind: "azure", apiKey: azureKey, fields: { resource: "my-resource" }, modelIds: ["my-deployment"] }); ``` Vertex AI takes a service account’s JSON key, as text, in place of a key: ```ts const vertex = await fxbot.providers.add({ kind: "vertex", serviceAccount: readFileSync("service-account.json", "utf8") }); ``` `add` checks the key with the provider, and refuses one the provider rejects. Then the SDK seals the key in Postgres. A listed provider says only `hasKey: true`, never the key. To change a key, update it. It’s checked again: ```ts await fxbot.providers.update(openai.id, { apiKey: newKey }); ``` ## An account, with a sign-in [Section titled “An account, with a sign-in”](#an-account-with-a-sign-in) For `chatgpt`, `grok`, `vercel`, `huggingface`, and `orcarouter` by device code, and `openrouter`, which shows a code to paste, or comes back to your page. The person signs in on any device, and the SDK claims the tokens or the key on your backend. 1. Start the sign-in, and show its link and code: ```ts const signIn = await fxbot.signIns.start({ kind: "chatgpt" }); console.log(`Open ${signIn.verificationUrl} and enter ${signIn.userCode}`); ``` OpenRouter’s `way` is `paste` unless you pass the page’s own HTTPS or localhost origin, when it’s `redirect`. Send the person to `signIn.url`, then pass the code they paste to `signIns.code(signIn.id, code)`, or route `/api/sign-ins//callback` to `signIns.callback(id, query)`. 2. Ask how it’s going until it’s done. A finished sign-in names the new provider: ```ts import { setTimeout as sleep } from "node:timers/promises"; let provider: string | undefined; while (!provider) { await sleep(2000); const status = fxbot.signIns.get(signIn.id); if (status.status === "failed") throw new Error(status.error); provider = status.provider; } ``` 3. For a Vercel account with more than one team, pick the team to bill: ```ts const teams = await fxbot.providers.teams(provider); await fxbot.providers.update(provider, { teamId: teams[0].id }); ``` One sign-in runs at a time: a new one replaces one still waiting. `signIns.cancel(id)` stops one. To sign in again to a provider you have, as after a failed refresh, pass its id: `signIns.start({ kind: "chatgpt", provider: id })`. A Vercel account needs a Vercel OAuth app that may use device codes, and Hugging Face fxbot’s Hugging Face app. The list of providers names Hugging Face’s. Vercel doesn’t let fxbot’s app use device codes yet, so its sign-in is off. Or pass your own apps’ ids to `createFxbot` as `vercelClientId` and `hfClientId`. ## Then: models and bots [Section titled “Then: models and bots”](#then-models-and-bots) 1. List the provider’s models, and pick its default model: ```ts const models = await fxbot.providers.models(openai.id); // ids, with a context window, tool use, and images when known await fxbot.providers.update(openai.id, { model: "gpt-6.1-sol" }); ``` 2. Make it the default provider, so new bots start on it: ```ts await fxbot.settings.update({ defaultProvider: openai.id }); const bot = await fxbot.profiles.create({ name: "Scout" }); ``` Or give a bot its provider, and a model of its own, when you make it: `profiles.create({ name, provider, model })`. A bot with no model follows its provider’s default. 3. To move a bot to another provider, update it: ```ts await fxbot.profiles.update(bot.id, { provider: local.id, model: "qwen3:8b" }); ``` A bot with a chat starts a new one there, from a summary of the old one. See [Moving a bot to another provider](/docs/explanation/bots-and-chats/#starting-a-chat-over). `providers.remove(id)` removes a provider that no bot uses. ## From a page [Section titled “From a page”](#from-a-page) The client has the same calls over fxbot’s HTTP API: `client.providers.catalog()`, `client.providers.add(...)`, `client.signIns.start(kind)`, `client.signIns.get(id)`, and `client.signIns.code(id, code)`. A key goes up to the server once and never comes back. See [Build a page on the client](/sdk/how-to/web-page/). ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **`add` says the provider rejected this key.** It answered 401 or 403, or a status its entry names, such as xAI’s 400. Check the key, and that it’s for that provider and its region. * **`add` can’t reach a server on your network.** Start the server first, and check `baseUrl`. Ollama’s ends in `/v1`. * **`signIns.start` asks for `FXBOT_VERCEL_CLIENT_ID` or `FXBOT_HF_CLIENT_ID`.** Pass `vercelClientId` or `hfClientId` to `createFxbot`. * **A ChatGPT sign-in fails.** The account or workspace must allow device code sign-in. The error says how to turn it on. * **`send` says there’s no model.** Give the provider a default model, as in step 1, or give the bot one. * **`send` says the bot has no provider.** Set a default provider before you make bots, or give each bot one. * **`providers.remove` says bots use the provider.** Move them to another provider first. # Use the SDK in a project > Add @fxbot/sdk to a Node app of your own, with Postgres and the local embedder beside it. The SDK isn't on npm yet. It's TypeScript source in fxbot's repository, and your app takes it from there through an npm workspace. Add `@fxbot/sdk` to a Node app of your own, with Postgres and the local embedder beside it. The SDK isn’t on npm yet. It’s TypeScript source in fxbot’s repository, and your app takes it from there through an npm workspace. You need Node 22.18 or newer, git, and podman or docker. 1. Make the project’s folder, and clone fxbot inside it: ```sh mkdir my-bot && cd my-bot git clone --depth 1 https://github.com/iammrduncan/fxbot ``` `main` holds releases only, so this is the newest release. To pin one, add `--branch v0.3.0`. A git submodule works the same way: `git submodule add https://github.com/iammrduncan/fxbot`. 2. Write `package.json`, with the SDK’s folder as a workspace: ```json { "name": "my-bot", "private": true, "type": "module", "workspaces": ["fxbot/packages/sdk"], "dependencies": { "@fxbot/sdk": "*" } } ``` Node runs TypeScript as it is, but not from inside `node_modules`. With the workspace, `node_modules/@fxbot/sdk` is a link to `fxbot/packages/sdk`, and Node loads the SDK from there. 3. Install: ```sh npm install ``` This installs the SDK’s packages, with libfx’s native addon for your machine’s CPU. 4. Make the key that seals secrets, and a database password, and write them to `.env`: ```sh openssl rand -base64 32 > secret.key && chmod 400 secret.key pw=$(openssl rand -hex 16) printf '%s\n' "FXBOT_DB_PASSWORD=$pw" "FXBOT_DATABASE_URL=postgres://fxbot:$pw@127.0.0.1:5433/fxbot_dev" FXBOT_EMBED_URL=http://127.0.0.1:8081/v1 FXBOT_SECRET_KEY_FILE=secret.key > .env ``` The SDK seals every API key and token it stores with `secret.key`. Keep the file for as long as you keep the database: without it, they can’t be opened again. 5. Start Postgres, with pgvector, on 127.0.0.1:5433, and the local embedder for memory search on 127.0.0.1:8081. fxbot’s own compose file runs both: ```sh podman compose -f fxbot/deploy/compose.dev.yaml --env-file .env up -d # or docker compose ``` The embedder downloads its model, 310 MB, on its first start. Until it answers, memory search uses words alone. The compose project is called `fxbot-dev`, the same as a checkout of fxbot’s. If one already runs on this machine, give yours a name and ports of its own in `.env`: `COMPOSE_PROJECT_NAME=my-bot`, then `FXBOT_DB_PORT` and `FXBOT_EMBED_PORT`, with the same ports in `FXBOT_DATABASE_URL` and `FXBOT_EMBED_URL`. 6. Write `bot.ts`: ```ts import { readFileSync } from "node:fs"; import { createFxbot } from "@fxbot/sdk"; const fxbot = await createFxbot({ databaseUrl: process.env.FXBOT_DATABASE_URL!, secretKey: readFileSync(process.env.FXBOT_SECRET_KEY_FILE!, "utf8"), embedUrl: process.env.FXBOT_EMBED_URL, syncRegistry: false, }); console.log(await fxbot.profiles.list()); await fxbot.close(); ``` `syncRegistry: false` skips the copy of GitHub’s MCP registry and the read of fxbot’s lists when the app starts. An app that doesn’t search for MCP servers doesn’t need them. Every option is in [createFxbot](/sdk/reference/create-fxbot/). 7. Run it: ```sh node --env-file=.env bot.ts ``` On the first start, `createFxbot` brings the empty database up to date and prints `fxbot migrated the database:`, with the migrations it ran. Then the script prints `[]`: there are no bots yet. The SDK keeps plugins’ files in `data/` and its backups in `backups/`, in the folder the app runs from. Chats are in the database. `dataDir` and `backupsDir` move them. Keep `.env`, `secret.key`, `data/`, `backups/`, and `node_modules/` out of git, and `fxbot/` too unless it’s a submodule. ## Type-check it [Section titled “Type-check it”](#type-check-it) An editor or `tsc` needs fxbot’s TypeScript settings. The SDK’s own source needs the DOM library, even on a server. 1. Install TypeScript and Node’s types: ```sh npm install -D typescript @types/node@22 ``` 2. Write `tsconfig.json`: ```json { "compilerOptions": { "target": "ES2023", "lib": ["ES2023", "DOM"], "module": "ESNext", "moduleResolution": "bundler", "customConditions": ["node"], "types": ["node"], "strict": true, "noEmit": true, "skipLibCheck": true, "allowImportingTsExtensions": true, "verbatimModuleSyntax": true, "erasableSyntaxOnly": true }, "include": ["*.ts"] } ``` `include` names your own files. Change it to where your code lives, and leave `fxbot/` out: `tsc` checks the SDK through your imports, and fxbot’s other packages need settings of their own. 3. Check: ```sh npx tsc ``` ## Update the SDK [Section titled “Update the SDK”](#update-the-sdk) 1. Read the release’s section of the [changelog](/docs/reference/changelog/). A release that adds migrations says so under **Before upgrading**. 2. Pull the new release, or check out its tag, and install again: ```sh git -C fxbot pull npm install ``` 3. Start your app. `createFxbot` runs the new migrations, after backing up the database and `data/` into `backups/`. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **`npm install` can’t find `@fxbot/sdk`.** npm looked for it on the registry, where it isn’t. Check that `workspaces` names `fxbot/packages/sdk`, the folder with the SDK’s own `package.json`. * **Node refuses to strip types in `node_modules`.** The SDK was copied into `node_modules` instead of linked. Use the workspace from step 2, and run `npm install` again. * **`createFxbot` says memories need pgvector.** The database lacks the extension. Use the database that the compose file runs, which has it. * **`createFxbot` says it can’t back up before migrating.** The backup runs the machine’s `pg_dump`, which must be Postgres 17’s, such as from `postgresql-client-17`. Nothing was migrated. * **`createFxbot` says the database has a migration from a newer fxbot.** A newer SDK has run on this database. Update `fxbot/` to that release or newer. * **`createFxbot` says the secret key must be 32 random bytes in base64.** `FXBOT_SECRET_KEY_FILE` names the wrong file, or the file holds something else. * **Compose says the port is in use.** Something else has 5433 or 8081. Set `FXBOT_DB_PORT` or `FXBOT_EMBED_PORT` in `.env`, as in step 5. # Stream replies > Show a bot's reply while it's written, in a Node app on @fxbot/sdk. fxbot.send() resolves once libfx has stored the message. The reply comes on fxbot.stream(): the bot's chat as NDJSON, one JSON object per line, which applyLine from @fxbot/sdk/client folds into turns. Show a bot’s reply while it’s written, in a Node app on `@fxbot/sdk`. `fxbot.send()` resolves once libfx has stored the message. The reply comes on `fxbot.stream()`: the bot’s chat as NDJSON, one JSON object per line, which `applyLine` from `@fxbot/sdk/client` folds into turns. In a page or a script on fxbot’s server, the client’s `stream()` does all of this for you: see [Build a page on the client](/sdk/how-to/web-page/). ## Read a reply [Section titled “Read a reply”](#read-a-reply) 1. Add a reader that turns the stream’s bytes into lines: ```ts import type { Fxbot, StreamLine } from "@fxbot/sdk"; // Every line of a bot's chat after `cursor`, parsed, until the loop that reads it stops. async function* lines(fxbot: Fxbot, botId: string, cursor = 0): AsyncGenerator { const reader = (await fxbot.stream(botId, cursor)).getReader(); const decoder = new TextDecoder(); let rest = ""; let epoch = 0; try { for (;;) { const { value, done } = await reader.read(); if (done) return; const parts = (rest + decoder.decode(value, { stream: true })).split("\n"); rest = parts.pop()!; for (const part of parts) { if (!part) continue; const line: StreamLine = JSON.parse(part); // libfx's rule: hide a line whose epoch is lower than one before it. if (line.epoch !== undefined && line.epoch < epoch) continue; epoch = line.epoch ?? epoch; yield line; } } } finally { await reader.cancel(); } } ``` A chunk can end in the middle of a line, so the last piece waits for the next chunk. Leaving the loop that reads the lines cancels the stream. 2. Send a message, with an id you make: ```ts const messageId = crypto.randomUUID(); await fxbot.send(bot.id, { text: "What's on today?", messageId }); ``` An id is 1 to 128 letters, digits, `.`, `_`, or `-`. The same id again reaches the same turn and runs nothing new, so you can send again after a failed request. 3. Read the chat, fold each line into the turns, and print the reply’s text as it comes: ```ts import { applyLine, type Turn } from "@fxbot/sdk/client"; let cursor = 0; let turns: Turn[] = []; for await (const line of lines(fxbot, bot.id, cursor)) { cursor = line.cursor ?? cursor; turns = applyLine(turns, line); if (line.messageId !== messageId) continue; if (line.type === "text_delta") process.stdout.write(line.delta ?? ""); if (line.type === "turn_end") break; } const turn = turns.find((t) => t.messageId === messageId)!; if (turn.note) console.error(turn.note); ``` The stream replays the chat from the cursor, then stays open for new lines. From 0, it replays the whole chat, so the loop skips lines of other turns. It stops at the `turn_end` of this message. 4. Keep `cursor` for the next message. A stream opened from it starts after the last line you read, so the next reply comes without a replay. `applyLine` gives one `Turn` per message: its `text`, its `reply` text, its `parts` in order (thinking, text, and tool calls with their input and result), and `done` once its `turn_end` has come. `note` says how a turn ended when it didn’t end normally, such as `Error: …` or `Stopped: max_output_tokens`. All the fields are in [The client](/sdk/reference/client/). ## The lines [Section titled “The lines”](#the-lines) Each line has a `type`. A line of a turn has the turn’s `messageId`, and every line has a `cursor`. | Type | What it carries | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `turn_start` | A turn began. `input` is the message’s text, and `files` the files it sent. | | `text_delta` | The next piece of the reply, in `delta`. | | `reasoning_delta` | The next piece of the model’s thinking, in `delta`, when the provider sends it. | | `tool_start` | A tool call: its `id`, `name`, and `input`, or `inputPreview` for an input over 64 KiB. | | `tool_end` | The call’s result, by the same `id`: `content`, and `isError` when it failed. | | `user_message` | A message joined the running turn, whose `messageId` this has. `id` is the message’s own, `text` its words, and `files` and `from` as on `turn_start`. Since 0.6.0. | | `turn_end` | The turn ended, and `stopReason` says how: `end_turn` normally, another reason such as `max_output_tokens`, or `error`, with the reason in `error`. | | `turn_resume` | A turn left open by a stopped process runs again. Its reply starts over. | libfx writes more types, such as `idle`, which has no `messageId`. `applyLine` passes over the lines it doesn’t use. ## Pick up after a restart [Section titled “Pick up after a restart”](#pick-up-after-a-restart) When your app starts, `createFxbot` runs again any turn that a stopped process left open. Its lines come with `turn_resume`, and `applyLine` starts its reply over. Save `cursor` where your app keeps its state. After a restart, or when a stream ends early, open the stream again from that cursor. ## Pass the stream on over HTTP [Section titled “Pass the stream on over HTTP”](#pass-the-stream-on-over-http) A server can hand the stream to its own clients as it is. This is what fxbot’s server does at `/api/profiles//stream?cursor=`, which the client’s `stream()` reads: ```ts import { Readable } from "node:stream"; import { pipeline } from "node:stream/promises"; import type { ReadableStream } from "node:stream/web"; const body = await fxbot.stream(botId, Number(url.searchParams.get("cursor") ?? 0)); res.writeHead(200, { "content-type": "application/x-ndjson", "cache-control": "no-store" }).flushHeaders(); // A closed response cancels the stream. await pipeline(Readable.fromWeb(body as ReadableStream), res).catch(() => {}); ``` ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The stream ends at once, with no lines.** The bot has no chat yet, or its provider is gone. Send the first message before you open the stream. * **`send` fails with status 400.** The message has no text, its id breaks the rules in step 2, or the bot has no provider or model. The error says which. * **The script crashes with `CONNECTION_ENDED` right after a reply.** Before 0.4.0, `close()` didn’t wait for the SDK to save a reply that just finished. Update the SDK, or keep the app running between turns and call `close()` when it shuts down. * **The reply shows twice.** A turn ran again after a restart: its `turn_resume` line starts the reply over. Fold lines with `applyLine` rather than adding up `text_delta`s yourself. # Give bots tools > Every bot comes with tools to search its own chats, keep memories, and use the library. Give bots more with plugins, through fxbot.plugins: remote MCP servers, whose tools they call, and skills, which they read. A package can carry both, with code of its own: see Write a plugin. Every bot comes with tools to search its own chats, keep memories, and use the library. Give bots more with plugins, through `fxbot.plugins`: remote MCP servers, whose tools they call, and skills, which they read. A package can carry both, with code of its own: see [Write a plugin](/sdk/how-to/write-a-plugin/). Until Settings’ `unvetted` is true, `preview` and `add` take only what fxbot’s own lists name, and fail with 400 for an address, a public registry’s entry, or a skills.sh skill. Turn it on first: `await fxbot.settings.update({ unvetted: true })`. ## The tools every bot has [Section titled “The tools every bot has”](#the-tools-every-bot-has) | Tool | What it does | | ------------------------------------------------ | -------------------------------------------------------------------------------------------- | | `chat_history` | Searches the bot’s own messages across all its chats, and reads them in full around a match. | | `memory_save`, `memory_search`, `memory_forget` | Keep the bot’s memories. See [Work with memories](/sdk/how-to/memories/). | | `library_search`, `library_read`, `library_save` | Find, open, and save files in the library, only those tagged for the bot. | | `skill` | Reads one of the bot’s skills. Bots have it once you add a skill. | Each tool finds its bot from the chat it runs in, never from what the model asks. ## Add an MCP server by its address [Section titled “Add an MCP server by its address”](#add-an-mcp-server-by-its-address) 1. Look at the server first. `preview` connects without credentials, and answers with its name, how it signs in (`none`, `headers`, or `oauth`), its tools when it lists them without a sign-in, and a `hash`: ```ts import type { McpPreview } from "@fxbot/sdk"; const ref = { url: "https://mcp.example.com/mcp" }; const page = (await fxbot.plugins.preview(ref)) as McpPreview; console.log(page.name, page.auth, page.tools?.map((t) => t.name)); ``` For a server that takes a key, name its header in the ref, such as `{ url, headers: ["Authorization"] }`. 2. Add it with that hash. If the server changed since the preview, `add` fails with status 409: look at it again. ```ts const server = await fxbot.plugins.add(ref, page.hash); ``` 3. Give it what it needs to connect. For a key, set the header’s value: ```ts await fxbot.plugins.setSecrets(server.id, { headers: { Authorization: `Bearer ${key}` } }); ``` Values go in once and are sealed. A listed server says only `signedIn: true`. For OAuth, see [Sign in with OAuth](#sign-in-with-oauth). 4. Allow the tools bots may call. At first, only the server’s read-only tools are allowed. Name every tool to allow, by the server’s own name for it: ```ts await fxbot.plugins.change(server.id, { allowed: ["search_issues", "create_issue"] }); ``` `plugins.list()` shows each server’s `tools`, each with `readOnly`, its `allowed` list, and its `status`, such as `Connected`. A server that signs in lists its tools once it connects. 5. To give the server to some bots only, choose them one by one: ```ts await fxbot.plugins.change(server.id, { bots: "each" }); await fxbot.plugins.forBot(bot.id, server.id, true); ``` Bots see each tool under the server’s name, such as `linear_create_issue`. ## Add a server from a registry [Section titled “Add a server from a registry”](#add-a-server-from-a-registry) Search fxbot’s list of servers and its copy of GitHub’s MCP registry, then add an entry by its name: ```ts import type { McpSearch } from "@fxbot/sdk"; const { cards } = (await fxbot.plugins.search("linear", {})) as McpSearch; const ref = { registry: cards[0].name, from: cards[0].from }; const page = (await fxbot.plugins.preview(ref)) as McpPreview; const server = await fxbot.plugins.add(ref, page.hash); ``` Then carry on from step 3 above. A card’s `from` is `fxbot` for fxbot’s list, `github` for GitHub’s registry, or `official`. `{ everything: true }` adds the official registry’s results, for searches of 3 characters or more. The copy of GitHub’s registry fills in when `createFxbot` starts and every hour after. An app started with `syncRegistry: false` has nothing to search until a sync has run. It can still add an entry by its name: `{ registry: "" }`. ## Sign in with OAuth [Section titled “Sign in with OAuth”](#sign-in-with-oauth) For a server whose `auth` is `oauth`. 1. Start the sign-in, and send the person to its `url`: ```ts const attempt = await fxbot.oauth.start(server.id, origin); console.log(`Open ${attempt.url}`); ``` 2. Finish it the way its `mode` says: * `redirect`: the browser comes back to `/api/oauth/callback`. `origin` is your page’s own, and must be HTTPS. Route that path in your server to `fxbot.oauth.callback(url.searchParams)`. * `paste`: the browser goes to the `localUrl` you gave `createFxbot`, `http://127.0.0.1:8787` by default, at `/callback`. Serve that path with `fxbot.oauth.callback` too. Where nothing serves it, the page fails to load: pass its address, copied from the browser, to `fxbot.oauth.paste(attempt.id, address)`. 3. Ask `fxbot.oauth.get(attempt.id)` until its `status` is `done` or `failed`. A sign-in expires after 10 minutes. A server that registers no apps itself needs your own OAuth app: register one with it, then pass it with `setSecrets(server.id, { clientId, clientSecret })`. ## Add a skill [Section titled “Add a skill”](#add-a-skill) 1. Find it in fxbot’s own skills, or on skills.sh for 2 characters or more: ```ts import type { SkillPreview, SkillSearch } from "@fxbot/sdk"; const { cards } = (await fxbot.plugins.search("frontend", { kind: "skill" })) as SkillSearch; const ref = { skill: cards[0].id }; // // ``` 2. Look at it. `preview` reads the skill from its repository’s current commit: ```ts const page = (await fxbot.plugins.preview(ref)) as SkillPreview; if (page.error) throw new Error(page.error); console.log(page.text); // its SKILL.md ``` 3. Add it with the hash: ```ts const skill = await fxbot.plugins.add(ref, page.hash); ``` Each bot’s instructions now list its skills, and the `skill` tool reads one when a task needs it. To be sure a bot uses a skill, name it in a message: `$name` anywhere, or `/name` at the start, sends the skill along with it: ```ts await fxbot.send(bot.id, { text: "/frontend-design A page for a bakery", messageId: crypto.randomUUID() }); ``` `profiles.skills(bot.id)` lists the names a bot takes. Skills go to all bots, or to chosen ones with `change` and `forBot`, as servers do. ## Keep plugins up to date [Section titled “Keep plugins up to date”](#keep-plugins-up-to-date) `plugins.list()` marks a plugin whose source changed. Its `mark.kind` is `update`, with the newer `version`, or `deprecated`, or `removed`. Nothing changes by itself. To move one to its newer version, look at it again from the same source, then update it with that hash: ```ts for (const addon of await fxbot.plugins.list()) { if (addon.mark?.kind !== "update") continue; const ref = addon.kind === "skill" ? { skill: addon.source.skill } : { registry: addon.source!.registry, from: addon.source!.from, allowLocal: addon.allowLocal }; const page = await fxbot.plugins.preview(ref); await fxbot.plugins.update(addon.id, page.hash); } ``` The skills’ repositories are checked every hour. `plugins.check()` checks them now. `change(id, { enabled: false })` turns a plugin off, and `remove(id)` removes it. A change to the tools bots have makes the agents again, after their running turns finish. ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **`add` or `update` fails with status 409.** The server or skill changed since its preview. Look at it again, and use the new hash. * **`preview` says the address is local.** A server on this machine or a private network needs `allowLocal: true` in the ref. It may then use `http`. Use it only for a server you run. * **The server’s `status` is `Add its header values`.** Set them with `setSecrets`. Header names must be the ones the ref named. * **The server’s `status` is `Sign in to use it`.** Run the OAuth sign-in above. * **A tool call fails, saying the tool is not allowed.** Add it to `allowed` with `change`. * **The preview has `local: true`, and `add` refuses it.** That entry runs as a program on this machine, not as a remote server, and the SDK can’t add it yet. * **The MCP search finds nothing.** The registry’s copy hasn’t synced: see [Add a server from a registry](#add-a-server-from-a-registry). fxbot’s own page does the same in Plugins: [Add an MCP server](/docs/how-to/add-an-mcp-server/) and [Add a skill](/docs/how-to/add-a-skill/). # Build a page on the client > Build a web page of your own on @fxbot/sdk/client, against fxbot's server. The client is a typed wrapper for the server's HTTP API, with the stream reader and applyLine. It carries no credentials: keys go to the server once and never come back. Build a web page of your own on `@fxbot/sdk/client`, against fxbot’s server. The client is a typed wrapper for the server’s HTTP API, with the stream reader and `applyLine`. It carries no credentials: keys go to the server once and never come back. You need: * fxbot’s server, running: a release install, which answers on 127.0.0.1:8787, or `npm run server` in a [checkout](/docs/how-to/checkout-beside-release/). * A project with the SDK as a workspace: steps 1 to 3 of [Use the SDK in a project](/sdk/how-to/set-up/). A page needs no database or key of its own. The steps use [Vite](https://vite.dev), as fxbot’s own page does. It compiles the client’s TypeScript along with yours. 1. Install Vite: ```sh npm install -D vite ``` 2. Proxy `/api` to fxbot’s server, in `vite.config.ts`: ```ts import { defineConfig } from "vite"; export default defineConfig({ server: { proxy: { "/api": { target: "http://127.0.0.1:8787" } }, }, }); ``` The server refuses a write whose `Origin` doesn’t match its `Host`, and sends no CORS headers. So the page reaches it through a proxy on the page’s own origin. Use the object form: Vite’s string form, `"/api": "http://127.0.0.1:8787"`, sets `changeOrigin`, which sends the server’s own host, and every write fails. 3. Write `index.html`: ```html My bot

   
``` 4. Write `main.ts`. It shows the first bot’s chat, and sends what you type: ```ts import { applyLine, createClient, type Turn } from "@fxbot/sdk/client"; const client = createClient(); // the page's own origin const log = document.querySelector("#log")!; const form = document.querySelector("form")!; const input = form.querySelector("input")!; const [bot] = await client.profiles.list(); let turns: Turn[] = []; form.addEventListener("submit", (event) => { event.preventDefault(); const text = input.value.trim(); input.value = ""; if (text) client.send(bot.id, { text, messageId: crypto.randomUUID() }).catch((error) => alert(error.message)); }); // Replays the chat, then each new line. It reconnects by itself after a drop. for await (const line of client.stream(bot.id)) { turns = applyLine(turns, line); log.textContent = turns.map((t) => `> ${t.text}\n${t.reply}${t.note ? `\n(${t.note})` : ""}`).join("\n\n"); } ``` 5. Start it, and open the address Vite prints: ```sh npx vite ``` The page needs a bot. Make one in fxbot’s own page, or from yours with `client.profiles.create({ name, provider })`. ## What the client does [Section titled “What the client does”](#what-the-client-does) * Each call throws an `Error` with the server’s message, or `Cannot reach the server.` when no answer comes. * `client.stream(id, { cursor, signal, onConnection, onCaughtUp })` replays the chat from `cursor`, 0 by default, then waits for new lines. `onCaughtUp` hears the replay end. After a drop, it asks again from the last cursor every 2 seconds, and `onConnection` hears it go and come back. It hides lines from an older epoch, as libfx asks. Abort `signal` to stop it. * `send` resolves once the server has stored the message. The reply comes on the stream. * `client.providers.add({ kind, apiKey })` sends a key once. A listed provider says only `hasKey`. * `createClient({ onVersion })` hears the server’s version on every answer, so a page can notice a new release. Every call is in [The client](/sdk/reference/client/), and the routes behind them in [HTTP API](/sdk/reference/http-api/). ## In production [Section titled “In production”](#in-production) Build the page: ```sh npx vite build ``` Then serve `dist/` and `/api` from one origin, with a reverse proxy in front of both. It must pass the `Host` header on as the browser sent it, and pass the stream’s lines on as they come, without buffering. fxbot’s server has no login of its own, and the client sends no credentials, so whoever reaches the page can use all of fxbot through it. Where to put it: see [Reach fxbot from other devices](/docs/how-to/reach-it/). ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **Writes fail with `This request came from another site.`** The proxy changed `Host`, or the page calls the server from another origin. Use the object form in step 2, without `changeOrigin`. * **Every call says `Cannot reach the server.`** The proxy can’t reach fxbot’s server, or something answered with a page that isn’t JSON. Check that `curl http://127.0.0.1:8787/api/health` answers. * **A reply shows up all at once, at its end.** A proxy holds the stream back. Turn buffering off for `/api/profiles//stream`. * **The chat stays empty.** The bot has no chat until its first message. The stream asks again every 2 seconds, and shows it once you send one. # Write a plugin > A plugin changes fxbot itself: server code that runs in fxbot's own process, and as much as it needs of page code, tables, settings, skills, and remote MCP servers. This guide writes one in a checkout of fxbot, which loads it from its folder and again each time you change it, then publishes it on GitHub. Every call is in Plugin API. A plugin changes fxbot itself: server code that runs in fxbot’s own process, and as much as it needs of page code, tables, settings, skills, and remote MCP servers. This guide writes one in a checkout of fxbot, which loads it from its folder and again each time you change it, then publishes it on GitHub. Every call is in [Plugin API](/sdk/reference/plugin-api/). You need a checkout of fxbot that runs with `npm run dev`: see [Run from a checkout](https://github.com/iammrduncan/fxbot#run-from-a-checkout) in the README. ## 1. Make the plugin [Section titled “1. Make the plugin”](#1-make-the-plugin) 1. Make its folder: ```sh mkdir -p my-plugins/hello/fxbot ``` 2. Write `my-plugins/hello/plugin.json`: ```json { "name": "hello", "version": "0.1.0", "description": "Greets people", "extensions": { "sh.fxbot": { "server": "./fxbot/server.ts" } } } ``` The name is the plugin’s id in fxbot: up to 40 lowercase letters, digits, and dashes. Bots see its tools as `hello_`, its routes are under `/api/plugins/hello/`, and its tables are in the schema `plugin_hello`. fxbot’s own fields go under `sh.fxbot`, so the rest of the file stays the [Agent Plugins](https://github.com/agentplugins/agent-plugins-spec) manifest that other agents read. 3. Write `my-plugins/hello/fxbot/server.ts`: ```ts import type { PluginApi } from "@fxbot/sdk"; export default function setup(fx: PluginApi) { let greeted = 0; // A tool, which bots see as hello_greet. fx.tool({ name: "greet", description: "Greet someone by name", inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] }, idempotent: true, execute: (input: { name: string }) => (greeted++, `Hello, ${input.name}!`), }); // A line in the instructions of every chat it's on for. fx.on("instructions", (event) => { event.instructions.push("When someone asks you to greet a person, use hello_greet."); }); // A route, at /api/plugins/hello/count. fx.route("GET", "/count", () => Response.json({ greeted })); } ``` The import is for types only: Node erases it, so the plugin needs nothing installed to run. For an editor’s types, open the folder in a project that has the SDK, as in [Use the SDK in a project](/sdk/how-to/set-up/). ## 2. Load it [Section titled “2. Load it”](#2-load-it) 1. Name its folder in the checkout’s `.env`, as an absolute path. Separate more than one with `:`. ```sh FXBOT_PLUGIN_DIRS=/path/to/my-plugins/hello ``` 2. Start `npm run dev` again. fxbot adds the plugin on first sight, and the API’s output says `[plugin hello] loaded 0.1.0`. It’s in **Plugins**, under **Installed**. 3. Ask a bot to greet someone. Its reply shows a call of `hello_greet`. 4. Read the count from the route: ```sh curl http://127.0.0.1:8788/api/plugins/hello/count ``` Change `server.ts`, and fxbot loads the plugin again a moment later. A plugin whose setup throws stays added but off, with the error on its row in **Plugins**, and in its log. ## 3. Add a page [Section titled “3. Add a page”](#3-add-a-page) 1. Write `fxbot/page.jsx`. It gets React and `@fxbot/app` from the page: ```jsx import { useEffect, useState } from "react"; import { api, ui } from "@fxbot/app"; function Count() { const [greeted, setGreeted] = useState(null); useEffect(() => { api("/count").then((res) => res.json()).then((body) => setGreeted(body.greeted)); }, []); return (
Greeted {greeted ?? "…"} times.
); } export default function setup(app) { app.nav({ label: "Hello", path: "/count" }); app.route("/count", Count); } ``` 2. Build it into one CommonJS file that leaves React and `@fxbot/app` out. [rolldown](https://rolldown.rs) comes with the checkout’s packages: ```sh npx rolldown /path/to/my-plugins/hello/fxbot/page.jsx --format cjs -e react -e react/jsx-runtime -e @fxbot/app --file /path/to/my-plugins/hello/fxbot/page.js ``` Run it in the checkout, where `npx` finds rolldown. 3. Name it in `plugin.json`, beside `server`: `"page": "./fxbot/page.js"`. 4. Reload the page. The sidebar’s footer has an **H** button, which opens `/hello/count`. The page’s styles hold only the classes the app uses. The app’s components, in `ui`, bring their own looks. For more, name a CSS file in `plugin.json` as `css`. ## 4. Keep data [Section titled “4. Keep data”](#4-keep-data) 1. Name a folder of migrations in `plugin.json`: `"migrations": "./fxbot/migrations"`. 2. Write `fxbot/migrations/0001_greetings.sql`: ```sql create table greetings (name text not null, at timestamptz not null default now()); ``` 3. Use the table with `fx.sql`, which is in the plugin’s own schema: ```ts execute: async (input: { name: string }) => { await fx.sql`insert into greetings (name) values (${input.name})`; return `Hello, ${input.name}!`; }, ``` Each file runs once, in name order, in a transaction. Add a new file for each change, and never change one that has shipped. Removing the plugin drops its schema. ## 5. Take settings [Section titled “5. Take settings”](#5-take-settings) 1. Declare them in `plugin.json`, under `sh.fxbot`: ```json "settings": [ { "name": "greeting", "description": "The word to greet with", "default": "Hello" }, { "name": "apiKey", "description": "A key for the greeting service", "isSecret": true } ] ``` 2. Read them as `fx.settings.greeting`. The object stays up to date, and `fx.on("settings", …)` hears a change. The owner sets them on the plugin’s tab in **Settings**. A secret one is sealed, and the page never gets it back. ## 6. Need another plugin [Section titled “6. Need another plugin”](#6-need-another-plugin) A plugin can build on another. The browser plugin has no code: it gives the computer setup steps, which install a browser on every bot’s computer. 1. Name the plugin you need under `sh.fxbot`’s `needs`, with an object for it. What the object holds is up to that plugin: the computer takes `setup`, a list of shell steps for its image. ```json "needs": { "computer": { "setup": ["apt-get update && apt-get install -y --no-install-recommends chromium"] } } ``` 2. The owner adds the plugin you need first: your plugin’s page says what it needs, and **Add** waits for it. Yours loads after it, and while yours is added, it can’t be removed. 3. The plugin you need reads every plugin’s object with `fx.dependents()`, and hears a change with `fx.on("dependents", …)`. ## 7. Say which fxbot it needs [Section titled “7. Say which fxbot it needs”](#7-say-which-fxbot-it-needs) Set `minFxbot` in `plugin.json` to the oldest fxbot your plugin runs on, and raise it when you start using something newer. The [Plugin API](/sdk/reference/plugin-api/#which-fxbot-it-runs-on) says `Since` on what’s new: ```json { "extensions": { "sh.fxbot": { "minFxbot": "0.6.0", "server": "./fxbot/server.ts" } } } ``` An owner on an older fxbot can’t add it, or update to it, and is told what it needs. When a later release breaks something your plugin uses, it shows as **Unsupported**, with what to change. Change it, raise `minFxbot` to that release, and push. ## 8. Publish it [Section titled “8. Publish it”](#8-publish-it) 1. Push the plugin’s folder to a public GitHub repository, at its root or in a folder of it. 2. Anyone can add it from **Plugins**, on **Browse**, under **From GitHub**: `owner/repo`, or `owner/repo/folder`. That’s there once they turn on unvetted plugins in Settings › Plugins, since fxbot doesn’t vet it. fxbot pins it to the commit that its page showed. 3. When you push a change that touches its files, fxbot marks it **Update available** within the hour, and shows the owner what changes before it moves. A plugin can also carry skills, as `skills//SKILL.md`, and remote MCP servers, in `mcp.json`. To ask for a place in fxbot’s own list, open a pull request that adds it to `packages/sdk/src/plugins-registry.json`. # The client > @fxbot/sdk/client is a typed client for an fxbot server's HTTP API, for a page or a script. `@fxbot/sdk/client` is a typed client for an fxbot server’s [HTTP API](/sdk/reference/http-api/), for a page or a script. ```ts import { applyLine, createClient, type Turn } from "@fxbot/sdk/client"; const client = createClient({ baseUrl: "http://127.0.0.1:8787" }); let turns: Turn[] = []; for await (const line of client.stream(botId, { signal })) turns = applyLine(turns, line); ``` It imports nothing from `@fxbot/sdk`’s main entry, so a browser bundle can take it. See [Build a page on the client](/sdk/how-to/web-page/). ## createClient [Section titled “createClient”](#createclient) `createClient(options?)` returns a `Client`. | Option | Type | Default | What it does | | ----------- | --------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------- | | `baseUrl` | `string` | `""`, the page’s own origin | The server’s origin, such as `http://127.0.0.1:8787`. A script needs it. | | `onVersion` | `(version: string) => void` | None | Hears the version in each answer’s `x-fxbot-version` header, so a page can notice a new release | * Each call asks `/api/...` with `fetch`, sends JSON, and resolves to the JSON answer. * A call that fails throws an `Error` with the server’s message. When the server can’t be reached, or answers with something that isn’t JSON, such as a proxy’s page, the message is `unreachable`: “Cannot reach the server.” The `Error` carries no status. * The client holds no keys or tokens. A key goes to the server once, in `providers.add` or `providers.update`, and comes back only as `hasKey`. Header values and OAuth clients go up once, in `plugins.setSecrets`. * The server refuses a write with 403 when the request’s `Origin` header names another host than its `Host`. A browser sends `Origin`, so a page on another origin gets 403 for every write. Node’s `fetch` sends no `Origin`, so a script’s writes pass. The server sends no CORS headers. ## Calls [Section titled “Calls”](#calls) Each call is one route of the [HTTP API](/sdk/reference/http-api/). They mirror [the fxbot object](/sdk/reference/server-api/), which has the rules for each. ### Health and updates [Section titled “Health and updates”](#health-and-updates) | Call | Route | Returns | | ---------------- | ------------------ | ----------------------- | | `health()` | `GET /api/health` | `{ ok: true, version }` | | `update.get()` | `GET /api/update` | `UpdateStatus` | | `update.start()` | `POST /api/update` | `UpdateStatus` | ### Bots [Section titled “Bots”](#bots) | Call | Route | Returns | | ---------------------------------------------- | --------------------------------------------------- | ------------------------------------ | | `profiles.list()` | `GET /api/profiles` | `Profile[]` | | `profiles.get(id)` | `GET /api/profiles/` | `Profile` | | `profiles.create(fields)` | `POST /api/profiles` | `Profile` | | `profiles.stop(id)` | `POST /api/profiles//stop` | `{ ok: true }` | | `profiles.update(id, fields)` | `PATCH /api/profiles/` | `Profile` | | `profiles.order(ids)` | `PUT /api/profiles/order` | `Profile[]` | | `profiles.remove(id)` | `DELETE /api/profiles/` | `{ ok: true }` | | `profiles.earlier(id)` | `GET /api/profiles//earlier` | `Turn[]` | | `profiles.skills(id)` | `GET /api/profiles//skills` | `BotSkill[]` | | `profiles.memories.list(id, query?)` | `GET /api/profiles//memories?query=` | `Memory[]` | | `profiles.memories.add(id, text)` | `POST /api/profiles//memories` | `Memory` | | `profiles.memories.update(id, memoryId, text)` | `PATCH /api/profiles//memories/` | `Memory` | | `profiles.memories.remove(id, memoryId)` | `DELETE /api/profiles//memories/` | `{ ok: true }` | | `profiles.memories.share(id, memoryId)` | `POST /api/profiles//memories//share` | `Memory`. Since 0.10.0 | | `memories.list(query?)` | `GET /api/memories?query=` | `Memory[]`: the team’s. Since 0.10.0 | | `memories.add(text)` | `POST /api/memories` | `Memory`. Since 0.10.0 | | `memories.update(memoryId, text)` | `PATCH /api/memories/` | `Memory`. Since 0.10.0 | | `memories.remove(memoryId)` | `DELETE /api/memories/` | `{ ok: true }`. Since 0.10.0 | `profiles.memories.list` and `memories.list` take the search as a string. An empty one lists the newest. ### Chat [Section titled “Chat”](#chat) | Call | Route | Returns | | ---------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `send(id, message)` | `POST /api/profiles//messages` | `{ messageId, sessionId }`, and `joined`, the running turn’s `messageId`, when the message joined it | | `stream(id, options?)` | `GET /api/profiles//stream?cursor=` | An async generator of `StreamLine` | `send` resolves once the server has stored the message. The reply arrives on the stream. ### Settings [Section titled “Settings”](#settings) | Call | Route | Returns | | ------------------------- | ----------------------------- | ----------------- | | `settings.get()` | `GET /api/settings` | `Settings` | | `settings.update(fields)` | `PATCH /api/settings` | `Settings` | | `settings.embedding()` | `GET /api/settings/embedding` | `EmbeddingStatus` | `settings.update` also takes `local`: `cpu`, `gpu`, or `off`. It asks the machine to run its local embedder that way, in an install made by `setup.sh`. ### Providers and sign-ins [Section titled “Providers and sign-ins”](#providers-and-sign-ins) | Call | Route | Returns | | -------------------------------------- | -------------------------------- | --------------- | | `providers.list()` | `GET /api/providers` | `Provider[]` | | `providers.add(provider)` | `POST /api/providers` | `Provider` | | `providers.update(id, fields)` | `PATCH /api/providers/` | `Provider` | | `providers.remove(id)` | `DELETE /api/providers/` | `{ ok: true }` | | `providers.models(id)` | `GET /api/providers//models` | `Model[]` | | `providers.teams(id)` | `GET /api/providers//teams` | `Team[]` | | `providers.catalog()` | `GET /api/providers/catalog` | `Catalog` | | `providers.local()` | `GET /api/providers/local` | `LocalServer[]` | | `signIns.start(kind, provider?, way?)` | `POST /api/sign-ins` | `SignIn` | | `signIns.get(id)` | `GET /api/sign-ins/` | `SignInStatus` | | `signIns.code(id, code)` | `POST /api/sign-ins//code` | `SignInStatus` | | `signIns.cancel(id)` | `DELETE /api/sign-ins/` | `{ ok: true }` | A sign-in: for a `device` one, show `userCode` and `verificationUrl`; for `redirect`, open `url`, which comes back to the page’s own address; for `paste`, open `url`, and send the code it shows with `signIns.code`. Then call `signIns.get` until the status is `done` or `failed`. `way: "paste"` asks OpenRouter for a code even where it could come back. ### Library [Section titled “Library”](#library) | Call | Route | Returns | | ---------------------------------------------------------- | --------------------------------------------------- | -------------- | | `library.list({ q?, profileId?, kind?, before?, limit? })` | `GET /api/library?q=&profile=&kind=&before=&limit=` | `LibraryPage` | | `library.get(id)` | `GET /api/library/` | `LibraryItem` | | `library.remove(id)` | `DELETE /api/library/` | `{ ok: true }` | A file itself is read through its item’s `url`, `/api/library//file`. ### Plugins and OAuth [Section titled “Plugins and OAuth”](#plugins-and-oauth) | Call | Route | Returns | | ---------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------- | | `plugins.list()` | `GET /api/plugins` | `Plugin[]` | | `plugins.search(q, { kind?, everything? })` | `GET /api/plugins/search?q=&kind=&everything=1` | `McpSearch` | | `plugins.searchSkills(q)` | `GET /api/plugins/search?q=&kind=skill` | `SkillSearch` | | `plugins.preview(ref)` | `POST /api/plugins/preview` | `SkillPreview` for a skill ref, `PackagePreview` for a repo ref, else `McpPreview` | | `plugins.add(ref, hash)` | `POST /api/plugins` | `Plugin` | | `plugins.update(id, hash)` | `POST /api/plugins//update` | `Plugin` | | `plugins.change(id, fields)` | `PATCH /api/plugins/` | `Plugin` | | `plugins.remove(id)` | `DELETE /api/plugins/` | `{ ok: true }` | | `plugins.setSecrets(id, secrets)` | `PUT /api/plugins//secrets` | `Plugin` | | `plugins.forBot(profileId, pluginId, enabled)` | `PUT /api/profiles//plugins/` | `Plugin` | | `plugins.readSkill(id, file?)` | `GET /api/plugins//skills?file=` | `string` | | `plugins.signIn(id)` | `POST /api/plugins//sign-in` | `OAuthAttempt` | | `plugins.searchPackages(q)` | `GET /api/plugins/search?q=&kind=package` | `PackageSearch` | | `plugins.configure(id, settings)` | `PUT /api/plugins//settings` | `PackagePlugin` | | `plugins.log(id)` | `GET /api/plugins//log` | `string[]` | | `plugins.contents(id)` | `GET /api/plugins//contents` | `PackagePreview` | | `plugins.pages()` | `GET /api/plugins/pages` | `PluginPage[]` | | `oauth.get(attemptId)` | `GET /api/oauth/attempts/` | `OAuthStatus` | | `oauth.paste(attemptId, address)` | `POST /api/oauth/attempts//paste` | `OAuthStatus` | After `plugins.signIn`, open the attempt’s `url`, then call `oauth.get` until the status is `done` or `failed`. The browser’s `Origin` decides where the sign-in comes back to. ## stream [Section titled “stream”](#stream) ```ts stream(id: string, options?: { cursor?: number; session?: string; signal?: AbortSignal; onConnection?: (connected: boolean) => void; onCaughtUp?: () => void }): AsyncGenerator ``` | Option | Default | What it does | | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `cursor` | `0` | Where to start. 0 replays the whole chat. | | `session` | None | The session `cursor` is in. When the chat has moved from it since, the stream is the `moved` line alone. Since 0.5.0. | | `signal` | None | Stops the stream. The generator then returns. | | `onConnection` | None | Hears `true` on each connection, and `false` when one drops | | `onCaughtUp` | None | Hears each connection catch up: every line the chat had when it opened has been yielded, so the lines before were the replay | * It yields every line of the bot’s chat from `cursor` on, then each new line, until `signal` aborts. * It keeps the `cursor` of the last line it read. When the connection drops, the server answers with an error, or the stream ends, it waits 2 seconds and asks again from that cursor. The server ends the stream at once for a bot with no chat yet, so the client asks again every 2 seconds until the chat starts. * It hides a line whose `epoch` is lower than one it has already seen, as libfx’s rule says. * A `moved` line, when the chat starts over, is the last it yields: a cursor of the old session means nothing in the new one. Read the bot again, and stream its new `sessionId` from 0. * Each connection’s `x-fxbot-version` header goes to `onVersion`. Its `x-fxbot-end` header, the chat’s newest cursor, says when to call `onCaughtUp`. A server without it is caught up at once. * A page can hold the replay’s lines and show them together at `onCaughtUp`, so a chat opens at its end instead of scrolling past each turn as it arrives. fxbot’s own page does. ## applyLine [Section titled “applyLine”](#applyline) `applyLine(turns, line)` folds one stream line into a list of turns, one per message, and returns a new list. It doesn’t change the list it was given. | Line | What it changes | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | A line without `messageId`, such as `idle` | Nothing | | `turn_start`, `turn_resume` | Moves the turn to the end of the list and starts it again: an empty `reply` and `parts`, `done: false`, and no `note` or `unsent`. `text` comes from the line’s `input` when it is a string, and `files` from the line’s `files`. A turn that runs again after a crash sends its reply again from the start. | | `text_delta` | Adds `delta` to `reply`, and to the last part when it is text, or else to a new text part. Separate text parts are joined in `reply` with a blank line. | | `reasoning_delta` | Adds `delta` to the last part when it is reasoning, or else to a new reasoning part | | `tool_start` | Adds a tool part with its `id`, `name`, and `input`, or `inputPreview` for a large input | | `user_message` | Adds a `user` part to the running turn, `{ type: "user", id, text, files?, from? }`, and drops the turn the page made for that message. | | `tool_end` | Ends the tool part of the same `id`, with `output` from `content` and `error` from `isError`. A tool that started before the replay’s cursor is added here. | | `turn_end` | Sets `done`. `note` is `Error: ` for an error, or `Stopped: ` when the reason isn’t `end_turn`. A tool still running is marked done. | | Any other type | Nothing | A line for a message not in the list adds a turn for it. ## Types [Section titled “Types”](#types) ```ts type Turn = { messageId: string; text: string; // the message files?: Upload[]; reply: string; // the reply's text alone parts?: Part[]; // the reply step by step, in order done: boolean; note?: string; // an error, or why it stopped unsent?: boolean; // for a page: a message the server never took }; type Part = | { type: "reasoning"; text: string } | { type: "text"; text: string } | { type: "tool"; id: string; name: string; input?: unknown; inputPreview?: string; output?: string; error?: boolean; done: boolean }; ``` A turn from `profiles.earlier` has `reply` and no `parts`. ## Stream lines [Section titled “Stream lines”](#stream-lines) `StreamLine` is one line of a bot’s NDJSON stream, as far as fxbot reads it. libfx writes more types and fields. | Field | Type | What it is | | -------------- | --------------------- | ------------------------------------------------------------------ | | `type` | `string` | The line’s type | | `messageId` | `string` | The turn it belongs to | | `input` | `unknown` | The message on `turn_start`, or a tool’s arguments on `tool_start` | | `text` | `string` | A message’s words, on `user_message` | | `files` | `Upload[]` | A message’s files, on `turn_start` | | `delta` | `string` | New text, on `text_delta` and `reasoning_delta` | | `id` | `string` | A tool call’s id, which pairs `tool_start` with `tool_end` | | `name` | `string` | A tool’s name | | `inputPreview` | `string` | A preview of a tool’s input, in place of a large `input` | | `content` | `string` | A tool’s result, on `tool_end` | | `isError` | `boolean` | Whether the tool failed, on `tool_end` | | `stopReason` | `string` | Why the turn ended, on `turn_end`, such as `end_turn` | | `error` | `{ message: string }` | Why the turn failed, on `turn_end` | | `cursor` | `number` | Where to start again to get the lines after this one | | `epoch` | `number` | The lease epoch of the line’s writer | | `sessionId` | `string` | On `moved`: the session the chat started over in | The types `applyLine` reads: | Type | When | | ----------------- | --------------------------------------------- | | `turn_start` | A turn starts | | `turn_resume` | A turn a stopped process left open runs again | | `text_delta` | More of the reply’s text | | `reasoning_delta` | More of the model’s reasoning | | `tool_start` | A tool call starts | | `tool_end` | A tool call ends | | `turn_end` | A turn ends | libfx writes other types too, such as `turn_yield` and `idle`. `applyLine` passes over them, and over `moved`, fxbot’s own last line of a chat that started over, by a provider switch or a plugin’s `startOver`, with the new `sessionId`. Since 0.5.0. ## Exports [Section titled “Exports”](#exports) | Export | What it is | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createClient` | Makes a client | | `applyLine` | Folds a stream line into a list of turns | | `unreachable` | `"Cannot reach the server."`, the message of a call that got no answer | | `colors`, `shapes`, `moods`, `heads`, `faces`, `outfits`, `tints`, `kinds`, `itemKinds`, `embeddingKinds`, `maxPinned`, `effortLadder`, `effortKinds`, `effortFor` | The same tables and function as `@fxbot/sdk`’s. See [Exports](/sdk/reference/server-api/#exports). | | `pluginIcon(key)` | A plugin’s icon from its `iconKey`: `path`, a closed curve in a 100 by 100 box; `turn`, in degrees; and `light` and `dark`, each four colors: the tile’s two stops, then the shape’s two. The tile is a rounded square, `rx` 24, with a gradient turned by `turn`, and the shape’s gradient is turned 90 degrees more. Since 0.5.0. | | `iconSeed(key)` | The 32-bit number a key seeds its icon with. | The types are `Client`, `ClientOptions`, `StreamOptions`, `Turn`, `Part`, `PluginIcon`, and `Tones`, and the shared types that `@fxbot/sdk` exports too, such as `Profile`, `Provider`, `Settings`, and `StreamLine`. # createFxbot > createFxbot(options), from @fxbot/sdk, opens fxbot's database, brings it up to date, and resolves to the fxbot object. `createFxbot(options)`, from `@fxbot/sdk`, opens fxbot’s database, brings it up to date, and resolves to [the fxbot object](/sdk/reference/server-api/). ```ts import { readFileSync } from "node:fs"; import { createFxbot } from "@fxbot/sdk"; const fxbot = await createFxbot({ databaseUrl: "postgres://fxbot:@127.0.0.1:5432/fxbot", secretKey: readFileSync("/path/to/secret.key", "utf8"), }); ``` To add the SDK to a project, see [Use the SDK in a project](/sdk/how-to/set-up/). ## Requirements [Section titled “Requirements”](#requirements) | Needs | Why | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Node 22.18 or newer | The package ships TypeScript source, which Node runs without a build. | | Postgres with the pgvector extension available | Every record lives in Postgres. Migration `0005_memories` creates the `vector` extension when the database lacks it. It stops with a message when the server has no pgvector, or when the extension is missing and fxbot’s database role is not a superuser. | | A key of 32 random bytes, in base64 | It seals every stored key and token. `openssl rand -base64 32` makes one. | | `pg_dump` and `tar` on the `PATH` | For the backup before migrations, when the database already holds fxbot’s records. | ## Options [Section titled “Options”](#options) `FxbotOptions`. Only `databaseUrl` and `secretKey` are required. | Option | Type | Default | What it does | | ------------------- | -------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `databaseUrl` | `string` | | fxbot’s Postgres. Every record lives there. Keys and tokens are stored only sealed. | | `secretKey` | `Buffer` or `string` | | The 32 bytes that seal keys and tokens: a `Buffer`, or the base64 text of the key file. A key of another length throws. | | `vercelClientId` | `string` | The list’s | fxbot’s Vercel OAuth app, for signing in with a Vercel account, in place of the one fxbot’s list of providers names. With neither, a Vercel sign-in fails with 400. | | `hfClientId` | `string` | The list’s | fxbot’s Hugging Face OAuth app, a public one with no secret, in place of the one fxbot’s list of providers names. With neither, a Hugging Face sign-in fails with 400. | | `dataDir` | `string` | `data` | Plugins’ files, under `plugins/`. Chats from before 0.4.0, under `sessions/`, move into the database on the first start, which renames the folder `sessions.moved`. A relative path is taken from the working directory. | | `backupsDir` | `string` | `backups` | Where a backup goes before migrations change a database in use. | | `version` | `string` | `0.0.0` | The running version, for `release()`. | | `releasesUrl` | `string` | None | Where the newest stable release is read, in the shape of GitHub’s `releases/latest`. It is read at start and once a day. Without it, nothing is asked. | | `fetch` | `typeof fetch` | `globalThis.fetch` | The `fetch` for fxbot’s own requests: sign-ins, model lists, key checks, MCP servers, the registries, skills, embeddings, and the release check. Turns use libfx’s own `fetch`, except on a Vercel account, OpenCode, and a provider whose entry adds headers, such as OpenRouter, Anthropic, and Azure. | | `localUrl` | `string` | `http://127.0.0.1:8787` | The server’s own origin on this machine. An MCP sign-in with a loopback redirect comes back to `/callback`. | | `clientMetadataUrl` | `string` | None | The project’s published OAuth client ID metadata document, for MCP servers that sign in with one. Without it, fxbot registers itself with each server that allows it. | | `registryUrl` | `string` | `https://api.mcp.github.com` | The MCP registry that registry entries come from. It is mirrored into Postgres for search. | | `everythingUrl` | `string` | `https://registry.modelcontextprotocol.io` | The official MCP registry. It is asked only when a search asks for everything. | | `listsUrl` | `string` | `https://fxbot.sh` | The site that publishes fxbot’s own lists, `/mcp-registry.json`, `/skills-registry.json`, and `/plugins-registry.json`, its list of providers, `/providers-registry.json`, and what each release broke, `/plugin-breaks.json`. They are read hourly. Until a read succeeds, fxbot uses the lists this release shipped with. | | `syncRegistry` | `boolean` | `true` | `false` skips the registry sync at start. In 0.3.0, the hourly sync still runs. | | `embedUrl` | `string` | None | The machine’s local embedder, an OpenAI-style API such as `http://embed:8080/v1`, for memory search. Trailing slashes are dropped. Without it, there is no local embedder. | | `pluginDirs` | `string[]` | None | Plugin folders, for writing a plugin. Each is added on first sight, loaded at start, and loaded again a moment after its files change. See [Plugin API](/sdk/reference/plugin-api/#where-plugins-come-from). | | `machine` | `PluginMachine` | None | The machine’s `fxbot` command, for a job only root can do. Plugins get it as `fx.machine`, which is `null` without it. See [Plugin API](/sdk/reference/plugin-api/#server-code). | ### How fxbot’s server sets them [Section titled “How fxbot’s server sets them”](#how-fxbots-server-sets-them) | Option | From | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `databaseUrl` | `FXBOT_DATABASE_URL` | | `secretKey` | The file named by `FXBOT_SECRET_KEY_FILE` | | `vercelClientId` | `FXBOT_VERCEL_CLIENT_ID` | | `hfClientId` | `FXBOT_HF_CLIENT_ID` | | `dataDir` | `FXBOT_DATA` | | `backupsDir` | `FXBOT_BACKUPS` | | `version` | `version` in the root `package.json` | | `releasesUrl` | `FXBOT_RELEASES_URL`, or GitHub’s `releases/latest` for the repository in the root `package.json`. None when `FXBOT_UPDATE_CHECK` is `off`. | | `localUrl` | `http://127.0.0.1:` | | `clientMetadataUrl` | `FXBOT_CLIENT_METADATA_URL` | | `registryUrl` | `FXBOT_MCP_REGISTRY` | | `everythingUrl` | `FXBOT_MCP_EVERYTHING` | | `listsUrl` | `FXBOT_LISTS_URL` | | `embedUrl` | `FXBOT_EMBED_URL` | | `pluginDirs` | `FXBOT_PLUGIN_DIRS`, folders separated as `PATH` is | | `machine` | The request folder that an install made by `setup.sh` shares with the machine. None in a checkout. | The server leaves `fetch` and `syncRegistry` at their defaults. The variables are in [Configuration](/docs/reference/configuration/). ## What it does when called [Section titled “What it does when called”](#what-it-does-when-called) In order: 1. Reads `secretKey`. 2. Connects to Postgres and runs the migrations it hasn’t run. See [Migrations](#migrations). If they fail, it closes the connection and throws. 3. Starts the release check, when `releasesUrl` is set: at once, then once a day. 4. Starts the registry sync, unless `syncRegistry` is `false`: fxbot’s two lists and the mirror of `registryUrl`. It runs again every hour. 5. Loads the MCP servers and skills in Plugins. The skills’ repositories are checked for changes a minute after start, then hourly. 6. Starts one libfx agent per provider, each with every bot tool. A provider whose agent doesn’t start, such as one whose secret doesn’t open, lists with an `error`. The others run. 7. Starts filling in the vectors that memories and messages lack, in the background. 8. Connects the MCP servers, in the background. 9. Resumes the turns a stopped process left open, for each bot with a chat whose provider runs. Each reply is saved as usual. ## Migrations [Section titled “Migrations”](#migrations) * The schema is the numbered SQL files in `packages/sdk/src/migrations/`. 0.3.0 has `0001_baseline` to `0005_memories`. * Each file runs once, in order of its name, and is recorded in the table `fxbot_migrations`. * All pending files run in one transaction. If one fails, none of them is kept, and the error names it. * The transaction holds an advisory lock, so two processes that start at once take turns. * When the database already holds fxbot’s records, a backup is made before anything changes. It goes into `/