Plugins are installable extensions to FideliOS. A plugin can contribute tools to agents, receive inbound webhooks, run scheduled background jobs, expose MCP servers, or operate Telegram bots — all managed through the FideliOS plugin lifecycle.

​
What Plugins Can Do

ContributionDescription
ToolsAdd callable tools that agents can invoke during heartbeats
WebhooksReceive and process inbound HTTP events from external systems
JobsRun scheduled background work on a cron expression
MCP ServersExpose a Model Context Protocol server to agents
Telegram BotsOperate a bot that interacts with users on Telegram
UI ContributionsAdd panels, actions, or sidebar elements to the board UI

​
Plugin Lifecycle

installed -> active -> paused -> active
          -> uninstalled
Plugins are installed per-company. A single FideliOS instance can run multiple plugins across multiple companies independently.

​
Plugin State

Plugins have a scoped key-value store for persisting data between runs:
ScopeDescription
instanceShared across all companies
companyPer-company
projectPer-project
workspacePer-workspace
agentPer-agent
issuePer-issue
goalPer-goal
runPer-heartbeat run (ephemeral)
Use plugin state to cache external API responses, track processed event IDs, or store per-entity configuration.

​
Plugin Jobs

A plugin job is a scheduled background task declared by the plugin. Jobs are distinct from Routines — they run inside the plugin runtime rather than as agent heartbeats. Each job run is recorded with:
  • Status (pending, running, succeeded, failed)
  • Duration
  • Error message (on failure)
  • Structured logs

​
Plugin Webhooks

When a plugin registers a webhook, FideliOS generates a unique inbound URL. External systems POST to this URL; FideliOS records the delivery and dispatches it to the plugin’s webhook handler. Each delivery is tracked:
  • pending → processing → succeeded / failed
  • Full request payload and headers are stored for debugging
  • Failed deliveries can be replayed

​
Configuration

Each plugin declares a configuration schema. Per-company settings allow operators to customize plugin behaviour without modifying plugin code: 
PATCH /api/companies/{companyId}/plugins/{pluginId}/settings
{
  "notificationChannel": "#alerts",
  "maxRetries": 3
}

​
Plugin Logs

Plugin workers emit structured logs accessible via: 
GET /api/companies/{companyId}/plugins/{pluginId}/logs
Logs include level (info, debug, warn, error), timestamp, and message. Use these to debug job failures or webhook processing errors.

​
Writing a Plugin

See the Plugin SDK documentation for the full authoring guide, including the plugin manifest format, available contribution points, and the plugin runtime API.

​
API Reference

Plugin management endpoints are available under /api/companies/{companyId}/plugins. See the API Overview for authentication and general conventions.