Build PluginsDynamic PluginsgRPC Worker

gRPC Worker Plugin Concepts

View as Markdown

Worker dynamic plugins run outside the Relay process and install subscribers, guardrails, and intercepts through the stable grpc-v1 protocol. The host starts the local worker, validates its component configuration, receives a declarative registration plan, and installs proxy callbacks.

Choose a Worker Runtime

Choose the runtime that matches the artifact you distribute:

  • Use python for a module:function entrypoint in a Relay-managed Python environment. Include source.manifest_root, then run nemo-relay plugins add so Relay can create and retain the required environment.
  • Use rust for a manifest-relative or absolute Rust executable.
  • Use command for another manifest-relative or absolute local executable that implements grpc-v1.

All worker runtimes receive the same local endpoint and activation credentials. The process boundary isolates crashes and dependencies, but it does not create a security sandbox.

Manifest

Use the following worker manifest:

1manifest_version = 1
2
3[plugin]
4id = "acme.policy"
5kind = "worker"
6
7[compat]
8relay = ">=0.5,<1.0"
9worker_protocol = "grpc-v1"
10
11[defaults]
12enabled = false
13
14[capabilities]
15items = ["plugin_worker"]
16
17[source]
18manifest_root = "."
19artifact = "acme_policy/worker.py"
20
21[integrity]
22sha256 = "sha256:<artifact-sha256>"
23
24[load]
25runtime = "python"
26entrypoint = "acme_policy.worker:main"

Set compat.worker_protocol to grpc-v1 and include plugin_worker in the capability list. Refer to Choose a Worker Runtime for the runtime-specific load and source requirements.

The worker receives its activation ID, plugin ID, worker and host endpoints, and a local activation token through environment variables. Do not start the worker directly during normal operation. The host supplies these values.

Registration and Trust

Workers return declarative registrations. Relay owns registry mutation, namespacing, rollback, and deregistration. Relay DTOs use JsonEnvelope values, while protobuf handles control flow.

Run nemo-relay plugins add and nemo-relay plugins validate to evaluate the configured host policy and artifact trust evidence. Refer to Configure Discoverable Plugins for the operator-side lifecycle and validation flow.

Next Steps