Plugin Interface Reference

Complete reference for the kaged plugin system — manifest, capabilities, and JSON-RPC protocol.

Plugins are external processes that communicate with the daemon over stdin/stdout JSON-RPC 2.0.

Every plugin ships a manifest.yaml declaring its name, methods, capabilities, and lifecycle parameters.

The daemon spawns the plugin, performs a handshake (initialize → initialized), then routes method calls. Health checks run periodically. On shutdown, the daemon sends a shutdown request and waits up to shutdown_timeout_sec.

# Plugin Manifest

The manifest.yaml file that every kaged plugin must provide.

Field	Type	Required	Default	Description
`name`	`string (pattern)`	yes	—	Plugin name — lowercase slug (a-z, 0-9, hyphens; max 64 chars). [min length: 1, max length: 64, pattern: `^[a-z][a-z0-9-]*$`]
`version`	`string`	yes	—	Semver version string. [min length: 1]
`kaged_api`	`integer`	yes	—	Required kaged plugin API version (positive integer). [min: 0]
`description`	`string`	yes	—	Short description (1-200 chars). [min length: 1, max length: 200]
`author`	`string`	no	—	Plugin author.
`license`	`string`	no	—	SPDX license identifier.
`homepage`	`url`	no	—	Plugin homepage URL.
`command`	`string[]`	yes	—	Command to spawn the plugin process (array of strings, min 1). [min items: 1]
`env`	`Record<string, string>`	no	`{}`	Environment variables to set when spawning (default: {}).
`capabilities`	`string[]`	no	`[]`	Declared capabilities — see §capabilities (default: []).
`methods`	`string (pattern)[]`	yes	—	JSON-RPC method names this plugin exposes (min 1). Must be dot-delimited, 2-4 segments, lowercase. [min items: 1]
`notifications`	`string[]`	no	`[]`	Notification names this plugin can emit (default: []).
`config_schema`	`Record<string, unknown>`	no	—	JSON Schema for plugin-specific configuration.
`shutdown_timeout_sec`	`integer`	no	`5`	Seconds to wait for graceful shutdown (1-30, default: 5). [min: 1, max: 30]
`health_interval_sec`	`integer`	no	`30`	Seconds between health checks (5-300, default: 30). [min: 5, max: 300]

# Capabilities

Capability strings declare what resources a plugin needs. Declared in manifest.yaml, validated at load time.

Field	Type	Required	Default	Description
`read:fs:<path>`	`string`	yes	—	Read access to an absolute filesystem path.
`write:fs:<path>`	`string`	yes	—	Write access to an absolute filesystem path.
`exec:<binary>:<path>`	`string`	yes	—	Execute a binary at the given path.
`net:<host>:<port>`	`string`	yes	—	Network access to a specific host:port.
`net:<host>:*`	`string`	yes	—	Network access to all ports on a host.
`net:*`	`string`	yes	—	Unrestricted network access.
`net:[]`	`string`	yes	—	No network access (explicit deny).
`kaged:storage:read`	`string`	yes	—	Read access to kaged's plugin storage.
`kaged:storage:write`	`string`	yes	—	Write access to kaged's plugin storage.

# JSON-RPC Protocol

Plugins communicate with the daemon over stdin/stdout using JSON-RPC 2.0.

Field	Type	Required	Default	Description
`initialize`	`object`	yes	—	Daemon sends initialize request with daemon_version, api_version, plugin_name, storage_available, projects. Plugin responds with name, version, api_version, methods, notifications, capabilities_used.
`initialized`	`object`	yes	—	Daemon sends initialized notification after successful handshake.
`shutdown`	`object`	yes	—	Daemon sends shutdown request. Plugin should clean up and exit within shutdown_timeout_sec.
`health.check`	`object`	yes	—	Daemon pings plugin at health_interval_sec intervals. Plugin must respond within 5 seconds.

Method names must not start with kaged.* or system.* — these prefixes are reserved.

Max message size: 4 MB. Notification rate limit: 100/sec.