elizaOS Registry

Intro

elizaOS supports dynamic plugin loading directly from the package registry.

Available Plugins

All official plugins are hosted at github.com/elizaos-plugins. Currently available plugins include:

• @elizaos/plugin-solana - Solana blockchain integration
• @elizaos/plugin-discord - Discord bot integration
• @elizaos/plugin-twitter - Twitter bot integration
• @elizaos/plugin-whatsapp - WhatsApp integration
• @elizaos/plugin-browser - Web scraping capabilities
• @elizaos/plugin-pdf - PDF processing
• @elizaos/plugin-image - Image processing and analysis
• @elizaos/plugin-video - Video processing capabilities
• @elizaos/plugin-local-ai - Local LLaMA model integration

Visit the our Registry Hub

Adding Plugins on eliza

1. package.json:

{
  "dependencies": {
    "@elizaos/plugin-solana": "github:elizaos-plugins/plugin-solana",
    "@elizaos/plugin-twitter": "github:elizaos-plugins/plugin-twitter"
  }
}

2. Character configuration:

{
  "name": "MyAgent",
  "plugins": ["@elizaos/plugin-solana", "@elizaos/plugin-twitter"]
}

Plugin Architecture

Plugin Development

elizaOS uses a unified plugin architecture where everything is a plugin - including clients, adapters, actions, evaluators, and services. This approach ensures consistent behavior and better extensibility. Here's how the architecture works:

1. Plugin Types: Each plugin can provide one or more of the following:

   • Clients (e.g., Discord, Twitter, WhatsApp integrations)
   • Adapters (e.g., database adapters, caching systems)
   • Bootstrap (e.g., how the bot responds to events)
   • Model Providers (e.g., OpenAI-compatible, local-ai, ollama, etc)

