Plugin Development

This guide covers how to create plugins that are installable via orchestra install.

Requirements

For a plugin to be installable, it must:

1. Be a Go module hosted on GitHub (e.g., github.com/my-org/my-plugin).
2. Build to a single binary with an entry point at cmd/main.go or the module root.
3. Support the --manifest flag that prints plugin metadata as JSON to stdout and exits.
4. Print READY <addr> to stderr when the QUIC server is listening.
5. Accept standard plugin flags: --orchestrator-addr, --listen-addr, --certs-dir.

All of these are handled automatically by the SDK if you use plugin.New(...).BuildWithTools() and call p.ParseFlags().

Plugin Structure

Manifest Format

When --manifest is passed, the binary must print JSON to stdout and exit:

The orchestra install command uses this to register the plugin's capabilities.

Distribution

Option A: Pre-built Binaries (Recommended)

Create GitHub Releases with platform-specific tarballs:

Each tarball should contain the plugin binary at the root level. The binary name must match the repository name.

Use GitHub Actions or GoReleaser to automate this.

Option B: Source Build

If no release binary is available, orchestra install falls back to cloning the repo and running go build. The build target is auto-detected:

1. cmd/main.go exists -> build ./cmd/
2. cmd/ directory exists -> build ./cmd/
3. Otherwise -> build ./

Installation Flow

When a user runs orchestra install github.com/my-org/my-plugin:

1. Attempt to download my-plugin-{os}-{arch}.tar.gz from GitHub Releases.
2. If download fails (and --binary not set), clone the repo and go build.
3. Place the binary in ~/.orchestra/plugins/bin/my-plugin.
4. Run my-plugin --manifest to discover capabilities.
5. Register in ~/.orchestra/plugins/registry.json.

Integration with orchestra serve

When orchestra serve starts, it:

1. Loads the plugin registry from ~/.orchestra/plugins/registry.json.
2. Adds each registered plugin to the orchestrator's plugins.yaml config.
3. The orchestrator starts the plugin binary with standard flags.
4. The plugin's tools become available through MCP.

Testing Your Plugin

Test that your plugin works with Orchestra end-to-end:

Example: Minimal Plugin

go.mod:

cmd/main.go: