> This page is for NeMo Fabric, version v0.5.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.4.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/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.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/fabric/_mcp/server.

# Use the OpenCode Adapter

> Install and configure the NVIDIA NeMo Fabric harness integration for OpenCode.

Use the `nvidia.fabric.opencode` adapter to run tasks with the OpenCode 2 SDK.
Each NVIDIA NeMo Fabric runtime starts one embedded OpenCode host and session.

## Install the Adapter

OpenCode adapter processes require Bun 1.4.2 or later on `PATH`.

To use a published adapter release, install the npm adapter and the compatible
OpenCode SDK in the project that owns the NeMo Fabric configuration:

```bash
npm install nemo-fabric-adapters-opencode @opencode/core@2.0.23 @opencode/sdk@2.0.23
```

OpenCode Core and the OpenCode SDK are optional peers, exact-pinned to the
supported OpenCode release. Installing the adapter alone does not install
either package. Starting the adapter without the compatible packages returns
`opencode_harness_unavailable`.

OpenCode 2.0.23 does not support npm's `install-strategy=nested`. The documented
command requires the default npm hoisted layout.

For source development, install the checked-out adapter workspace and its
pinned SDK from the repository root, then build the generated adapter CLI:

```bash
just install-typescript-opencode
npm run build --prefix adapter-contract/typescript
npm run build --prefix adapters/typescript --workspace nemo-fabric-adapters-common
npm run build --prefix adapters/typescript --workspace nemo-fabric-adapters-opencode
```

## Configure the Adapter

Select the OpenCode integration and point discovery at the adapter descriptor.
The following example uses the descriptor from an installed npm package:

```python
from nemo_fabric import DiscoveryConfig, FabricConfig, HarnessConfig
from nemo_fabric import MetadataConfig, ModelConfig

config = FabricConfig(
    metadata=MetadataConfig(name="opencode-review"),
    discovery=DiscoveryConfig(
        local_paths=[
            "./node_modules/nemo-fabric-adapters-opencode/opencode.fabric-adapter.json"
        ]
    ),
    harness=HarnessConfig(adapter_id="nvidia.fabric.opencode"),
    models={
        "default": ModelConfig(
            provider="nvidia",
            model="nvidia/nemotron-3.5-nano-30b-a3b",
            api_key_env="NVIDIA_API_KEY",
            base_url="https://integrate.api.nvidia.com/v1",
        )
    },
)
```

This example uses NVIDIA's hosted Nemotron 3.5 Nano model. Set
`NVIDIA_API_KEY` before starting the runtime.

For a source build, set `discovery.local_paths` to
`adapters/typescript/opencode/opencode.fabric-adapter.json` instead. The build
commands above create the descriptor's `dist/cli.js` runner.

## Supported Configuration

The adapter supports the following configuration:

* **Models:** Selects the `default` role, or the only configured role.
  `api_key_env` may use any portable environment-variable name. When no
  endpoint is configured, the provider and model must be supported by the
  installed OpenCode SDK.
* **Instructions:** Supports `instructions.system` with `mode: replace`.
  A replacement instruction replaces OpenCode's base prompt. OpenCode may still
  append runtime context.
* **Skills:** Each `skills.paths` entry must be a directory containing `SKILL.md`.
  Startup verifies that only those `SKILL.md` files load and that names are unique.
* **MCP:** Supports `stdio` and `streamable-http`. Startup fails if a configured
  server cannot connect.

### Model Endpoints

To route model requests through a local or company-hosted endpoint, set
`base_url`. The endpoint must implement the OpenAI-compatible Chat Completions
protocol. It is a model-provider endpoint, not the address of a remote
OpenCode server. Remote endpoints must use HTTPS because requests include the
provider credential. HTTP is permitted only for loopback endpoints used in
local development and testing. The adapter removes OpenCode's
`prompt_cache_key` extension for configured endpoints, so providers that
reject that OpenAI-specific field can still use the core protocol. The proxy
buffers and rewrites request bodies up to 16 MiB. Larger requests receive HTTP
413 rather than consuming unbounded adapter memory.

`temperature` and `top_p` are supported only with `base_url`.

To configure a loopback OpenAI-compatible endpoint for development, set
`base_url` as follows:

```python
config.models["default"].base_url = "http://127.0.0.1:8080/v1"
```

### MCP Configuration

Streamable-HTTP servers may define headers but not command arguments. Stdio
servers may define command arguments and environment variables but not HTTP
headers.

Streamable-HTTP server URLs require HTTPS except for loopback development
endpoints.

Header values may reference `${NAME}`. Resolution checks `environment.env`
first, then the parent process environment. Unresolved references fail startup.
For MCP credentials, prefer parent-only variables so they are used to construct
the header without being added to OpenCode's tool environment.

SSE, MCP authentication objects, and per-server tool filters are unsupported.
MCP elicitation is also unsupported. Configure only non-interactive MCP servers as
NeMo Fabric cannot reply to an elicitation request, so it can block an
invocation until its configured timeout.

### Runtime Behavior

The embedded session keeps the Fabric workspace as its working location, but
does not load ambient OpenCode project or user configuration and instructions
from that workspace or the host home directory.

At runtime, OpenCode receives only required operating-system variables,
explicit Fabric `environment.env` values, and the selected model credential.
Other variables inherited by the Fabric process are not exposed to OpenCode.

The adapter is non-interactive. It denies OpenCode's direct `read` permission
for `.env` files (except `.env.example`), access outside the workspace, or
follow-up questions rather than waiting for an approval that NeMo Fabric cannot
supply. These rules are not a filesystem sandbox and do not prevent shell tools
from reading files in the workspace.

The adapter accepts plain-text input and returns the final response in
`output.response`. Streaming, Relay, tool policy, subagents,
provider-specific model settings, and `max_tokens` are not supported.

## Understand the Runtime Lifecycle

The adapter runs in a persistent Bun process. `start` creates one embedded
OpenCode host and one OpenCode session for the NeMo Fabric runtime. Ordered
plain-text invocations reuse that session and its conversation history. A
successful result has `output.response`. Usage fields are present when OpenCode
reports them. `stop` removes the OpenCode session and closes the embedded host.

```mermaid
flowchart LR
  Fabric["Fabric runtime"] -->|"NDJSON over stdio"| Adapter
  subgraph Bun["One persistent Bun adapter process"]
    Adapter["OpenCode adapter"] --> Client["OpenCode SDK client"]
    Client -->|"in-memory fetch (no TCP)"| Host["Embedded OpenCode host"]
    Host --> Session["One OpenCode session"]
    Host -->|"when models.base_url is configured"| Proxy["Loopback compatibility proxy"]
  end
  Proxy --> Provider["Model-provider endpoint"]
  Host -->|"otherwise"| NativeProvider["OpenCode native provider"]
```

When OpenCode reports files changed by an invocation and the runtime has an
artifact root, the adapter writes the combined diff to a runtime- and
invocation-scoped path beneath `opencode/` and returns it as a `patch` artifact.
Without an artifact root, it returns no patch artifact.

Create a new runtime to change the selected model or workspace.