Rust Worker | NVIDIA NeMo Relay

The examples/rust-grpc-worker-plugin project is the compiled counterpart to the Python worker. It depends on nemo-relay-worker 0.9.0, implements WorkerPlugin, registers all 15 surfaces, and lets the SDK create the authenticated grpc-v1 server from the activation environment Relay provides.

Configure the Snapshot Location

Relay copies the worker runtime closure into an isolated activation snapshot before starting the worker. Set NEMO_RELAY_PLUGIN_SNAPSHOT_DIR in the environment that starts Relay to use a directory of your choice; Relay creates it when it does not exist. Choose a location outside every directory copied into a snapshot, including active plugin packages and external library directories:

1 $env:NEMO_RELAY_PLUGIN_SNAPSHOT_DIR = "C:\\nrs"

$ export NEMO_RELAY_PLUGIN_SNAPSHOT_DIR=/var/tmp/nrs

Build and Calculate Integrity

Build the executable and materialize its platform-specific manifest as follows:

Run the example from its own directory.
```
$ cargo test
$ cargo build
```
Copy relay-plugin.toml to relay-plugin.local.toml and replace <platform-worker-file> with nemo-relay-rust-grpc-worker-plugin-example on macOS or Linux, or the same name with .exe on Windows.
Calculate the promised digest before registration. On macOS run:
```
$ shasum -a 256 target/debug/<platform-worker-file>
```
On Linux run sha256sum target/debug/<platform-worker-file>. In PowerShell run Get-FileHash -Algorithm SHA256 target/debug/<platform-worker-file>. Put the lowercase hexadecimal value after sha256: in [integrity].sha256.

Success at this stage means tests pass, the manifest entrypoint resolves to the built executable, and integrity describes the exact executable that starts.

The local manifest retains the checked package identity and replaces only the executable name and digest placeholders:

1 manifest_version = 1
2 
3 [plugin]
4 id = "examples.rust_grpc_worker"
5 kind = "worker"
6 
7 [compat]
8 relay = ">=0.8.0,<1.0"
9 worker_protocol = "grpc-v1"
10 
11 [defaults]
12 enabled = false
13 
14 [capabilities]
15 items = ["plugin_worker", "config_schema"]
16 
17 [config_schema]
18 path = "config.schema.json"
19 
20 [source]
21 artifact = "target/debug/<platform-worker-file>"
22 
23 [integrity]
24 sha256 = "sha256:<artifact-sha256>"
25 
26 [load]
27 runtime = "rust"
28 entrypoint = "target/debug/<platform-worker-file>"

The worker speaks grpc-v1, whose Relay 0.8 tool-result baseline requires relay = ">=0.8.0,<1.0". ToolNext::call returns ToolExecutionResult, preserving an application payload and optional opaque annotation separately from Relay-owned pending marks. Rebuild the worker when adopting this SDK release; the protocol name remains grpc-v1, but an earlier generated binding cannot read the structural result messages.

The artifact and entrypoint paths must identify the same executable. Relay verifies the artifact digest before it starts the command, and the worker handshake must return the same plugin identity and grpc-v1 protocol.

Register and Start the Worker

Use the following procedure to register the manifest and inspect worker activation:

From the repository root, validate, add, and enable the local manifest.

$ nemo-relay plugins validate ./examples/rust-grpc-worker-plugin/relay-plugin.local.toml
$ nemo-relay plugins add --user ./examples/rust-grpc-worker-plugin/relay-plugin.local.toml
$ nemo-relay plugins enable examples.rust_grpc_worker

Start Relay from the repository root. Inspect the activation report and confirm the handshake reports plugin identity, SDK and runtime metadata, grpc-v1, multiple-component behavior, and all 16 surfaces.
```
$ nemo-relay --bind 127.0.0.1:4040
```

Build the Worker Implementation

The example uses the current public worker crate and creates both a library for focused tests and the executable named in the manifest.

1 [package]
2 name = "nemo-relay-rust-grpc-worker-plugin-example"
3 version = "0.1.0"
4 edition = "2024"
5 publish = false
6 
7 [dependencies]
8 futures-util = "0.3"
9 nemo-relay-worker = { version = "0.9.0", path = "../../crates/worker" }
10 serde = { version = "1", features = ["derive"] }
11 serde_json = "1"
12 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
13 
14 [lib]
15 name = "nemo_relay_rust_grpc_worker_plugin_example"
16 
17 [[bin]]
18 name = "nemo-relay-rust-grpc-worker-plugin-example"
19 path = "src/main.rs"

WorkerPlugin::register is a synchronous description step. It parses the validated JSON and fills the PluginContext with callbacks; the callbacks themselves return futures.

1 pub struct DocumentationWorker;
2 
3 impl WorkerPlugin for DocumentationWorker {
4     fn plugin_id(&self) -> &str {
5         "examples.rust_grpc_worker"
6     }
7 
8     fn allows_multiple_components(&self) -> bool {
9         false
10     }
11 
12     fn validate(&self, config: &Json) -> Vec<ConfigDiagnostic> {
13         config::validate(config)
14     }
15 
16     fn register(&self, context: &mut PluginContext, config: &Json) -> Result<()> {
17         let settings = ExampleConfig::parse(config)
18             .map_err(WorkerSdkError::InvalidInput)?;
19         if settings.observe.enabled {
20             register_observation(context, &settings);
21         }
22         if settings.requests.enabled {
23             register_requests(context, &settings);
24         }
25         register_execution(context, &settings);
26         Ok(())
27     }
28 }

The binary contains no transport configuration. serve_plugin reads the activation environment, starts the authenticated SDK service, and stays alive until Relay sends the shutdown stage.

1 use nemo_relay_rust_grpc_worker_plugin_example::DocumentationWorker;
2 use nemo_relay_worker::{Result, serve_plugin};
3 
4 #[tokio::main]
5 async fn main() -> Result<()> {
6     serve_plugin(DocumentationWorker).await
7 }

Exercise and Remove the Worker

Use the following procedure to verify the registered callbacks and stop the worker cleanly:

Exercise allowed and blocked calls, unary and streaming continuations, codec decode and encode proxies, pending marks, optimization contributions, nested and isolated scopes, and cancellation.

Disable and remove the component only after in-flight invocations have settled.

$ nemo-relay plugins disable examples.rust_grpc_worker
$ nemo-relay plugins remove examples.rust_grpc_worker

Success means shutdown rejects new invocations, cancels or drains active work, closes the authenticated endpoint, stops the process, and leaves no owned runtime registrations.

$	cargo test
$	cargo build