ZeroRoot Docs

Plugins

Build a deterministic, credential-bearing integration from a vendor SDK. You write one handler.go, GitOps deploys it, and its SPIFFE identity enrolls it.

A plugin is a deterministic, credential-bearing integration. It wraps a vendor's own SDK, or a hand-written API client, in the Gibson plugin harness. It exposes the wrapped client as a handful of typed methods. The plugin holds the credential, calls the vendor, and returns a curated result. It is the only Gibson component kind that reads secrets at runtime.

Use a plugin when you want a direct, typed API client that the caller drives with known inputs. No LLM decides the calls. The plugin does not use MCP. A plugin fits when you want to:

  • talk to a stateful or credentialed backend (GitHub, GitLab, Splunk, your CRM)
  • expose a stable, mission-shaped surface over a large vendor API
  • keep credentials in a component that an agent never touches

If you want an agent-driven integration over an existing vendor MCP server, build a connector instead. Plugins and connectors are separate, first-class component kinds with separate lifecycles. A plugin is code you write. A connector is a short declaration. A vendor can offer both.

The shape of a plugin

A plugin is one small Go module. The file that matters is handler.go. It holds the typed Go request and response structs and their handler functions. It also declares the plugin: its name, its version and each method with its description are arguments to plugin.Serve. No manifest file exists (ADR-0097).

There is no .proto and no generated code. The Go type is the method contract. The SDK derives each method's JSON-Schema input and output from the structs you register (ADR-0065). You write the types once, in Go, and you are done.

handler.go

package main

import (
	"context"
	"fmt"

	"github.com/google/go-github/v90/github"
	"github.com/zeroroot-ai/sdk/plugin"
	"github.com/zeroroot-ai/sdk/plugin/lifecycle"
)

// A typed method contract. The SDK derives the method's JSON-Schema from
// these structs at registration — expose a curated, mission-shaped subset
// of the vendor's API, not its entire surface.
type GetRepositoryRequest struct {
	Owner string `json:"owner"`
	Repo  string `json:"repo"`
}

type GetRepositoryResponse struct {
	Repository Repository `json:"repository"`
}

func handleGetRepository(ctx context.Context, req GetRepositoryRequest) (GetRepositoryResponse, error) {
	// The broker resolves the credential that a tenant admin granted this
	// plugin — never an env var. ResolveSecret returns the plaintext.
	token, err := plugin.ResolveSecret(ctx, "cred:github_token")
	if err != nil {
		return GetRepositoryResponse{}, err
	}
	gh, err := github.NewClient(github.WithAuthToken(string(token)))
	if err != nil {
		return GetRepositoryResponse{}, err
	}
	repo, _, err := gh.Repositories.Get(ctx, req.Owner, req.Repo)
	if err != nil {
		return GetRepositoryResponse{}, err
	}
	return GetRepositoryResponse{Repository: curate(repo)}, nil
}

// requireToken fails the start when the plugin cannot read its token, so a
// missing grant shows at boot with the secret named.
func requireToken(ctx context.Context) error {
	if _, err := plugin.ResolveSecret(ctx, "cred:github_token"); err != nil {
		return fmt.Errorf("resolve startup secret cred:github_token: %w", err)
	}
	return nil
}

func main() {
	_ = plugin.Serve(context.Background(),
		plugin.WithName("github"),
		plugin.WithVersion("0.1.0"),
		plugin.WithHandler("GetRepository", "Fetch a repository by owner and name.", handleGetRepository),
		// ...one WithHandler per method, each with its description
		plugin.WithLifecycle(lifecycle.LifecycleHooks{OnStart: requireToken}),
	)
}

plugin.Serve runs the whole lifecycle. It enrolls the plugin's identity, registers the declaration, and runs the OnStart hook. Then it polls for work, dispatches each call to the matching handler, and submits the result. The GitHub plugin is a complete worked example.

Runtime modes

