Plugin System

FastCMS is AI-native — but it doesn't bundle AI into the core wheel. Instead, RAG, vector search, autonomous agents, and other extensions ship as plugins you install on demand. The roadmap doubles down on this: future versions go deeper on agent orchestration and retrieval, all shipped as opt-in plugins, never bloating the install.

This means: pick the AI capabilities you need, skip the ones you don't, keep your wheel small. Same model for anything you'd build yourself.

Installing a pre-built plugin

# inside any FastCMS project directory
fastcms plugin install ai-core
fastcms plugin install ai-vectors
fastcms plugin install ai-rag
fastcms plugin install ai-agents

The CLI fetches the plugin from the fastcms-plugins repository, resolves dependencies, and places it in your project's plugins/ directory.

Restart FastCMS (Ctrl+C, then fastcms dev again) — plugins load once at startup. List installed plugins:

fastcms plugin list

The official plugin registry currently includes:

Dependencies are installed automatically (ai-rag pulls in ai-vectors and ai-core for you).

How the plugin system works

Plugins are plain Python packages dropped into the plugins/ directory. On startup, FastCMS discovers them automatically and calls their register() function — giving each plugin a PluginContext to hook into the system. Inspired by PocketBase's extension model.

What Plugins Can Do

Design Principles

1. Zero core modification — plugins never touch app/ files
2. Drop-in discovery — copy a folder, restart, done
3. Isolated namespace — routes under /api/v1/plugins/{prefix}/
4. Graceful failure — a broken plugin logs an error and is skipped; the server starts normally
5. Settings in DB — plugin config lives in the plugin_settings table, editable via Admin UI

Plugin Directory Structure

The minimal plugin is a single file. A full-featured plugin looks like:

plugins/
└── my_plugin/
    ├── __init__.py     # REQUIRED: PLUGIN_META dict + register(ctx) function
    ├── routes.py       # Optional: FastAPI APIRouter
    ├── models.py       # Optional: SQLAlchemy models (inherit from Base)
    ├── hooks.py        # Optional: async event handlers
    └── templates/      # Optional: Jinja2 templates for admin pages

Minimal Plugin

# plugins/hello_world/__init__.py
PLUGIN_META = {
    "id": "hello-world",
    "name": "Hello World",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "A minimal example plugin",
}

def register(ctx) -> None:
    from fastapi import APIRouter
    router = APIRouter()

    @router.get("/hello")
    async def hello():
        return {"message": "Hello from Hello World plugin!"}

    ctx.include_router(router, prefix="/hello-world")

Restart FastCMS and call:

curl http://localhost:8000/api/v1/plugins/hello-world/hello
# → {"message": "Hello from Hello World plugin!"}

Plugin Lifecycle

1. Startup — FastCMS calls load_plugins("./plugins", app, plugin_settings)
2. Discovery — scans plugins/ for sub-directories with __init__.py
3. Validation — checks PLUGIN_META has id, name, version
4. Context creation — builds PluginContext(plugin_id, app, settings)
5. Registration — calls register(ctx) — routes/hooks/pages registered here
6. Running — plugin routes are live, hooks fire on events
7. Admin listing — plugin appears at /admin/plugins

Admin UI

Loaded plugins are listed at /admin/plugins with name, version, author, and a settings link.

Plugins can also add their own pages to the sidebar:

ctx.add_admin_page(
    nav_id="hello-world",
    label="Hello World",
    icon="fa-star",
    url="/admin/plugins/hello-world",
)

Plugin Settings

Plugin settings are stored in the plugin_settings database table (key/value per plugin).

Read a setting at startup:

def register(ctx) -> None:
    api_key = ctx.get_setting("api_key", default="")

Update settings via API:

PATCH /api/v1/admin/plugins/hello-world/settings
Authorization: Bearer ADMIN_TOKEN
{"api_key": "sk-..."}

Example Plugin

A complete reference implementation lives at plugins/example_plugin/. It demonstrates routes, event hooks, and admin page registration. Copy it as your starting point:

cp -r plugins/example_plugin plugins/my_plugin
# Edit plugins/my_plugin/__init__.py

Security

Plugins run inside the FastCMS process with full Python access. Only install plugins from sources you trust.

• Never expose raw SQL through plugin routes — use SQLAlchemy ORM
• Always check authentication via require_auth or require_admin dependencies
• Review third-party plugins before installing

Troubleshooting

Build your first plugin →