> This page is for version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/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/gym/llms.txt.

# nemo_gym.web.browser_session

Browser-supply leases shared by stateful web environments.

The benchmark owns tasks, actions, observations, and evaluation.  A browser
session provider owns only the lifecycle of the isolated runtime in which the
browser executes.  Keeping that boundary asynchronous lets a provider acquire
an AgentEnv, container, VM, or remote browser without blocking the resources
server event loop, while synchronous Playwright operations remain on their
session-affine worker thread.

Remote providers should issue expiring leases and renew them from
`heartbeat`.  If the Gym process dies, heartbeats stop and provider-side TTL
cleanup becomes the final backstop against orphaned training sessions.

## Module Contents

### Classes

| Name                                                                                                     | Description                                                          |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [`BrowserSessionError`](#nemo_gym-web-browser_session-BrowserSessionError)                               | A provider could not supply or maintain a usable browser session.    |
| [`BrowserSessionHandle`](#nemo_gym-web-browser_session-BrowserSessionHandle)                             | Opaque provider handle retained until the rollout is released.       |
| [`BrowserSessionProvider`](#nemo_gym-web-browser_session-BrowserSessionProvider)                         | Acquire and release one isolated browser runtime per rollout.        |
| [`BrowserSessionSpec`](#nemo_gym-web-browser_session-BrowserSessionSpec)                                 | Provider-neutral request for one rollout-scoped browser runtime.     |
| [`LocalProcessBrowserSessionProvider`](#nemo_gym-web-browser_session-LocalProcessBrowserSessionProvider) | Represent the resources-server process and its DISPLAY as one lease. |
| [`RenewableBrowserSessionProvider`](#nemo_gym-web-browser_session-RenewableBrowserSessionProvider)       | Optional provider extension for renewing an expiring external lease. |

### Functions

| Name                                                                                                   | Description                                                                  |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| [`_entry_point_providers`](#nemo_gym-web-browser_session-_entry_point_providers)                       | -                                                                            |
| [`_local_instance_pool`](#nemo_gym-web-browser_session-_local_instance_pool)                           | -                                                                            |
| [`create_browser_session_provider`](#nemo_gym-web-browser_session-create_browser_session_provider)     | Instantiate a provider from a single-key `{name: kwargs}` mapping. |
| [`list_browser_session_providers`](#nemo_gym-web-browser_session-list_browser_session_providers)       | -                                                                            |
| [`register_browser_session_provider`](#nemo_gym-web-browser_session-register_browser_session_provider) | Register an in-process provider implementation by configuration name.        |

### Data

[`BrowserSessionProviderFactory`](#nemo_gym-web-browser_session-BrowserSessionProviderFactory)

[`ENTRY_POINT_GROUP`](#nemo_gym-web-browser_session-ENTRY_POINT_GROUP)

[`_PROVIDER_REGISTRY`](#nemo_gym-web-browser_session-_PROVIDER_REGISTRY)

### API

```python
class nemo_gym.web.browser_session.BrowserSessionError()
```

**Bases:** `RuntimeError`

A provider could not supply or maintain a usable browser session.

```python
class nemo_gym.web.browser_session.BrowserSessionHandle(
    session_id: str | None = None,
    provider_name: str | None = None,
    transport: str = 'local_process',
    endpoint: str | None = None,
    metadata: dict[str, typing.Any] = dict(),
    owner_pid: int | None = None,
    provider_state: typing.Any = None
)
```

Dataclass

Opaque provider handle retained until the rollout is released.

`transport` describes how the benchmark driver reaches the runtime.
The built-in reference runtime uses `local_process`.  Future providers
may return `agentenv` or `remote_cdp` and pair that lease with a driver
that implements the same `WebBrowserDriver` contract.

The handle is deliberately transport-neutral. Providers may keep their
SDK object in `provider_state`; benchmark code must use only the declared
transport, endpoint, and metadata instead of depending on that object.

**`endpoint`** `str | None = None`

---

**`metadata`** `dict[str, Any] = field(default_factory=dict)`

---

**`owner_pid`** `int | None = None`

---

**`provider_name`** `str | None = None`

---

**`session_id`** `str | None = None`

---

**`transport`** `str = 'local_process'`

---

```python
class nemo_gym.web.browser_session.BrowserSessionProvider()
```

Protocol

Acquire and release one isolated browser runtime per rollout.

Implementations with synchronous SDKs must offload blocking calls with
`asyncio.to_thread`.  `release` must be idempotent.  Metered or remote
providers must enforce `BrowserSessionSpec.lease_ttl_seconds` outside the
Gym process so a process crash cannot leak the session indefinitely.

**`name`** `str`

---

```python
nemo_gym.web.browser_session.BrowserSessionProvider.acquire(
    spec: nemo_gym.web.browser_session.BrowserSessionSpec
) -> nemo_gym.web.browser_session.BrowserSessionHandle
```

async

```python
nemo_gym.web.browser_session.BrowserSessionProvider.release(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None
```

async

```python
class nemo_gym.web.browser_session.BrowserSessionSpec(
    metadata: dict[str, str] = dict(),
    provider_options: dict[str, typing.Any] = dict(),
    lease_ttl_seconds: int = 900
)
```

Dataclass

Provider-neutral request for one rollout-scoped browser runtime.

**`lease_ttl_seconds`** `int = 900`

---

**`metadata`** `dict[str, str] = field(default_factory=dict)`

---

**`provider_options`** `dict[str, Any] = field(default_factory=dict)`

---

```python
class nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider(
    display_env: str = 'DISPLAY'
)
```

Represent the resources-server process and its DISPLAY as one lease.

The provider itself does not launch Chromium; the visual-browser driver
does that on its dedicated thread.  The handle records the owning process
so a forked child cannot accidentally operate a parent's Playwright state.

**`name`** `= 'local_process'`

---

```python
nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider._require_owner(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None
```

staticmethod

```python
nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider.acquire(
    spec: nemo_gym.web.browser_session.BrowserSessionSpec
) -> nemo_gym.web.browser_session.BrowserSessionHandle
```

async

```python
nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider.heartbeat(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None
```

async

```python
nemo_gym.web.browser_session.LocalProcessBrowserSessionProvider.release(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None
```

async

```python
class nemo_gym.web.browser_session.RenewableBrowserSessionProvider()
```

Protocol

**Bases:** [BrowserSessionProvider](#nemo_gym-web-browser_session-BrowserSessionProvider)

Optional provider extension for renewing an expiring external lease.

```python
nemo_gym.web.browser_session.RenewableBrowserSessionProvider.heartbeat(
    handle: nemo_gym.web.browser_session.BrowserSessionHandle
) -> None
```

async

```python
nemo_gym.web.browser_session._entry_point_providers() -> dict[str, type[nemo_gym.web.browser_session.BrowserSessionProvider]]
```

```python
nemo_gym.web.browser_session._local_instance_pool(
    kwargs: typing.Any = {}
) -> nemo_gym.web.browser_session.BrowserSessionProvider
```

```python
nemo_gym.web.browser_session.create_browser_session_provider(
    config: collections.abc.Mapping[str, typing.Any]
) -> nemo_gym.web.browser_session.BrowserSessionProvider
```

Instantiate a provider from a single-key `{name: kwargs}` mapping.

```python
nemo_gym.web.browser_session.list_browser_session_providers() -> list[str]
```

```python
nemo_gym.web.browser_session.register_browser_session_provider(
    name: str,
    provider_class: typing.Callable[..., nemo_gym.web.browser_session.BrowserSessionProvider],
    override: bool = False
) -> None
```

Register an in-process provider implementation by configuration name.

```python
nemo_gym.web.browser_session.BrowserSessionProviderFactory = Callable[[Mapping[str, Any]], BrowserSessionProvider]
```

```python
nemo_gym.web.browser_session.ENTRY_POINT_GROUP = 'nemo_gym.web_browser_session_providers'
```

```python
nemo_gym.web.browser_session._PROVIDER_REGISTRY: dict[str, Callable[..., BrowserSessionProvider]] = {LocalProcessBrowserSessionProvider.name: LocalProcessBrowserSessionProvider, 'l...
```