feat: add experimental OpenShell environment provider

Cargo.toml

@@ -3,9 +3,11 @@
 
 [workspace]
 members = [
+    "crates/fabric-runtime-control",
     "crates/fabric-core",
     "crates/fabric-cli",
     "crates/fabric-python",
+    "environment-providers/openshell",
 ]
 default-members = [
     "crates/fabric-core",
@@ -16,6 +18,7 @@ resolver = "2"
 [workspace.package]
 version = "0.5.0"
 edition = "2024"
+rust-version = "1.88"
 license = "Apache-2.0"
 repository = "https://github.com/NVIDIA/nemo-fabric"
 

README.md

@@ -72,6 +72,7 @@ NeMo Fabric separates consumers from execution targets through a stable, version
 
 - **Expand the harness ecosystem:** Add high-priority first- and third-party harnesses through the normalized lifecycle and capability contracts.
 - **Sandbox-native execution:** Run NeMo Fabric in secure environments through providers such as [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview).
+  Try the [OpenClaw and Hermes code-review POC](examples/code_review_agent/openshell/README.md) for a two-turn agent loop executing inside an OpenShell sandbox.
 - **Deepen NVIDIA ecosystem integrations:** Make NeMo Fabric a standard execution boundary for agent configuration, evaluation, rollouts, artifacts, and telemetry.
 - **Enhance session lifecycle management:** Add explicit cold-start, resume, and fork operations with stable session identifiers and capability-aware errors.
 - **Compose subagents:** Configure supported subagents through validated, portable NeMo Fabric configuration.

adapters/python/common/README.md

@@ -20,6 +20,8 @@ Use the maintained
 for adapter and configuration guidance. Source code is available in the
 [NVIDIA NeMo Fabric repository](https://github.com/NVIDIA/NeMo-Fabric/).
 
+For OpenShell Relay execution, `load_relay_plugin_config(payload)` materializes the runtime's inline configuration inside the task artifact root and maps file outputs to a runtime directory there. The Hermes adapter declares gzip snapshots in `AgentRunResult.artifacts`; the environment provider collects these into host paths. Local Relay execution continues to use `FABRIC_RELAY_CONFIG_PATH`.
+
 ## Persistent Local Hosts
 
 Every local Process or Python adapter implements the ordered persistent-host

adapters/python/common/src/nemo_fabric_adapters/common/utils.py

@@ -536,6 +536,21 @@ def validate_relay_observability_v3(plugin_config: dict[str, Any]) -> None:
 
 
 def load_relay_plugin_config(payload: dict[str, Any]) -> dict[str, Any]:
+    context = runtime_context(payload)
+    metadata = (context.get("telemetry") or {}).get("metadata") or {}
+    if "relay_config" in metadata:
+        # The host cannot stage files on the task filesystem. Materialize the
+        # inline remote declaration without carrying host output paths across.
+        root = Path(context["artifacts"]["root"]).resolve()
+        config_path = (
+            root / ".fabric" / str(context["runtime_id"]) / "relay-config.json"
+        )
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(
+            json.dumps({"relay": {"config": metadata["relay_config"]}}),
+            encoding="utf-8",
+        )
+        os.environ["FABRIC_RELAY_CONFIG_PATH"] = str(config_path)
     config_path = os.environ.get("FABRIC_RELAY_CONFIG_PATH")
     if not config_path:
         raise RuntimeError("FABRIC_RELAY_CONFIG_PATH is required when Relay is enabled")
@@ -571,6 +586,9 @@ def normalize_relay_output_dirs(
 
     base = Path(base_dir(payload)).resolve()
     runtime_id = runtime_context(payload)["runtime_id"]
+    context = runtime_context(payload)
+    remote = "relay_config" in ((context.get("telemetry") or {}).get("metadata") or {})
+    remote_root = Path(context["artifacts"]["root"]) / "relay" if remote else None
     for component in plugin_config.get("components", []):
         if not isinstance(component, dict) or component.get("kind") != "observability":
             continue
@@ -588,7 +606,7 @@ def normalize_relay_output_dirs(
                         path = base / path
                 else:
                     path = base / "artifacts" / "relay"
-                sink["output_directory"] = str(path / str(runtime_id))
+                sink["output_directory"] = str((remote_root or path) / str(runtime_id))
                 Path(sink["output_directory"]).mkdir(parents=True, exist_ok=True)
                 sink.setdefault("filename", "events.atof.jsonl")
                 sink.setdefault("mode", "overwrite")
@@ -604,7 +622,7 @@ def normalize_relay_output_dirs(
         else:
             path = base / "artifacts" / "relay"
 
-        atif["output_directory"] = str(path / str(runtime_id))
+        atif["output_directory"] = str((remote_root or path) / str(runtime_id))
         Path(atif["output_directory"]).mkdir(parents=True, exist_ok=True)
         atif.setdefault("filename_template", "trajectory-{session_id}.atif.json")
         atif.setdefault("agent_name", agent_name(payload))

adapters/python/hermes/README.md

@@ -5,7 +5,7 @@ SPDX-License-Identifier: Apache-2.0
 
 # NVIDIA NeMo Fabric Hermes Agent Adapter
 
-This adapter runs Hermes Agent through its Python SDK.
+This adapter runs Hermes Agent through its Python SDK. The [code-review OpenShell POC](../../../examples/code_review_agent/openshell/README.md) packages this same adapter and agent loop inside a sandbox, with generated model access, task-side preflight, and optional collected Relay telemetry.
 
 ## Install
 
@@ -112,13 +112,13 @@ runtime.
 
 ## Execution Model
 
-Each NeMo Fabric runtime starts one local adapter host, constructs one Hermes Agent
+Each NeMo Fabric runtime starts one adapter host in the selected environment, constructs one Hermes Agent
 `AIAgent`, and opens one `SessionDB`. Ordered `Runtime.invoke(...)` calls reuse
 those native objects and pass the prior turn's returned transcript back to
 `run_conversation(...)`. Runtime stop calls the agent's idempotent `close()`
 method, closes the session database, and releases the Relay plugin context when
 enabled. Relay subscriber work is flushed after each invocation so ATIF output
-is complete before the result returns.
+is complete before the result returns. In OpenShell, the adapter declares separate gzip ATIF/ATOF snapshots for each invocation; the environment provider copies them into the host artifact manifest before sandbox cleanup.
 
 ## Maintaining The Adapter
 

adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py

@@ -65,6 +65,7 @@ def __init__(self) -> None:
         self._agent: Any = None
         self._relay_plugin_config: dict[str, Any] | None = None
         self._relay_plugin_config_path: Path | None = None
+        self._relay_artifact_versions: dict[str, tuple[int, int]] = {}
         self._active_invoke_task: asyncio.Task[tuple[dict[str, Any], str]] | None = None
 
     async def start(self, payload: dict[str, Any]) -> None:
@@ -372,6 +373,13 @@ def clear_active_invoke_task(
             status=AgentRunStatus.FAILED if failed else AgentRunStatus.SUCCEEDED,
             output=output,
             error=error,
+            artifacts=telemetry.snapshot_remote_relay_artifacts(
+                self._relay_plugin_config,
+                runtime_context,
+                self._relay_artifact_versions,
+            )
+            if self._relay_plugin_config is not None
+            else [],
         )
 
     async def _authenticate_mcp_servers(self) -> None:
@@ -505,6 +513,7 @@ async def stop(self) -> None:
         self._conversation_history = None
         self._relay_plugin_config = None
         self._relay_plugin_config_path = None
+        self._relay_artifact_versions = {}
         self._started = False
 
         if had_relay_plugin:

adapters/python/hermes/src/nemo_fabric_adapters/hermes/telemetry.py

@@ -5,12 +5,14 @@
 
 from __future__ import annotations
 
+import gzip
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version
 from pathlib import Path
+import shutil
 from typing import Any
 
-from nemo_fabric_adapter_contract.models import RuntimeContext
+from nemo_fabric_adapter_contract.models import AgentArtifact, RuntimeContext
 import nemo_fabric_adapters.common.utils as common_utils
 
 
@@ -23,6 +25,43 @@
 )
 
 
+def snapshot_remote_relay_artifacts(plugin_config, context: RuntimeContext, versions):
+    """Declare immutable per-invocation snapshots for provider collection."""
+    if not context.telemetry or "relay_config" not in context.telemetry.metadata:
+        return []
+    root = Path(context.artifacts.root).resolve()
+    destination = (
+        root / "relay-invocations" / context.runtime_id / context.invocation_id
+    )
+    declared = []
+    for artifact in common_utils.collect_relay_artifacts(plugin_config):
+        source = Path(artifact["path"]).resolve()
+        if not source.is_relative_to(root):
+            raise ValueError(
+                "remote Relay artifact must remain inside the task artifact root"
+            )
+        stat = source.stat()
+        version = (stat.st_mtime_ns, stat.st_size)
+        if artifact["kind"] == "atif" and versions.get(str(source)) == version:
+            continue
+        destination.mkdir(parents=True, exist_ok=True)
+        # Native trajectories can exceed the provider's per-file byte bound.
+        # Compress complete snapshots rather than truncate evidence or widen it.
+        target = destination / (source.name + ".gz")
+        with source.open("rb") as stream, gzip.open(target, "wb") as snapshot:
+            shutil.copyfileobj(stream, snapshot)
+        versions[str(source)] = version
+        declared.append(
+            AgentArtifact(
+                name=source.name + ".gz",
+                kind=artifact["kind"],
+                path=target.relative_to(root),
+                media_type="application/gzip",
+            )
+        )
+    return declared
+
+
 def finalize_hermes_relay_session(session_id: str) -> None:
     """Finalize one Relay session through the installed Hermes lifecycle API."""
     try:

adapters/python/openclaw/README.md

@@ -5,6 +5,8 @@ SPDX-License-Identifier: Apache-2.0
 
 # NVIDIA NeMo Fabric OpenClaw Adapter
 
+For managed execution with the agent loop and tools inside an OpenShell sandbox, see the [code-review OpenShell POC](../../../examples/code_review_agent/openshell/README.md).
+
 This adapter supports two lifecycle shapes:
 
 - Managed runtime: Each NeMo Fabric runtime owns an isolated local OpenClaw

adapters/typescript/kilo/test/configuration.test.mjs

@@ -24,7 +24,7 @@ test("rejects ambiguous, unsafe, and unsupported model configuration", () => {
   assert.throws(() => selectModel({models: {a: {provider: "x", model: "a", api_key_env: "KEY"}, b: {provider: "x", model: "b", api_key_env: "KEY"}}}), (error) => error.code === "kilo_model_ambiguous");
   assert.throws(() => selectModel({models: {default: {provider: "x", model: "a", api_key_env: "BAD-KEY"}}}), (error) => error.code === "kilo_invalid_model");
   assert.throws(() => selectModel({models: {default: {provider: "x", model: "a", api_key_env: "KEY", base_url: "http://example.com/v1"}}}), (error) => error.code === "kilo_invalid_model");
-  assert.equal(selectModel({harness: {settings: {allow_insecure_http_model_endpoint: true}}, models: {default: {provider: "x", model: "a", api_key_env: "KEY", base_url: "http://10.86.19.10:8000/v1"}}}).baseUrl, "http://10.86.19.10:8000/v1");
+  assert.equal(selectModel({harness: {settings: {allow_insecure_http_model_endpoint: true}}, models: {default: {provider: "x", model: "a", api_key_env: "KEY", base_url: "http://192.168.1.10:8000/v1"}}}).baseUrl, "http://192.168.1.10:8000/v1");
   for (const url of ["http://example.com/v1", "http://8.8.8.8/v1", "http://169.254.169.254/v1"]) {
     assert.throws(() => selectModel({harness: {settings: {allow_insecure_http_model_endpoint: true}}, models: {default: {provider: "x", model: "a", api_key_env: "KEY", base_url: url}}}), (error) => error.code === "kilo_invalid_model");
   }