Plugins

Veyyon supports extending the agent’s capabilities with plugins. A plugin can add custom skills, Model Context Protocol (MCP) servers, applications, lifecycle hooks, and terminal user interface (TUI) customizations.

Plugin Structure

Every plugin is a directory with a .veyyon-plugin/plugin.json manifest file. The manifest describes the plugin’s metadata and lists its integration points.

Plugin Manifest (`plugin.json`)

The following fields are defined in the plugin.json schema:

Field	Type	Description
`name`	String	The unique name of the plugin. Only ASCII alphanumeric characters, hyphens, and underscores are allowed.
`version`	String	The version of the plugin (optional). Defaults to `"local"`.
`description`	String	A description of the plugin (optional).
`keywords`	Array of Strings	Keywords used to index and search for the plugin (optional).
`skills`	String or Array of Strings	Path or paths to directories containing skill definitions (optional).
`mcpServers`	String or Object	Path to a file or an inline object defining the plugin’s MCP servers (optional).
`apps`	String	Path to a file defining the plugin’s custom applications and connectors (optional).
`hooks`	String or Array of Strings or Object	Path or paths to hook definition files, or inline hook objects (optional).
`interface`	Object	Presentation metadata for the TUI (optional). Details like display name, descriptions, default prompt, developer name, category, website, privacy policy, and logo files.

Marketplaces

Marketplaces are collections of plugins. A marketplace is a directory or Git repository containing a marketplace.json catalog manifest.

Veyyon checks the following relative paths under a marketplace root to locate its catalog manifest:

.agents/plugins/marketplace.json (canonical path)
.agents/plugins/api_marketplace.json
.claude-plugin/marketplace.json

The marketplace catalog defines:

A name and optional presentation metadata.
A plugins list. Each entry contains the plugin name, installation policy, authentication policy, supported products, and its source. The source can point to a local directory or a Git repository (with optional branch, tag, commit ref, or subdirectory path).

File Locations

Veyyon stores plugins and marketplaces under the home directory (VEYYON_HOME). If VEYYON_HOME is not set, it defaults to ~/.veyyon.

Path	Description
`VEYYON_HOME/.tmp/marketplaces/<marketplace_name>`	Snapshots/clones of Git marketplaces.
`VEYYON_HOME/plugins/cache/<marketplace_name>/<plugin_name>/<version>`	Installed plugin files.
`VEYYON_HOME/plugins/data/<plugin_name>-<marketplace_name>`	Persistent data generated by the plugin.
`VEYYON_HOME/plugins/.marketplace-plugin-source-staging`	Staging area for downloading remote plugins.

Command Line Interface

You can manage plugins and marketplaces using the veyyon plugin and veyyon plugin marketplace command groups.

Managing Plugins

Add a Plugin

Install a plugin from a configured marketplace. Specify the plugin as plugin_name@marketplace_name, or use the --marketplace option.

$ veyyon plugin add sample@debug
$ veyyon plugin add sample --marketplace debug

Use the --json flag to print the installation result as JSON.

List Plugins

List installed plugins and their statuses.

$ veyyon plugin list

Options:

-m, --marketplace <name>: Filter listing to a specific marketplace.
--json: Print the output as JSON.
--available: Include uninstalled but available plugins from the marketplaces (requires --json).

Remove a Plugin

Uninstall a plugin from local cache and config.

$ veyyon plugin remove sample@debug

Use the --json flag to return the removal result as JSON.

Managing Marketplaces

Add a Marketplace

Add a local path or Git repository to your configured marketplace sources.

$ veyyon plugin marketplace add ./path/to/marketplace
$ veyyon plugin marketplace add owner/repo --ref main
$ veyyon plugin marketplace add https://github.com/owner/repo --sparse plugins/foo

Options:

--ref <ref>: Git branch, tag, or commit SHA to fetch.
--sparse <path>: Limits the Git clone to a specific subdirectory. Can be repeated.
--json: Print the result as JSON.

List Marketplaces

List all configured marketplaces and their filesystem root directories.

$ veyyon plugin marketplace list

Use the --json flag to output the list as JSON.

Upgrade Marketplaces

Fetch the latest revisions for configured Git marketplaces. Omit the marketplace name to upgrade all configured Git marketplaces.

$ veyyon plugin marketplace upgrade
$ veyyon plugin marketplace upgrade debug

Use the --json flag to output the upgrade result as JSON.

Remove a Marketplace

Remove a configured marketplace by name.

$ veyyon plugin marketplace remove debug

Use the --json flag to output the result as JSON.

TUI Integration

Veyyon TUI integrates plugin management directly.

Slash Commands

/plugins: Opens the interactive plugins catalog popup. You can browse all available plugins, install or uninstall them, and toggle plugins on or off.
/apps: Opens the apps and connectors status and configuration popup.

TUI Keybindings

When the /plugins popup is open, you can use the following keyboard shortcuts on the selected marketplace tab:

Ctrl+R: Remove the selected configured marketplace.
Ctrl+U: Upgrade the selected configured Git marketplace.

Configuration File

Marketplaces and plugin settings are stored persistently in your config.yml file.

Marketplaces Section

Marketplaces are registered under the marketplaces map, keyed by marketplace name.

marketplaces:
  debug:
    source_type: git
    source: https://github.com/owner/repo.git
    ref: main
    sparse_paths: ["plugins/"]
    last_updated: "2026-07-13T10:00:00Z"

Plugins Section

Each installed plugin has an entry under the plugins map keyed by <plugin_name>@<marketplace_name>. You can toggle the plugin or configure tool settings for its contributed MCP servers.

plugins:
  "sample@debug":
    enabled: true
    mcp_servers:
      sample_server:
        enabled: true
        default_tools_approval_mode: always
        enabled_tools: ["compile", "test"]
        disabled_tools: ["delete_all"]

Install and discovery tools (list_available_plugins_to_install, request_plugin_install) are documented in Tools reference. For task-shaped recipes that combine plugins with MCP and skills, see Task guides.

Keyboard shortcuts

The Veyyon Harness Handbook