> This page is for NeMo Fabric, version Latest (v0.6.0) (default).
> 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 Factory Droid Adapter

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

Use the NVIDIA NeMo Fabric `nvidia.fabric.droid` adapter to run Factory Droid
through its supported TypeScript SDK while retaining conversation context for
the lifetime of a NeMo Fabric runtime.

## Install Droid, the SDK, and the Adapter

The adapter requires Node.js 22.19.0 or newer. Install the supported caller-owned
Droid CLI, SDK, and adapter:

```bash
npm install --global droid@0.233.0
npm install --save-exact @factory/droid-sdk@0.9.1
npm install nemo-fabric-adapters-droid
```

The adapter never installs Droid at runtime. A missing SDK produces
`droid_harness_unavailable`, and a missing CLI produces
`droid_cli_unavailable`.

For source development in the NeMo Fabric repository, run:

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

## Configure the Adapter

Select the Droid adapter and point discovery at its installed descriptor:

```python
from nemo_fabric import DiscoveryConfig, FabricConfig, HarnessConfig
from nemo_fabric import InstructionConfig, InstructionsConfig
from nemo_fabric import MetadataConfig, ModelConfig, ToolsConfig

config = FabricConfig(
    metadata=MetadataConfig(name="droid-review"),
    discovery=DiscoveryConfig(
        local_paths=[
            "./node_modules/nemo-fabric-adapters-droid/droid.fabric-adapter.json"
        ]
    ),
    harness=HarnessConfig(adapter_id="nvidia.fabric.droid"),
    models={
        "default": ModelConfig(
            provider="factory",
            model="auto",
            api_key_env="FACTORY_API_KEY",
        )
    },
    instructions=InstructionsConfig(
        system=InstructionConfig(
            content="Review code for correctness risks.",
            mode="append",
        )
    ),
    tools=ToolsConfig(enabled=["Read", "Grep", "Glob"]),
)
config.add_skill_path("./skills/code-review")
```

For a source build, use
`adapters/typescript/droid/droid.fabric-adapter.json`. Set the environment
variable named by `api_key_env` before starting the runtime.

Start one runtime and reuse it for ordered turns:

```python
from nemo_fabric import Fabric

async with await Fabric().start_runtime(config) as runtime:
    first = await runtime.invoke(input="Review the authentication changes.")
    second = await runtime.invoke(input="Now summarize the highest-risk finding.")
```

The second invocation uses the conversation retained by the Droid session.

## Understand Configuration Mapping

The initial adapter selects a model resolved by Droid and passes the
credential named by `api_key_env` to the SDK as the Factory API key. It does
not map `models.base_url` or arbitrary providers because custom model endpoints
are configured through external Droid settings, not the SDK session API.

System instructions support both modes. `replace` replaces Droid's default
system prompt. `append` preserves the native Droid prompt and appends the
configured content.

Tool policy names are Droid built-in tool IDs. The adapter lists the tools
available to the created session, rejects unknown IDs, and translates
`tools.enabled` into an exact allowlist by disabling every unselected tool.
It then applies `tools.blocked`. Inspect tool IDs with:

```bash
droid exec --model MODEL_ID --list-tools --output-format json
```

Tool policy limits Droid's available tools; it is not a host sandbox. Use an
isolated task environment when enabling tools that edit files or execute
commands.

## Configure MCP Servers

Normalized MCP servers are supplied directly to the runtime-scoped Droid
session. The adapter supports unauthenticated stdio, SSE, and
streamable HTTP servers. Stdio servers accept `args` and `env`, but not HTTP
headers. Network servers accept `custom_headers`, but not process arguments or
environment variables. Remote network endpoints require HTTPS; loopback HTTP
is allowed for development.

Normalized MCP authentication, `allowed_tools`, and `blocked_tools` are not
supported and fail during startup. Each configured server must expose at least
one tool so the adapter can verify session-scoped discovery before invocation.
The Droid process and its stdio MCP children inherit safe operating-system
variables, Fabric `environment.env`, the selected model credential, and each
server's explicit `env`; unrelated variables from the adapter host are removed.

## Configure Skills

The adapter supports normalized `skills.paths`. It validates each configured
directory and its `SKILL.md`, copies the skill into a runtime-scoped temporary
home using Droid's compatible personal `.agents/skills` layout, and verifies
discovery through the SDK. Runtime shutdown removes the temporary files.
Project skills already placed in Droid's documented discovery locations remain
Droid-owned ambient configuration.

When an isolated profile is required for MCP servers or skills, the adapter
copies the user's Factory `settings.json` and `settings.local.json` into it so
externally configured custom models remain available. Fabric supplies MCP
servers directly to the Droid session; ambient MCP configuration and Factory
authentication state are not copied.

## Optional: Use a Custom BYOK Model

The default configuration uses Droid's `auto` model selection and a Factory
API key. Use the following optional configuration only when Droid must call a
custom model endpoint through BYOK. The configuration below uses an
NVIDIA-hosted model as one example.

Define the model in `~/.factory/settings.json` or
`~/.factory/settings.local.json`. The settings entry uses the model's
unprefixed provider ID. Set `apiKey` to an exact environment-variable reference
such as `${NVIDIA_API_KEY}`. The variable name is the existing credential for
the configured provider; the adapter forwards only that referenced variable
when the custom model is selected. This NVIDIA configuration is one example:

```json
{
  "cloudSessionSync": false,
  "customModels": [
    {
      "model": "nvidia/nemotron-3-super-120b-a12b",
      "displayName": "NVIDIA Nemotron 3 Super",
      "baseUrl": "https://integrate.api.nvidia.com/v1",
      "apiKey": "${NVIDIA_API_KEY}",
      "provider": "generic-chat-completion-api"
    }
  ]
}
```

Select the model through Fabric with Droid's `custom:` prefix. The Factory SDK
credential and the external model-provider credential are separate. For local
BYOK, set `FACTORY_API_KEY=EMPTY`. In this example, the adapter forwards
`NVIDIA_API_KEY` because the selected custom model explicitly references it in
Droid settings; unrelated ambient credentials remain isolated:

```python
from nemo_fabric import ModelConfig

config.models = {
    "default": ModelConfig(
        provider="factory",
        model="custom:nvidia/nemotron-3-super-120b-a12b",
        api_key_env="FACTORY_API_KEY",
    )
}
```

Export both variables before starting Fabric:

```bash
export FACTORY_API_KEY=EMPTY
export NVIDIA_API_KEY=nvapi-...
```

## Understand Runtime Behavior

Each NeMo Fabric runtime creates an isolated `DroidSession`. Every ordered
invocation streams one prompt through the same session, and runtime shutdown
closes the session and its CLI subprocess. Independent runtimes do not share
session history.

Successful results include normalized response text and token usage. Usage
extensions preserve cache, thinking-token, and Factory-credit metadata.
Result extensions preserve the Droid session ID, finish reason, duration, and
turn count.

The initial adapter does not support NeMo Relay telemetry, native NeMo Fabric
streaming, Relay-backed streaming, custom model endpoints, or adapter-specific
`harness.settings`.

## Runtime health

`Fabric.check()` supports `live`. The adapter sends a fresh native
`DroidSession.listTools()` request. A successful SDK response establishes that
the selected Droid subprocess responds; a retained SDK handle is insufficient.
A failed request returns unknown health and does not close the session.

`active` and `ready` are unsupported. A busy invocation
can remain live. Checks do not send prompts, validate model credentials, or
change tool policy. At most one uncancellable native health request remains
outstanding after a caller timeout.

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