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.
| Mode | Where the plugin runs | Pick this when |
|---|---|---|
| process | A bare process — your laptop or a dev container | Local development, the fastest loop. Enrol with a one-time token (see below). |
pod (default in-cluster) | A Kubernetes pod, deployed by Helm/GitOps | Production. Auto-enrols via its SPIFFE identity — no token. |
setec | A microVM under the Setec sandbox operator | Hardened 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.