The runtime value of the plugin entry in the chart values selects where a deployed plugin runs. On your own machine, the plugin runs as a process.

ModeWhere the plugin runsPick this when
processA bare process — your laptop or a dev containerLocal development, the fastest loop. Enrol with a one-time token (see below).
pod (default in-cluster)A Kubernetes pod, deployed by Helm/GitOpsProduction. Auto-enrols via its SPIFFE identity — no token.
setecA microVM under the Setec sandbox operatorHardened isolation for sensitive workloads.

Secrets

A plugin declares no secret. A tenant admin grants the plugin access to named secrets of the workspace when the plugin is deployed. The plugin resolves a secret through the broker with plugin.ResolveSecret, and the daemon checks the grant on each resolve. A plugin's identity reads exactly the secrets it was granted and nothing else.

A plugin that cannot start without a secret resolves it in its OnStart hook, as requireToken does above. A missing grant then fails the boot with the secret named. When a secret rotates, the plugin drops its cached value, and the next resolve gets the new value. See Secrets management.

Deploying a plugin

The plugin lifecycle is author → build → deploy → enroll. None of it is a dashboard upload.

1. Author it as one Go module

Each plugin is one Go module, so each plugin has an isolated dependency graph. Run gibson component init <name> --kind plugin in your own repo. It writes the handler, a test, the Dockerfile and the Helm values. Then replace the handlers. The first-party plugins live in gibson/plugins/<vendor>/ in the same layout.

2. Build the image in your CI

Your CI builds the plugin module into a container image in your registry, for example ghcr.io/<org>/<plugin>. There is no in-cluster build. There is no artifact you upload to us. You own the source and the image. The first-party plugin images are ghcr.io/zeroroot-ai/gibson-plugin-<vendor>.

3. Enable it in your GitOps values

The platform Helm chart deploys a plugin. Add an entry under plugins, keyed by vendor, that names the image CI built:

plugins:
  github:
    enabled: true
    image:
      repository: ghcr.io/your-org/github-plugin
      tag: v0.1.0
    runtime: pod          # pod (default) | setec

The chart renders the Deployment, ServiceAccount, and per-plugin NetworkPolicy. This is the platform's existing GitOps path. Argo, Flux, or helm upgrade already syncs the same chart.

4. The plugin enrolls itself

A pod-runtime plugin auto-enrolls with its SPIFFE SVID. The SPIRE agent issues the pod an identity. The plugin presents that identity to register with the platform. There is no bootstrap token and no manual step. The plugin re-enrolls cleanly on every restart. See Component bootstrap & auth for the identity model.

Before the plugin can start, a tenant admin grants it the secrets it resolves. After the plugin registers and reports Ready, it appears on the Plugins page in the dashboard. On that page you grant which tenants, teams, or agents may use it.

Local development

The process runtime on your own machine has no SPIRE socket. So you enroll once with a short-lived bootstrap token that you mint as yourself:

gibson agent enroll --name my-plugin --kind plugin   # prints a one-time token
export GIBSON_URL=https://<your-platform>
export GIBSON_BOOTSTRAP_TOKEN=<bootstrap-token>
gibson component run --kind plugin                   # runs plugin.Serve(ctx)

The first start exchanges the token for a persistent Ed25519 host key under ~/.gibson/. Every start after that is unattended. This is the local-dev path only. In-cluster plugins never need it.

Calling a plugin

A tool's harness invokes a plugin. An agent never invokes a plugin directly:

out, err := h.QueryPlugin(ctx, "github", "GetRepository", req)

This keeps agents one hop away from the credential-bearing plugin. That gives you a single place to gate plugin invocation. See Roles & permissions.

Testing

Plugins ship hermetic fixtures. handler_test.go replays a committed cassette. So tests run fully offline, per module, with no live vendor credentials. An AI-authored plugin is green from its first commit. A re-recorded fixture catches vendor API drift. A live gate does not.

On this page