Skip to content

Plugin API

Copy all docs

What a plugin with code is made of, and every call it can make: its server code’s fx, and its page code’s app and @fxbot/app. fxbot calls such a plugin, a folder with plugin.json, a package. A guide to writing one: Write a plugin.

my-plugin/
├── plugin.json
├── fxbot/
│ ├── server.ts server code: plain JavaScript, or TypeScript that Node runs as it is
│ ├── page.js page code: one CommonJS bundle
│ ├── page.css optional
│ └── migrations/ optional: its tables
├── skills/<name>/SKILL.md optional: skills, as Agent Skills lays them out
└── mcp.json optional: MCP servers

Only plugin.json is required, and only the paths it names count.

Field What it is
name Required. Up to 40 lowercase letters, digits, and dashes. Its tools are <name>_<tool>, its routes are under /api/plugins/<name>/, its page paths under /<name>/, and its schema is plugin_<name>, with _ for -. It can’t be chat, memory, library, or skill, or an MCP server’s prefix, nor a name fxbot uses itself: preview, search, addons, plugins, settings, profiles, or 12 hex characters, which is a plugin’s id. It and the repository’s owner make the plugin’s icon.
version Shown on its row. Default 0.0.0
description Shown whole on its page. Its rows in Plugins show its first sentence, up to 100 characters and two lines, so write one sentence that fits.
extensions["sh.fxbot"].minFxbot The oldest fxbot it runs on, as x.y.z. See Which fxbot it runs on. Since 0.7.0.
extensions["sh.fxbot"].server Its server code, a path inside the folder
extensions["sh.fxbot"].page Its page code
extensions["sh.fxbot"].css Its CSS
extensions["sh.fxbot"].migrations A folder of .sql files
extensions["sh.fxbot"].settings A list of settings, each with name, description, and optionally default, isRequired, and isSecret
extensions["sh.fxbot"].commands Commands for the / list in a bot’s message box, each with name (up to 40 lowercase letters, digits, and dashes) and description (up to 200 characters). Listing one runs nothing: the plugin’s message hook sees /name as text. Since 0.5.0.
extensions["sh.fxbot"].needs The plugins it needs, each name mapped to an object for that plugin, up to 16 KiB in all. See Plugins that need others.

minFxbot is the oldest fxbot a plugin runs on. The rows on this page say Since 0.6.0 where a call is newer than the rest, so set it to the newest of those that the plugin uses. It’s a version and not a range: nothing says the newest fxbot a plugin runs on, since nobody can know that ahead of time.

A plugin with code on a fxbot older than its minFxbot can’t be added, or updated to. On a start, it doesn’t run, and says what it needs. fxbot before 0.7.0 doesn’t read minFxbot, so a plugin that wants to refuse those can check for a call it needs, and throw.

What a release breaks is in fxbot’s plugin-breaks.json, which installs read every hour:

{
"breaks": [
{ "since": "0.8.0", "uses": ["fx.models.ask"], "says": "Use fx.models.run." },
{ "since": "0.9.0", "says": "Hooks changed shape, so every plugin needs a new version." },
{ "plugin": "computer", "below": "0.4.0", "says": "It can lose a bot's files on this version." }
]
}
A line It fits a plugin when
since and uses Its minFxbot is below since, and its server or page code names one of uses, as a whole word
since alone Its minFxbot is below since
plugin and below It’s that plugin, at a version below below

A line applies on a fxbot at since or later. A plugin it fits is Unsupported there: it doesn’t run, its files, settings, and tables stay, and it can’t be added. To say a plugin has moved on from a break, raise its minFxbot to since. A plugin that needs one that’s Unsupported gets null from fx.need, as it does for any plugin that isn’t running.

The check reads names in code, so it can miss a call reached another way, and a name in a comment counts. A plugin from FXBOT_PLUGIN_DIRS runs whatever the check says, with a line in its log, since its author is at the keyboard.

