aitbc/docs/apps/plugins/plugin-service.md

Plugin Service

Level: Intermediate
Prerequisites: Familiarity with AITBC plugin architecture
Estimated Time: 10 minutes
Last Updated: 2026-05-03
Version: 1.0

🧭 Navigation Path:

🏠 Documentation Home → 📦 Apps → 🔌 Plugins → You are here

breadcrumb: Home → Apps → Plugins → Plugin Service

---

🎯 See Also:

• 📖 About Documentation - Template standard and audit checklist
• 🧭 Master Index - Full documentation catalog
• 🔌 Plugins Overview - Plugin system overview

---

Overview

The Plugin Service provides the infrastructure for managing and executing plugins in the AITBC ecosystem. It handles plugin registration, lifecycle management, and provides a secure execution environment for third-party extensions.

Features

• Plugin Registry: Central registry for all plugins
• Lifecycle Management: Install, enable, disable, and remove plugins
• Sandboxed Execution: Secure plugin execution environment
• Dependency Management: Automatic dependency resolution
• Version Control: Support for multiple plugin versions
• API Gateway: Plugin API endpoints for external integration

Architecture

The Plugin Service consists of:

• Registry: Stores plugin metadata and configurations
• Loader: Dynamically loads plugin code
• Executor: Runs plugin code in sandboxed environment
• API Server: Exposes plugin endpoints
• Dependency Manager: Handles plugin dependencies
• Version Manager: Manages plugin versions

Installation

cd /opt/aitbc
poetry install --with plugin-service

Configuration

Configuration is managed through environment variables:

# Plugin Storage
PLUGIN_STORAGE_PATH=/var/lib/aitbc/plugins

# Registry
PLUGIN_REGISTRY_URL=http://localhost:9002

# Security
PLUGIN_SANDBOX_ENABLED=true
PLUGIN_SIGNATURE_VERIFICATION=true

# API
PLUGIN_API_PORT=9003

Running

Development

cd apps/plugin-service
python -m plugin_service.main

Production (systemd)

sudo systemctl start plugin-service
sudo systemctl enable plugin-service

Endpoints

• GET /health - Health check
• GET /plugins - List all plugins
• POST /plugins/install - Install plugin from repository
• POST /plugins/{plugin_id}/enable - Enable plugin
• POST /plugins/{plugin_id}/disable - Disable plugin
• DELETE /plugins/{plugin_id} - Remove plugin
• GET /plugins/{plugin_id}/info - Get plugin information
• GET /plugins/{plugin_id}/versions - List plugin versions

Plugin Development

Plugin Structure

my-plugin/
├── plugin.yaml          # Plugin metadata
├── src/
│   ├── __init__.py
│   └── main.py          # Plugin entry point
├── requirements.txt     # Plugin dependencies
└── tests/              # Plugin tests

plugin.yaml Example

name: my-plugin
version: 1.0.0
description: My custom plugin
author: Your Name
license: MIT
entry_point: src.main:main
dependencies:
  - aitbc-core>=1.0.0
permissions:
  - blockchain:read
  - marketplace:read

Installing a Plugin

# From local directory
curl -X POST http://localhost:9003/plugins/install \
  -F "plugin=@/path/to/plugin.tar.gz"

# From repository
curl -X POST http://localhost:9003/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"repository": "https://repo.example.com/my-plugin", "version": "1.0.0"}'

Managing Plugins

# Enable plugin
curl -X POST http://localhost:9003/plugins/my-plugin/enable

# Disable plugin
curl -X POST http://localhost:9003/plugins/my-plugin/disable

# Remove plugin
curl -X DELETE http://localhost:9003/plugins/my-plugin

# Get plugin info
curl http://localhost:9003/plugins/my-plugin/info

Security

• Sandboxed Execution: Plugins run in isolated environment
• Signature Verification: Plugin signatures verified before installation
• Permission System: Granular permission controls
• Dependency Isolation: Plugin dependencies isolated from core system
• Resource Limits: CPU and memory limits for plugin execution

Built-in Plugins

• Plugin Analytics: Analytics and metrics collection
• Plugin Marketplace: Plugin marketplace integration
• Plugin Registry: Plugin registry management
• Plugin Security: Security scanning and validation

Troubleshooting

Plugin Installation Fails

1. Verify plugin signature is valid
2. Check plugin dependencies are available
3. Review plugin logs for specific errors

Plugin Won't Enable

1. Check plugin permissions are granted
2. Verify plugin dependencies are satisfied
3. Review plugin configuration

Plugin Execution Errors

1. Check resource limits are not exceeded
2. Verify plugin code is compatible with current version
3. Review sandbox logs for errors

Monitoring

Health Check

curl http://localhost:9003/health

Plugin Status

curl http://localhost:9003/plugins

Plugin Logs

journalctl -u plugin-service -f

Related Documentation

• Plugin Analytics
• Plugin Marketplace
• Plugin Registry
• Plugin Security

---

Last updated: 2026-05-03
Version: 1.0
Status: Active service
Tags: plugins, extensions, service, management