Environments and Shared Services
For examples that reuse config, start with Start With One Run.
Explicit Environment Lifecycle
prepare_environment(config) returns an immutable EnvironmentHandle without
starting an agent. Pass it to start_runtime_in(config, environment) to start a
runtime, then invoke and stop that runtime normally. Call
release_environment(environment) separately after collecting results. Local
release preserves caller-owned files and supports multiple runtimes.
attach_environment(config, EnvironmentReference.from_mapping(...)) asks the
selected provider to verify an existing resource. Providers that do not support
attachment return an unsupported-provider error. Attachment retains caller
ownership; release detaches without deleting that resource. Provider availability
and runtime reuse limits depend on the selected environment implementation.
Non-local workspace and artifact paths refer to the task environment and are
not resolved against the host’s base_dir. The OpenShell provider starts the
agent through the task SDK command bridge. One sandbox can host multiple
independent runtime IDs; invoke and stop target a specific ID, and stopping one
does not stop the others. Streaming and shared-service hosting remain local SDK
capabilities.
The optional OpenShell provider
uses the task command bridge and returns the task-generated SDK runtime ID and
normalized results. Declared files are collected under the host’s
runtime.artifacts/<runtime_id>/<invocation_id>/ directory. The task artifact
root is separate. OpenShell invocation is buffered; streaming and shared-service
hosting remain local SDK capabilities. Commands with uncertain outcomes are
never replayed; an uncertain start blocks further starts in that sandbox.
Shared Services
Use prepare_service(...) when NeMo Fabric should create and supervise a
long-lived service. Start independent runtimes against the returned service,
then stop every runtime before releasing it.
This example uses OpenClaw. Install OpenClaw and its adapter and set NVIDIA_API_KEY for the NVIDIA-hosted model before running it. The configuration selects the OpenClaw adapter, which provides the openclaw_gateway service type.
Use attach_service(...) when another system owns deployment and supervision.
The adapter defines the required ServiceReference.connection fields. The
reference contains locators and secret references, not secret values. Releasing
an attachment only removes NeMo Fabric-owned clients and temporary state.
For this example, replace the Gateway URL and set OPENCLAW_GATEWAY_TOKEN to its authentication token. The deployment must already configure the selected model and its credentials. The client configuration selects OpenClaw and omits deployment-owned model endpoints, API-key references, tools, MCP servers, and skills; the adapter rejects those fields on attachment because it cannot verify or apply them to an existing Gateway. Refer to Attach to a Caller-Owned Gateway for the complete restrictions.
Service.handle is safe to inspect but is valid only in the process that
created it. Cold-resume behavior will be defined separately.
Install And Runtime Responsibilities
In production, the consumer or execution environment is responsible for installing NeMo Fabric, the selected harness, adapter dependencies, model access, credentials, and any required native tools. NeMo Fabric validates and diagnoses the runtime assumptions, but it does not silently install harnesses or credentials at invocation time.
Development environments may use extras, virtual environments, or local source checkouts to make iteration easy. Production environments should prefer explicit images, preinstalled dependencies, or managed deployment packages.
Runtime compatibility checks should validate:
- NeMo Fabric SDK and native extension versions;
- selected adapter version;
- selected harness version or version range;
- required environment variables or secret references;
- optional capability support such as NeMo Relay, MCP, or tool exposure.