> This page is for NeMo Fabric, version Latest (v0.4.0) (default).
> 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 Qwen Code Adapter

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

Use the `nvidia.fabric.qwen` adapter to run tasks with Qwen Code. Each NVIDIA
NeMo Fabric runtime uses `@qwen-code/sdk` to start one bundled Qwen CLI child
process and reuses one live session across ordered invocations. Qwen Code runs
as a separate process; it is not embedded in the adapter process.

## Install the Adapter

Install Node.js 22.19 or later. Then install the adapter and its exact-pinned,
consumer-managed SDK in the project that owns the NeMo Fabric configuration:

```bash
npm install --save-exact nemo-fabric-adapters-qwen @qwen-code/sdk@0.1.16
```

The SDK is an optional peer and bundles the Qwen CLI. Installing the adapter
alone does not install it. Starting the adapter without the compatible SDK
returns `qwen_sdk_missing`.

For source development, run these commands from the repository root:

```bash
just install-typescript-qwen
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-qwen
```

## Configure the Adapter

Select the Qwen Code integration and point discovery at the installed adapter
descriptor:

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

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

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

## Supported Configuration

The adapter supports the following normalized configuration:

* **Models:** Selects the `default` role, or the only configured role. It maps
  `model`, `api_key_env`, `base_url`, `temperature`, and `top_p` for the
  `openai` provider.
* **Instructions:** Supports `instructions.system` with `mode: replace` or
  `mode: append`.
* **Tools:** Maps Qwen-native tool names from `tools.blocked`. Tool definitions
  and `tools.enabled` are unsupported.
* **Skills:** Each `skills.paths` entry must be a directory containing
  `SKILL.md`.
* **MCP:** Supports stdio and streamable HTTP servers, including per-server
  allowed and blocked tool filters.
* **Harness settings:** Maps `permission_mode` to Qwen Code's `default`, `plan`,
  `auto-edit`, `auto`, or `yolo` approval mode.

### Model Endpoints

The adapter requires `models.<role>.provider: openai`. When `base_url` is set,
it must identify an OpenAI-compatible Chat Completions endpoint. Remote
endpoints require HTTPS, with HTTP allowed for loopback development servers.

The adapter reads the variable named by `api_key_env` from NeMo Fabric
`environment.env` first and then the parent process environment. It does not
write the credential to Qwen settings.

### MCP Configuration

Stdio servers map `url` to the executable and may define `args` and `env`, but
not HTTP headers. Streamable HTTP servers may define `custom_headers`, but not
process arguments or environment variables. Remote MCP endpoints require HTTPS
except for loopback development endpoints.

Header values may reference `${NAME}`. Resolution checks NeMo Fabric
`environment.env` first and then the parent process environment. Unresolved
references fail startup. `allowed_tools` and `blocked_tools` map to Qwen Code's
per-server filters. Normalized MCP authentication is unsupported.

Only explicitly configured server names are enabled. The pinned SDK discovers
external MCP servers on the first prompt and does not include them in
`mcpServerStatus()`. The adapter captures the SDK's MCP startup diagnostic and
returns `qwen_mcp_unavailable` instead of accepting a result produced without
every explicitly configured server.

### Runtime Behavior

The adapter accepts plain-text input and returns the terminal assistant text in
`output.response`. Qwen Code reports cumulative usage for a live query, so the
adapter returns the per-invocation difference. Create a new runtime to change
the selected model, workspace, system instructions, skills, MCP servers, tool
policy, or permission mode.

The adapter gives the child process isolated temporary Qwen home and runtime
directories. It disables Qwen Code's optional product-usage analytics and
telemetry. This does not affect model-provider metering or token usage reported
by NeMo Fabric. The adapter also disables extensions, ambient skills, and
ambient MCP servers. Explicit NeMo Fabric `environment.env` values and the
selected model credential are forwarded to the child process.

In SDK mode, set `harness.settings.permission_mode` to control Qwen Code's
permission policy. The default value, `default`, denies tool calls that need
interactive approval. Use `auto` for Qwen's classifier-mediated policy. Use
`yolo` only inside an appropriate task sandbox because it bypasses edit
approval. Qwen's permission policy is not a filesystem sandbox.

`models.max_tokens`, provider-specific model settings, `runtime.max_turns`,
`tools.enabled`, native streaming, cancellation, service mode, and Relay
telemetry are unsupported.

## Understand the Runtime Lifecycle

The adapter runs as a persistent Node.js process, but the Qwen Code harness does
not run in-process. `start` creates isolated configuration and asks
`@qwen-code/sdk` to launch its bundled Qwen CLI as a child process. The SDK
exchanges JSON-lines messages with the CLI over stdin and stdout. `stop` closes
the live query, terminates the child process, and removes the temporary profile.

```mermaid
flowchart TB
  Fabric["NeMo Fabric runtime"]

  subgraph AdapterProcess["Node.js adapter process"]
    Adapter["Qwen Code adapter"]
    SDK["@qwen-code/sdk client"]
    Adapter --> SDK
  end

  subgraph QwenProcess["Separate Qwen CLI child process"]
    CLI["Bundled Qwen CLI"]
    Session["One live Qwen Code session"]
    CLI --> Session
  end

  Fabric -->|"Adapter contract<br />NDJSON over stdio"| Adapter
  SDK -.->|"Starts, configures, and stops"| CLI
  SDK <-->|"JSON-lines over stdin/stdout"| CLI
  Session -->|"Model requests"| Provider["OpenAI-compatible endpoint"]
  CLI -->|"stdio or streamable HTTP"| MCP["Configured MCP servers"]
```

To try the source adapter, use the
[code-review agent Qwen variant](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.4.0/examples/code_review_agent).