> This page is for NeMo Fabric, version Latest (v0.7.0) (default).
> For other versions, use one of these documentation indexes:
> - Latest (v0.7.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.7.0: https://docs.nvidia.com/nemo/fabric/v0.7.0/llms.txt
> - v0.6.1: https://docs.nvidia.com/nemo/fabric/v0.6.1/llms.txt
> - v0.6.0: https://docs.nvidia.com/nemo/fabric/v0.6.0/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/llms.txt.

# Environments and Shared Services

> Manage environment and shared-service lifecycles from the Python SDK.

For examples that reuse `config`, start with [Start With One Run](/nemo/fabric/sdk/python-sdk#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](https://github.com/NVIDIA/NeMo-Fabric/blob/v0.7.0/environment-providers/openshell/README.md)
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](/nemo/fabric/integrations/harness-integrations/open-claw#install-openclaw-and-the-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.

```python
import asyncio

from nemo_fabric import Fabric, FabricConfig, HarnessConfig, MetadataConfig, ModelConfig

service_config = FabricConfig(
    metadata=MetadataConfig(name="shared-openclaw"),
    harness=HarnessConfig(adapter_id="nvidia.fabric.openclaw"),
    models={
        "default": ModelConfig(
            provider="nvidia",
            model="nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
            base_url="https://integrate.api.nvidia.com/v1",
            api_key_env="NVIDIA_API_KEY",
        )
    },
)

async def main():
    fabric = Fabric()
    async with await fabric.prepare_service(service_config) as service:
        async with await fabric.start_runtime(service_config, service=service) as first:
            async with await fabric.start_runtime(service_config, service=service) as second:
                first_result = await first.invoke(input="Inspect the repository")
                second_result = await second.invoke(input="Review the latest patch")

asyncio.run(main())
```

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](https://github.com/NVIDIA/NeMo-Fabric/blob/v0.7.0/adapters/python/openclaw/README.md#attach-to-a-caller-owned-gateway) for the complete restrictions.

```python
import asyncio

from nemo_fabric import (
    Fabric,
    FabricConfig,
    HarnessConfig,
    MetadataConfig,
    ModelConfig,
    ServiceReference,
)

attached_config = FabricConfig(
    metadata=MetadataConfig(name="attached-openclaw"),
    harness=HarnessConfig(adapter_id="nvidia.fabric.openclaw"),
    models={
        "default": ModelConfig(
            provider="nvidia",
            model="nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
        )
    },
)

async def main():
    reference = ServiceReference.from_mapping(
        {
            "adapter_id": "nvidia.fabric.openclaw",
            "service_type": "openclaw_gateway",
            "connection": {
                "gateway_url": "https://openclaw.example.com",
                "gateway_token_env": "OPENCLAW_GATEWAY_TOKEN",
            },
        }
    )

    fabric = Fabric()
    async with await fabric.attach_service(attached_config, reference) as service:
        async with await fabric.start_runtime(attached_config, service=service) as runtime:
            result = await runtime.invoke(input="Review the latest patch")

asyncio.run(main())
```

`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.