The server module’s default export is called once when the plugin loads, with fx. It may be async, and may return a cleanup function, which runs when the plugin is turned off, updated, or removed, and when fxbot stops.

import type { PluginApi } from "@fxbot/sdk";
export default async function setup(fx: PluginApi) {
const timer = setInterval(() => fx.log("still here"), 60_000);
return () => clearInterval(timer);
}
Member What it is
fx.name The plugin’s name
fx.on(event, handler) A hook. See Hooks.
fx.tool(tool) A tool for bots. See Tools.
fx.route(method, path, handler) A route. See Routes.
fx.socket(path, handler) A WebSocket. See Sockets.
fx.sql A postgres client in the plugin’s own schema, with two connections at most
fx.settings Its settings, with defaults, and secrets opened. The same object, kept up to date.
fx.secrets.get(name), fx.secrets.set(name, value) Values the plugin makes itself, such as keys of its own, sealed beside its settings and never shown in them. get answers null for a name it never set, and set with null removes one. A name is up to 64 letters, digits, ., _, or -, and a value up to 64 KiB of text. Since 0.8.0.
fx.bots.list(), fx.bots.get(id) The bots, as the fxbot object lists them
fx.bots.on(id) Whether this plugin is on for the bot. Since 0.6.0.
fx.localUrl The server’s own address on its machine, such as http://127.0.0.1:8787, for requests to fxbot’s own API. Since 0.8.0.
fx.timeZone() The owner’s time zone, such as Europe/Berlin: Settings › General’s, or the machine’s. Read it at each use. Since 0.6.0.
fx.compaction() Idle compaction’s setting, from Settings › General: { idleMinutes, provider, model }. idleMinutes is how long a chat sits idle before it’s compacted, 0 when it’s off, and provider and model the model that writes a summary, or "" for each bot’s own. Chat rooms compacts its rooms by it. Read it at each use. Since 0.10.0.
fx.chats Sessions and turns of its own. See Turns.
fx.dependents() The added plugins that need this one: { name, version, needs, api } each, where needs is its object for this plugin, and api what it provides, or null while it isn’t running
fx.provide(api) Offers an object to the plugins that need this one, which get it with fx.need. Since 0.5.0. See Plugins that need others.
fx.need(name) What a plugin this one names under needs provides, or null while it isn’t running. It throws for a plugin needs doesn’t name. Since 0.5.0.
fx.library.read(bot, id) A library item’s name, type, and bytes, if it’s tagged for the bot; otherwise it throws
fx.library.save({ bot, session, name, type, bytes }) Saves an image, UTF-8 text, or since 0.10.0 a PDF, whose text fxbot reads, to the bot’s library, tagged for the chat, through the library’s checks. It answers the item.
fx.library.replace({ bot, session, id, name, type, bytes }) Changes a document a bot made, in place: its id and tags stay, the chat gets a tag, and it comes to the top of the library. It refuses an image, an upload, an item not tagged for the bot, one another bot holds too, since one item serves every bot that saved the same text, and text another item holds. When the owner sends a bot’s document in a chat, it becomes an upload. It answers the item. Since 0.7.0.
fx.library.list(bot, session) The items saved in one chat of the bot, newest first. Since 0.6.0.
fx.skills.files(bot, name) The files besides SKILL.md of the skill the bot sees by that name, as { path, text }. None when it has no such skill.
fx.skills.set(bot, skills) The skills the plugin gives one bot, in place of those it gave before, each { name, description, instructions }, as a SKILL.md’s name, description, and body. They join the bot’s catalog, its skill tool, and its / list while the plugin is on for it, and go when the plugin unloads, so a plugin keeps them and sets them again in its setup. It throws with status 400 for a bad name, a description over 1,024 characters, a name twice, or instructions over 64 KiB. Since 0.5.0.
fx.memories.get(bot, id) One of the bot’s memories, with savedBy, bot or owner, or null when the bot has none by that id. Since 0.5.0. fx.memories reaches only a bot’s own memories, never the team’s.
fx.memories.save(bot, { text, replaces? }) Saves a memory as the bot’s, as memory_save does, or with replaces, changes that one’s text. It answers { memory, existed, merged }: existed when the same text was saved already, and merged when the changed memory now said what another did, and went into that one. It throws with status 400 for text over 1,000 characters, and 404 for a replaces the bot doesn’t have. Since 0.5.0.
fx.models.ask(bot, { instructions, text, provider?, model?, timeoutMs? }) One tool-free request, on the bot’s provider and model unless provider and model name others. It answers the text, and throws on a failure or after timeoutMs, 60 seconds by default. Keys stay on the server. Since 0.6.0.
fx.memories.remove(bot, id) Deletes one of the bot’s memories. A missing one throws with status 404. Since 0.5.0.
fx.machine In an install made by setup.sh, the machine’s fxbot command, for a job only root can do; null in a checkout. ask("computer") asks it to set up the computer plugin’s engine, and status("computer") says how that went: { state, error? }, with state asked, working, done, or failed, or null when nothing asked. computer is its only job.
fx.log(...parts) A line in its log, which its tab in Settings shows
fx.signal An AbortSignal that aborts when the plugin unloads

