> This page is for NeMo Fabric, version v0.6.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.6.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/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.
> 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.

HTTPS is required by default, except for loopback HTTP. For a trusted Docker or Kubernetes gateway, set `harness.settings.insecure_http_model_hosts` to the exact hostnames that can receive HTTP model requests. Entries contain only hostnames or IPv4 addresses, without schemes, ports, paths, or wildcards. Matching ignores case and a trailing DNS dot, and permits any port or path on the listed host. The adapter does not resolve DNS to infer trust. Allowlisted HTTP endpoints receive model credentials and prompt content over an unencrypted connection. This setting applies only to model endpoints; MCP endpoint restrictions are unchanged.

For example, allow the gateway hosts used by your deployment:

```yaml
harness:
  settings:
    insecure_http_model_hosts:
      - host.docker.internal
      - release-nhx-api
      - gateway.namespace.svc.cluster.local
```

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 NeMo Fabric `environment.env` values, variables named by
`environment.env_names`, and the selected model credential. Other variables
inherited by the NeMo 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, NeMo Fabric subagent configuration,
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`. `stop` removes the OpenCode session and closes the embedded host.

For OpenAI-compatible Chat Completions responses, the adapter reports standard input and output counts when it proves ownership and completion of OpenCode-managed model work, including automatic title generation and attributable foreground children. Input includes cache reads, and output includes reasoning; do not add these breakdowns again. Harbor receives the same counts. Ambiguous runs retain partial observations and coverage gaps under `usage.metadata["nvidia.fabric.opencode.usage_evidence.v1"]`, with standard totals left unknown. Provider-reported cost stays unknown. Refer to the [adapter's token usage limits](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.6.0/adapters/typescript/opencode#token-usage) before using these counts in comparisons.

When coverage cannot be proved, the evidence may include `scope_reasons` with bounded reason codes such as `background_shell`, `title_completion_unconfirmed`, or `observer_lost`. These diagnostics contain no native error messages, shell commands, or credentials and do not make partial counters complete.

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

## Runtime Health

`Fabric.check()` supports `live`, `active`, and `ready`. Each level obtains a fresh native `sessions.get({ sessionID })` response and validates the selected unarchived session. Readiness establishes local session availability.

Refer to the [SDK health-check overview](/nemo/fabric/sdk/health-checks) for shared behavior and a comparison of native evidence across adapters.