2. Plugin Interface: All plugins implement the core Plugin interface: 1.x (https://github.com/elizaOS/plugin-specification/blob/f800a4340e95123838c594528fa26ddff7ec9ecd/core-plugin-v2/src/types.ts#L569)

   type Plugin = {
     name: string;
     description: string;
     init?: (
       config: Record<string, string>,
       runtime: IAgentRuntime
     ) => Promise<void>;
     config?: { [key: string]: any };
     services?: Service[];
     componentTypes?: {
       name: string;
       schema: Record<string, unknown>;
       validator?: (data: any) => boolean;
     }[];
     actions?: Action[];
     providers?: Provider[];
     evaluators?: Evaluator[];
     adapter?: IDatabaseAdapter;
     models?: {
       [key: string]: (...args: any[]) => Promise<any>;
     };
     events?: {
       [K in keyof EventPayloadMap]?: EventHandler<K>[];
     } & {
       [key: string]: ((params: EventPayload) => Promise<any>)[];
     };
     routes?: Route[];
     tests?: TestSuite[];
   };

   0.x (https://github.com/elizaOS/plugin-specification/blob/f800a4340e95123838c594528fa26ddff7ec9ecd/core-plugin-v1/src/types.ts#L664)

   type Plugin = {
     name: string;
     description: string;
     config?: { [key: string]: any };
     actions?: Action[];
     providers?: Provider[];
     evaluators?: Evaluator[];
     services?: Service[];
     clients?: Client[];
     adapters?: Adapter[];
   };

3. Independent Repositories: Each plugin lives in its own repository, allowing:

   • Independent versioning and releases
   • Focused issue tracking and documentation
   • Easier maintenance and contribution
   • Separate CI/CD pipelines

4. Plugin Structure: Each plugin repository should follow this structure:

   plugin-name/
   ├── images/
   │   ├── logo.jpg        # Plugin branding logo
   │   ├── banner.jpg      # Plugin banner image
   ├── src/
   │   ├── index.ts        # Main plugin entry point
   │   ├── actions/        # Plugin-specific actions
   │   ├── clients/        # Client implementations
   │   ├── adapters/       # Adapter implementations
   │   └── types.ts        # Type definitions
   │   └── environment.ts  # runtime.getSetting, zod validation
   ├── package.json        # Plugin dependencies
   └── README.md          # Plugin documentation
   

5. Package Configuration: Your plugin's package.json must include an agentConfig section:

   {
     "name": "@elizaos/plugin-example",
     "version": "1.0.0",
     "agentConfig": {
       "pluginType": "elizaos:plugin:1.0.0",
       "pluginParameters": {
         "API_KEY": {
           "type": "string",
           "description": "API key for the service"
         }
       }
     }
   }

6. Plugin Loading: Plugins are dynamically loaded at runtime through the handlePluginImporting function, which:

   • Imports the plugin module
   • Reads the plugin configuration
   • Validates plugin parameters
   • Registers the plugin's components (clients, adapters, actions, etc.)

7. Client and Adapter Implementation: When implementing clients or adapters:

0.x

// Client example
const discordPlugin: Plugin = {
  name: "discord",
  description: "Discord client plugin",
  clients: [DiscordClientInterface],
};

// Adapter example
const postgresPlugin: Plugin = {
  name: "postgres",
  description: "PostgreSQL database adapter",
  adapters: [PostgresDatabaseAdapter],
};

// Adapter example
export const browserPlugin = {
  name: "default",
  description: "Pdf",
  services: [PdfService],
  actions: [],
};

Environment Variables and Secrets

Plugins can access environment variables and secrets in two ways:

1. Character Configuration: Through agent.json.secret or character settings:

   {
     "name": "MyAgent",
     "settings": {
       "secrets": {
         "PLUGIN_API_KEY": "your-api-key",
         "PLUGIN_SECRET": "your-secret"
       }
     }
   }

2. Runtime Access: Plugins can access their configuration through the runtime:

   class MyPlugin implements Plugin {
     async initialize(runtime: AgentRuntime) {
       const apiKey = runtime.getSetting("PLUGIN_API_KEY");
       const secret = runtime.getSetting("PLUGIN_SECRET");
     }
   }

The getSetting method follows this precedence:

1. Character settings secrets
2. Character settings
3. Global settings

Plugin Registration

1. Add it to your agent's character configuration:

   {
     "name": "MyAgent",
     "plugins": ["@elizaos/plugin-example"]
   }

2. Include it in your package.json:

   {
     "dependencies": {
       "@elizaos/plugin-example": "github:elizaos-plugins/plugin-example"
     }
   }

Creating a New Plugin

1. Use any of the already mentioned list plugins, such as web-search as a starting point
2. Implement the Plugin interface:

   interface Plugin {
     actions?: Action[];
     evaluators?: Evaluator[];
     services?: Service[];
     providers?: Provider[];
     initialize?(runtime: AgentRuntime): Promise<void>;
   }

3. Create a plugin.json file with metadata and configuration schema
4. Document your plugin's functionality and required environment variables

Plugin Development Guidelines

1. Minimal Dependencies: Only include necessary dependencies
2. Clear Documentation: Document all required environment variables
3. Error Handling: Gracefully handle missing or invalid configuration
4. Type Safety: Use TypeScript for better developer experience
5. Testing: Include tests for core functionality
6. GitHub Topics: Add elizaos-plugins as a topic to your repository along with relevant tags like ai, crypto, social, etc. to help with discovery and categorization

Pull Request Requirements

When submitting a plugin to the elizaOS Registry, your PR must include:

1. Working Demo Evidence:

   • Screenshots or video demonstrations of the plugin working with elizaOS
   • Test results showing successful integration
   • Example agent configuration using your plugin
   • Documentation of any specific setup requirements

2. Integration Testing:

   • Proof of successful dynamic loading with elizaOS
   • Test cases covering main functionality
   • Error handling demonstrations
   • Performance metrics (if applicable)

3. Configuration Examples:

   {
     "name": "MyAgent",
     "plugins": ["@elizaos/your-plugin"],
     "settings": {
       "your-plugin": {
         // Your plugin's configuration
       }
     }
   }

4. Quality Checklist:

   • Plugin follows the standard structure
   • All required branding assets are included
   • Documentation is complete and clear
   • GitHub topics are properly set
   • Tests are passing
   • Demo evidence is provided

Visit the [elizaOS Plugin Development Guide](https://github.com/elizaos-plugins/plugin-image for detailed information on creating new plugins.

Plugin Branding and Images

To maintain a consistent and professional appearance across the elizaOS ecosystem, we recommend including the following assets in your plugin repository:

1. Required Images:

   • logo.png (400x400px) - Your plugin's square logo
   • banner.png (1280x640px) - A banner image for your plugin
   • screenshot.png - At least one screenshot demonstrating your plugin's functionality

2. Image Location:

   plugin-name/
   ├── assets/
   │   ├── logo.png
   │   ├── banner.png
   │   └── screenshots/
   │       ├── screenshot1.png
   │       └── screenshot2.png
   

3. Image Guidelines:

   • Use clear, high-resolution images
   • Keep file sizes optimized (< 500KB for logos, < 1MB for banners)
   • Image example
   • Include alt text for accessibility

Automated Registry Generation

This repository includes an automated system that generates a processed generated-registry.json file whenever the index.json file is updated on the main branch.

How it works:

1. Source Data: The index.json file contains the raw registry mappings from plugin names to GitHub repositories
2. GitHub Action: When index.json is pushed to the main branch, a GitHub Action automatically runs
3. Processing: The action processes each plugin entry to gather:
   • Version information from Git tags
   • NPM package metadata
   • Branch information for different ElizaOS versions (v0.x and v1.x)
   • Compatibility information
4. Output: A comprehensive generated-registry.json file is generated and committed back to the repository

Using the Generated Registry

The CLI and other tools can fetch the processed registry data directly from the raw GitHub URL:

# Fetch the processed registry data
curl https://raw.githubusercontent.com/elizaos-plugins/registry/main/generated-registry.json

This provides:

• Real-time version information
• Compatibility details
• Installation guidance
• Complete plugin metadata

Manual Generation

You can also generate the registry manually:

# Install dependencies
npm install

# Generate registry.json (requires GITHUB_TOKEN environment variable)
npm run generate-registry

The generated file will be generated-registry.json and contains the same format as served by the Next.js API, making it easy to switch between the API and static file approaches.