Setup gets 10 seconds. A setup that throws or runs late leaves the plugin added but off, with its error on its row. fxbot starts either way. Turns can start only after fxbot has: not from setup itself.

Handlers run in the order the plugins were added, and change the event’s fields in place, so each sees what the last one changed. A plugin’s hooks reach only the bots it’s on for.

Event When Fields Can
message Before a message runs, after the chat is known bot, session, text, files, from, asked Change text and files; answer { handled: true }, and no turn runs; or answer { startOver: { ask } }, and the message goes to a new chat
instructions Each time a chat opens bot, session, instructions, a list Add, change, or remove entries
tool.before Before every tool call: fxbot’s, MCP servers’, skills’, and plugins’ bot, session, and since 0.9.0 label, the session’s from newSession, or null, messageId, the message whose turn it’s in, since 0.6.0, and since 0.6.0, callId, which holds across a restart, tool, description, input, and safe, the tool’s own word that it only reads or writes the bot’s own notes Change input, answer { block: reason }, which the model gets as a failed call, or since 0.6.0 answer { wait }: a function core calls after every hook, with { input }, the final one, and no time limit but the call’s own. It answers { block: reason }, or nothing, and the call runs. Since 0.7.0, the bot’s waiting is true while a wait holds one of its calls
tool.after After it the same, with result, or error when it failed Change result
turn.start Once libfx stores the prompt, or since 0.6.0, in a bot’s own chat, when the turn it waited behind ends bot, session, messageId, text, from, asked Observe
turn.end When the turn ends the same, with reply, error when it failed, as when the provider answered with an error, and cancelled when it was stopped, since 0.6.0 Observe
library.removed An item left the library, for every bot. It reaches every running plugin, whichever bots it’s on for. Since 0.7.0. id Observe
settings The owner changed its settings settings Observe
dependents A plugin that needs this one was added, updated, or removed dependents, as fx.dependents() gives them Observe
  • message, instructions, tool.before, and tool.after handlers get 5 seconds each. One that throws or runs late is logged and skipped, except tool.before, where it blocks the call.
  • turn.start and turn.end run beside the turn, and never hold it up.
  • from is the plugin that sent the message, when one did.
  • asked, since 0.7.0, is the owner’s words a plugin’s message carried on, as send was given them, when it had any. The plugin that sent them vouches they’re the owner’s.
  • A message that joins a running turn runs the message hook as ever, and has no turn.start or turn.end of its own: those are the running turn’s. See Turns.
  • A message that a message hook handled answers send with { messageId, sessionId, handled: true }.
  • { startOver: { ask } }, since 0.5.0, starts the bot’s own chat over before the message runs: the bot’s model summarizes the chat, answering ask, up to 16 KiB of text, and the bot starts a new chat from that summary, as a provider switch does. The message then goes to the new chat as the owner’s. It applies only to the bot’s own chat, only to a chat with messages, and only once for a message: a retry of one that went through doesn’t start over again. The other plugins’ hooks still run, and the first startOver counts. A message left with no text and no files answers handled: true. A summary that fails fails the send, with 502, and nothing moves. fxbot’s own /fresh takes the same path since 0.10.0, before the hooks run, and a hook’s startOver then doesn’t count.
