ExtendRoom 13 of 13
Extend the core. Without forking it.
Sophon Plugins are out-of-process dotnet programs speaking gRPC to the Gateway, adding new channel types and document formats that behave exactly like built-ins. Installed locally, enabled explicitly, managed for you.
Since Sophon 1.15
A recreation of Settings, Plugins in the Sophon Dashboard. The plugin system starts off. An admin switches it on through a confirm dialog and allowlists acme-chat-adapter. The Gateway spawns the plugin as its own dotnet process, initializes it over gRPC, and shows it running with zero restarts and a health check every 30 seconds.
04 / 04 · Running, health-checked every 30s
Recreation of Settings › Plugins in the Dashboard.
AWatch a plugin crash and restart
The Gateway runs your plugin so you don't babysit it.
The Gateway spawns acme-chat-adapter as its own dotnet process on a free port.
Step 1 of 5: The Gateway spawns it
01 / 05 · The Gateway spawns it
Each plugin is a long-lived local process. The Gateway launches
dotnet <plugin>.dll --port {port}on a free port and talks to it over gRPC on localhost.
BMechanism
Two interfaces, live today.
ChannelAdapterBuild your own messaging channelBridge Sophon to a proprietary in-house chat system, an internal ticketing tool, or a niche protocol, and it behaves exactly like a built-in channel.
- Appears in the Dashboard add-channel wizard alongside WhatsApp, Telegram, and Slack
- Full integration with sessions, message routing, and approval flows
- Inbound attachments and outbound delivery work like any native channel
- Connection settings render in the Dashboard; secrets are vault-backed
DocumentExtractorAdd your own file formatsAdd extraction for formats Sophon doesn't read natively (EPUB, RTF, CAD), and they flow through the same document pipeline as PDFs.
- Register the file extensions you handle; a dynamic registry routes them to your plugin
- Extracted content is chunked, embedded, and searchable like every other document
- Citable in grounded Q&A: your formats show up with citations, not just search hits
- Built-in formats always take precedence, so a plugin can never break native extraction
CHow it works
From an empty project to a running extension.
- 01 Implement an interface
- A plain dotnet console app that implements
ChannelAdapterorDocumentExtractor: a C# (.NET 10) project that subclassesPluginBasefrom the Sophon Plugin SDK. No forking Sophon, no rebuilding the Gateway; your plugin is its own project with its own dependencies. - 02 Describe it in manifest.json
- Declare the plugin's name, which interface it implements, and a settings schema. Settings marked as secrets are vault-backed, configured in the Dashboard, never stored in plain text.
- 03 Pack and install
- sophon dev build packages your project as a .sophon-plugin archive, and sophon dev install copies the project into the data directory. Or skip the CLI entirely and install a published plugin from the Sophon Marketplace.
- 04 Enable and allowlist
- Nothing runs until an admin enables plugins and allowlists the plugin by name. Start, stop, and configure it hot from Dashboard Settings › Plugins, with no Gateway restart.
One manifest, two CLI commands, one Dashboard toggle. Here's the manifest for a channel adapter, end to end.
{
"name": "acme-chat-adapter",
"version": "1.0.0",
"description": "Channel adapter for the Acme in-house chat system",
"author": "Your Name",
"type": "plugin",
"pluginInterface": "ChannelAdapter",
"entrypoint": "AcmeChatAdapter.dll",
"channelType": "acme-chat",
"recipientMetadataKey": "channel",
"settings": [
{
"name": "serverUrl",
"displayName": "Server URL",
"type": "string",
"required": true
},
{
"name": "apiToken",
"displayName": "API Token",
"type": "secret",
"required": true
}
]
}$ sophon dev build ./acme-chat-adapter
→ acme-chat-adapter.sophon-plugin
$ sophon dev install ./acme-chat-adapter
# Then enable it in Dashboard → Settings → PluginsDFull trust, explicit consent
Treated like software you install, not content you browse.
- Off by default
- An admin opts in at Settings › Plugins, where a confirm dialog guards the switch, or in config. The Dashboard toggle applies live; the environment-variable form needs a restart.
- Allowlisted by name
Sophon:Plugins:Allowlists the plugins that may load, case-insensitive. Left empty, every discovered plugin may load.- Admin-only
- Installing, starting, and stopping a plugin are admin actions. Settings › Plugins lists every discovered plugin with its state, restart count, and any registration errors.
- Gated installs
- An install the agent starts through marketplace.install is always gated behind your approval and is treated as Critical for plugins. A new Marketplace version stays invisible until a moderator approves it.
- Discovery you trigger
- The Gateway scans
<dataDir>/plugins/first, then<dataDir>/skills/installed/for Marketplace installs, on startup and on demand. There is no filesystem watcher: rescan with the Scan button orPOST /api/plugins/scan.
EWhat's coming
Three more interfaces, already in the manifest format.
ModelProvider- Bring your own inference: plug a custom or self-hosted model endpoint into Sophon as a first-class provider. For an OpenAI-compatible endpoint, use the built-in custom provider today.
EmbeddingProvider- Supply your own embedding backend for memory and document search.
VaultBackend- Store Sophon's secrets in your own vault infrastructure instead of the built-in store. Deferred: plugin settings are vault-hydrated, so the vault must exist before plugins are scanned. Use the built-in vault backends today.
Tool- Refused, intentionally: a Tool manifest is refused at parse time and the plugin never starts. Custom tools already have two first-class homes: skills for sandboxed, Marketplace-distributable capabilities, and MCP for external tool servers. Plugins are reserved for extending the core.
Distribute through the Marketplace
The Marketplace carries skills, plugins and, since 2.2, agent packages. Agent packages share personas and setup; plugins remain full-trust processes that extend the Gateway.
Publish your plugin to the Sophon Marketplace and anyone can install it from their Dashboard, with the same packaging and the same review flow as skills.
Limits
What plugins aren't.
Plugins are not sandboxed. No container, no code signing, no resource limits, unrestricted network: a plugin can do anything the Gateway's OS user can do. Install them from sources you trust, the way you would vet any binary you put on your server.
Security modelA crashing plugin cannot take down the Gateway, but that is a stability property, not a security boundary.
Security modelThe allowlist filters by the name a manifest claims. It doesn't verify authorship or file integrity.
Enabling pluginsNever put a real secret in a setting's default. Defaults are visible to any authenticated user through the listing endpoints.
The manifestModelProvider, EmbeddingProvider and VaultBackend manifests are accepted and the process runs and passes health checks, but the runtime doesn't use them yet. The Gateway logs a one-time warning so an inert plugin isn't mistaken for a bug.
What plugins can extend