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.
The folder
Section titled “The folder”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 serversOnly plugin.json is required, and only the paths it names count.
plugin.json
Section titled “plugin.json”| 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. |
Which fxbot it runs on
Section titled “Which fxbot it runs on”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.
Server code
Section titled “Server code”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, andtool.afterhandlers get 5 seconds each. One that throws or runs late is logged and skipped, excepttool.before, where it blocks the call.turn.startandturn.endrun beside the turn, and never hold it up.fromis 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, assendwas 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
messagehook as ever, and has noturn.startorturn.endof its own: those are the running turn’s. See Turns. - A message that a
messagehook handled answerssendwith{ 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, answeringask, 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 firststartOvercounts. A message left with no text and no files answershandled: true. A summary that fails fails the send, with 502, and nothing moves. fxbot’s own/freshtakes the same path since 0.10.0, before the hooks run, and a hook’sstartOverthen 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.
Routes
Section titled “Routes”fx.route("GET", "/rooms/:id", async (request, { id }) => Response.json({ id }));- A route answers
/api/plugins/<name>/<path>, with a webRequestandResponse.:nameparts come inparams. - A
Responsewith a stream for its body streams to the caller. The request’ssignalaborts 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.
Sockets
Section titled “Sockets”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 withws:orwss:, matching its own address. sockethassend(data),close(code?, reason?),bufferedAmount, and two handlers to set:onmessage, which gets a binary message as aBufferand text as a string, andonclose.- 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.sqlreaches the schema’s tables by name, without the schema.- Removing the plugin drops the schema.
Settings
Section titled “Settings”- 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.settingshas 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 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.
Plugins that need others
Section titled “Plugins that need others”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": truein 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.needanswers 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 setsminFxbotto 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 thedependentsevent. - A plugin with no code, only
needsand 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 withapp.slot. Name a place for the plugin that leaves it, such aschat-rooms.room-header.
The computer and chat rooms provide objects of their own: see the computer’s and chat rooms’ README.
Page code
Section titled “Page code”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.
Where plugins come from
Section titled “Where plugins come from”| 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.jsonis 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.
In your own app
Section titled “In your own app”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.pluginsadds, updates, and removes plugins, andpluginDirsloads folders. - Routes and sockets need your server. Pass requests under
/api/plugins/<name>/tofxbot.plugins.handle(name, request, path), its page code and CSS underfiles/tofxbot.plugins.file, and WebSocket upgrades there tofxbot.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, theappplaces 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 thatrequireandappitself. fx.machineisnullunless you passmachine. The computer plugin then sets up its engine by itself only when the app runs as root, and otherwise shows the command to run.