fx.tool({
name: "greet",
description: "Greet someone by name",
inputSchema: { type: "object", properties: { name: { type: "string" } } },
idempotent: true,
execute: async (input, { bot, session, signal }) => `Hello, ${input.name}!`,
});
Field What it is
name Lowercase letters, digits, and _. Bots see <plugin>_<name>, up to 64 characters.
description What the model reads
inputSchema A JSON Schema object for the input
idempotent Whether running a call twice is harmless, so a call cut off by a crash runs again
safe Optional: it only reads, or writes the bot’s own notes, and reaches nothing outside. A hook sees this on tool.before. Since 0.6.0.
execute(input, call) Runs one call. call has the bot and session of the chat, the session’s label from newSession, or null in the bot’s own chat, since 0.9.0, the messageId of the message whose turn it’s in, since 0.6.0, and a signal that aborts with the turn. A string goes to the model as it is, and anything else as JSON, but for { type: "libfx.tool-result", text, images }, whose images, up to 8, the model sees.

Adding a tool makes fxbot’s agents again. A call from a bot the plugin isn’t on for fails, and so does a result over 64 KiB.

fx.route("GET", "/rooms/:id", async (request, { id }) => Response.json({ id }));
  • A route answers /api/plugins/<name>/<path>, with a web Request and Response. :name parts come in params.
  • A Response with a stream for its body streams to the caller. The request’s signal aborts when the caller goes.
  • fxbot’s server checks first: a write from another site’s page gets 403, and a body over 12 MiB 413.
  • A handler that throws answers 500, { "error": "<message>" }, and the error goes in the log.
  • /api/plugins/<name>/files/ serves its page code and CSS, and no route there is reached.
fx.socket("/desktop/:bot", (socket, request, { bot }) => {
socket.onmessage = (data) => socket.send(data);
socket.onclose = () => {};
});
  • A socket is a WebSocket at /api/plugins/<name>/<path>, for a two-way stream that a route’s request and response can’t carry. The page opens one with ws: or wss:, matching its own address.
  • socket has send(data), close(code?, reason?), bufferedAmount, and two handlers to set: onmessage, which gets a binary message as a Buffer and text as a string, and onclose.
  • fxbot’s server checks first: a socket opened from another site’s page gets 403, since a WebSocket opens with a GET, which the write check doesn’t cover. A path no socket has gets 404.
  • A handler that throws closes its socket with code 1011, and the error goes in the log. Turning the plugin off, removing it, or stopping fxbot closes its open sockets.
  • Adding the plugin makes the schema plugin_<name>, then runs each file in its migrations folder, in name order, each in a transaction. The names run are kept in the schema’s _migrations.
  • An update runs only the files that are new. Never change a file that has shipped.
  • fx.sql reaches the schema’s tables by name, without the schema.
  • Removing the plugin drops the schema.
  • The owner sets them on the plugin’s tab in Settings. Each is text, up to 8 KiB. Clearing one brings back its default.
  • They’re sealed together in Postgres. A secret one is never shown again, and its row says only that it’s set.
  • fx.settings has them. fx.on("settings", …) hears a change.

A plugin’s turns run as the owner’s do, with the same hooks, history, library, and busy.

Call What it does
fx.chats.newSession(bot, { label?, effort? }) A session of the plugin’s own for the bot, on the bot’s provider now. Keep its id. label, since 0.9.0, names it, up to 80 characters, such as a subagent’s name: each of its tool calls gets it, so a plugin such as the computer can tell the bot’s sessions apart. effort, since 0.10.0, is the thinking level its turns ask for, such as high, in place of the bot’s: the model’s nearest lower level when it doesn’t offer that one.
fx.chats.send(bot, { text, shown?, label?, steer?, files?, session?, messageId?, asked? }) A message. shown, since 0.6.0, is what the chat shows of it, when that isn’t text, which the model gets. Without session, it goes to the bot’s own chat, which shows it as “From ”. With one, it stays out of the bot’s chat, its earlier chats, and its preview, and chat_history still finds it. messageId defaults to a new UUID. asked, since 0.7.0, is the owner’s own words the message carries on, up to 8,000 characters, which the plugin quotes from a chat of theirs, such as what they asked the bot it’s from. Hooks get it with the message and its turn.
fx.chats.stream(bot, session, cursor?) That session’s lines, as NDJSON, from cursor on, then each new one. The same lines as fxbot.stream.
fx.chats.ownerSaid(bot, limit) The owner’s newest messages in the bot’s own chat, oldest first, with no plugin’s or other bot’s. Since 0.6.0.
fx.chats.cancel(bot, session?) Stops the turn running in one of the plugin’s own sessions, if one runs. It ends cancelled, and the session’s stream says so. Since 0.4.1. With no session, since 0.6.0, it stops the turn running in the bot’s own chat, if this plugin started it. Any other turn there throws with status 409, and with nothing running it does nothing.

In a bot’s own chat, since 0.6.0, and in a session of the plugin’s own, since 0.9.0, send also takes these, and its answer has joined:

Field What it does
label Who the chat says the message is from, in place of the plugin’s name. Hooks still get the plugin in from.
steer true lets the message join a turn that’s running, instead of waiting behind it, when that turn takes messages: the owner’s turns, and plugin turns sent with steer. The turn this message starts takes messages the same way. A message with an image never joins, since that would end the running turn. Since 0.9.0, it works the same in a session of the plugin’s own: a turn there sent with steer takes the plugin’s later messages sent with steer.
joined In the answer: the messageId of the turn the message joined, when it did. Its text reaches that turn, and the turn’s hooks stay that turn’s. A message that came just too late runs as a turn of its own, under its own messageId, with turn.start and turn.end.

A session belongs to the provider it started on. After the bot moves to another provider, send and stream for it fail with status 409: make a new one.

A plugin names the plugins it needs, and what it asks of each, under needs:

"needs": { "computer": { "setup": ["apt-get update && apt-get install -y --no-install-recommends chromium"] } }
  • Its page says what it needs. Adding it is refused until those are added, and they can’t be removed while it is.
  • It loads after the plugins it needs.
  • "optional": true in a need’s object, since 0.10.0, makes it a plugin it works with: it loads and runs without it, Add doesn’t wait for it, and it can be removed. fx.need answers null while it isn’t running. Its page lists it under Works with. An older fxbot reads it as needed, so a plugin that uses it sets minFxbot to 0.10.0. The computer marks chat rooms so, for a room’s computer.
  • What each object holds is up to the plugin it names, which reads them with fx.dependents() and hears a change with the dependents event.
  • A plugin with no code, only needs and skills, is a plugin too.

Since 0.5.0, plugins call each other through objects they provide. A plugin offers one with fx.provide, and a plugin that needs it gets it with fx.need. The plugin needed reads its dependents’ objects as api in fx.dependents():

// rooms: what other plugins may ask it.
fx.provide({ roomOf: async (session: string) => rooms.get(session) ?? null });
// room-notes, with "needs": { "rooms": {} }: asks rooms, at each use.
fx.route("GET", "/notes/:session", async (_request, { session }) => {
const room = await fx.need<{ roomOf(session: string): Promise<{ id: number } | null> }>("rooms")?.roomOf(session);
return Response.json({ room });
});
  • Read it at each use. An update or a reload of the plugin replaces its object, and one turned off, failed, or unloading provides null.
  • It’s the provider’s own object, not a copy: its functions run the provider’s code, with no time limit, and their errors reach the caller.
  • On the page, a plugin leaves a place with Slot, from @fxbot/app, and another fills it with app.slot. Name a place for the plugin that leaves it, such as chat-rooms.room-header.

The computer and chat rooms provide objects of their own: see the computer’s and chat rooms’ README.

page is one CommonJS bundle that leaves react, react/jsx-runtime, and @fxbot/app out. The page runs it with a require that gives those three, its own copies, and nothing else. Its default export is called with app, which has the plugin’s name and version, and these:

Call Where it shows
app.route(path, Component) The screen at /<plugin><path>. path may have :name parts, which Component gets as params.
app.sidebar(Component) A group in the sidebar, after the bots
app.nav({ label, path, icon? }) A button in the sidebar’s footer row, to /<plugin><path>. icon is a component; without one, the button shows the plugin’s icon.
app.chat(Component) Above the message box in a bot’s chat. It gets bot, and reload(), which reads the bot again, so the chat follows a session the plugin started, such as with fx.chats.send to a bot that had no chat. Since 0.6.0; reload since 0.10.0.
app.botPanel(Component) Above the tabs of a bot’s panel, beside its chat. It gets bot.
app.libraryItem(Component) Beside Download in an item’s preview, from the library or a bot’s panel. It gets item. Since 0.7.0.
app.composer(Component) A control beside the attach button. It gets bot, setDraft(text), and attach(files). setDraft also takes a function from the draft to the new text.
app.box(Component) Replaces the textarea in a bot’s chat, for the first plugin that sets one. It gets bot and a textarea’s props, and acts as one: value is the text, onChange gets { target: { value, selectionStart } }, and its ref has selectionStart and setSelectionRange. One that throws falls back to the textarea. Since 0.6.0.
app.fold({ message, tool }) Folds messages in a bot’s chat into a pill, which counts what was received and sent, shows each bot’s face, and opens to show them. message(id) gets a message’s id, and answers { fold, bot }, or nothing: fold is "turn" to fold it with the turn it starts, or "message" to fold it alone, and bot is the id of who it’s from. tool(call) gets a tool call, and answers { bot, name } when it sent a message, or nothing, and its card goes in a pill. A run of them makes one pill, until something that doesn’t fold. A turn the owner wrote into stays in view. Since 0.6.0.
app.codeBlock(language, Component) Draws each fenced code block of language, such as ```mermaid, wherever the app shows Markdown: a bot’s replies, Markdown pages, rooms, and the library’s preview. Component gets code, language, meta (what follows the language on the fence), and incomplete, true while the block is still streaming in: in a bot’s reply as it arrives, and in ui.Streamdown when the plugin passes it isAnimating. The first plugin to claim a language draws it, and one that throws leaves the plain code. Since 0.9.0.
app.said(pattern, Component) Draws each match of pattern, a global regex, in what the owner or a plugin said in a bot’s chat. Component gets match. Since 0.6.0.
app.toolView(tool, Component, { open? }) How a call of <plugin>_<tool> shows in a reply. With open, since 0.6.0, it stays in sight below the folded steps, for what the owner shouldn’t miss. It gets call: name, input, output, error, and done.
app.settings(Component) A part of the plugin’s tab in Settings, at /settings/plugins/<plugin>, above its bots and settings. Every plugin has that tab, and several calls stack in it. Before 0.6.0, only a plugin that called this had a tab, and before 0.5.0, it was a section of Settings’ one page.
app.botSettings(Component) A section in a bot’s settings. It gets bot.
app.slot(name, Component) A part in a place another plugin’s page leaves with Slot, which gets that Slot’s props. Several stack in order. Since 0.5.0.

Each part sits in its own error boundary: one that throws shows a short card in its place, and the rest of the app goes on. A plugin’s page parts are for everyone, whichever bots it’s on for. The page reads the list of plugins again after a change in Plugins, and keeps code it already ran until it reloads.

@fxbot/app:

Export What it is
api(path, init?) fetch for the plugin’s own routes
client The app’s client, as The client describes
applyLine Folds a stream line into turns
go(path) Opens a path in the app
useBots() The app’s list of bots, or null while it loads
createPortal(children, node) React’s, from react-dom, for drawing a component into DOM the plugin doesn’t render with React, such as an editor’s node. Since 0.4.1.
Slot <Slot name="<plugin>.<place>" props={…} /> leaves a place other plugins fill with app.slot, each part in its own error boundary. One nobody fills draws nothing. Since 0.5.0.
ui The app’s components: Button, Input, Textarea, Badge, Switch, Checkbox, the Dialog, Empty, Sidebar (with useSidebar), Attachment, Message, Bubble, and MessageScroller parts, Streamdown for Markdown, with the code blocks plugins draw since 0.9.0, Header for a screen’s top bar, Blob for a bot’s look, given a whole bot, as in <ui.Blob {...bot} size={24} />, NativeSelect, ModelField for the app’s model picker, since 0.6.0, Reply for a turn’s reply, and since 0.7.0, useReorder(onMove, axis?), the app’s drag to reorder a list, by mouse or finger: the list’s element takes its list ref, each item item(id)’s props, with data-lifted on the one held, onMove gets the ids in their new order, dragging is true while an item is held, and cancel() ends a drag, as when the item’s menu opens

The page’s styles hold only the classes the app uses. A plugin brings its own CSS for anything else.

Source How
GitHub Plugins, on Browse, under From GitHub, with unvetted plugins on: owner/repo, or owner/repo/folder. Its page pins the repository’s newest commit, and shows its code. Add writes its files to FXBOT_DATA/plugins/<name>/<commit>/.
fxbot’s list plugins-registry.json on fxbot’s site, read hourly, tagged fxbot
A folder FXBOT_PLUGIN_DIRS, in a checkout. Added on first sight, loaded at start, and loaded again a moment after its files change
  • From GitHub, files are text only, up to 2 MiB each and 20 MB in all.
  • The hourly check marks Update available when a plugin’s files change in its repository. Update moves it to the commit its page showed, and keeps the old version running when the new one doesn’t load.
  • Its skills join the catalog of the bots it’s on for. Each remote server in its mcp.json is added with it, under the usual rules for addresses: a record of its own, which shows in the package’s settings, follows the package’s switch and bots, and is removed with it. A server that runs a command isn’t used yet.
  • In a release, fxbot runs in its container, and a plugin reaches what the container does.

Plugins load inside createFxbot, so an app built on the SDK runs them as fxbot does, with some parts left to the app:

  • Server code runs as it is: hooks, tools, tables, settings, turns, skills, and MCP servers. fxbot.plugins adds, updates, and removes plugins, and pluginDirs loads folders.
  • Routes and sockets need your server. Pass requests under /api/plugins/<name>/ to fxbot.plugins.handle(name, request, path), its page code and CSS under files/ to fxbot.plugins.file, and WebSocket upgrades there to fxbot.plugins.socket, as fxbot’s server does (packages/server/src/index.ts). A plugin’s page calls that path.
  • Page code needs fxbot’s page. fxbot.plugins.pages() lists each plugin’s bundle, but what runs one, the app places and @fxbot/app, is part of fxbot’s own app (packages/ui/src/plugins.tsx), not @fxbot/sdk/client. An app with a page of its own shows none of a plugin’s screens, panels, or buttons, unless it gives the bundle that require and app itself.
  • fx.machine is null unless you pass machine. The computer plugin then sets up its engine by itself only when the app runs as root, and otherwise shows the command to run.