> 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 Kilo Code Adapter

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

Use the `nvidia.fabric.kilo` adapter to run tasks with Kilo Code. Each NVIDIA
NeMo Fabric runtime starts one isolated `kilo serve` child process and reuses
one Kilo Code session across ordered invocations. Kilo Code runs as a separate
server 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 Kilo Code packages in the project that owns the NeMo Fabric
configuration:

```bash
npm install --save-exact nemo-fabric-adapters-kilo @kilocode/cli@7.7.12 @kilocode/sdk@7.7.12
```

The Kilo CLI and SDK are optional peers. Installing the adapter alone does not
install them. Starting the adapter without the compatible packages returns
`kilo_harness_unavailable`.

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

```bash
just install-typescript-kilo
npm install --prefix adapters/typescript --no-save --package-lock=false @kilocode/cli@7.7.12
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-kilo
```

## Configure the Adapter

Select the Kilo 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="kilo-review"),
    discovery=DiscoveryConfig(
        local_paths=[
            "./node_modules/nemo-fabric-adapters-kilo/kilo.fabric-adapter.json"
        ]
    ),
    harness=HarnessConfig(adapter_id="nvidia.fabric.kilo"),
    models={
        "default": ModelConfig(
            provider="nvidia",
            model="nvidia/nemotron-3-nano-30b-a3b",
            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/kilo/kilo.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
  `provider`, `model`, `api_key_env`, `base_url`, `temperature`, and `top_p`.
* **Instructions:** Supports `instructions.system` with `mode: replace`.
* **Runtime:** Maps a positive `runtime.max_turns` to Kilo Code's build-agent
  step limit.
* **Tools:** Maps native Kilo Code tool names in `tools.enabled` and
  `tools.blocked`. Tool definitions are unsupported.
* **Skills:** Each `skills.paths` entry must be a directory containing
  `SKILL.md`. Startup verifies that Kilo Code loaded every configured skill.
* **MCP:** Supports stdio, streamable HTTP, and SSE server configurations.
  Startup requires every configured server to report `connected`.

### Model Endpoints

When `base_url` is set, it must identify an OpenAI-compatible model-provider
endpoint. It is not the address of the Kilo Code server. Without `base_url`,
the configured provider and model must be supported by Kilo Code.

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 existing `harness.settings.allow_insecure_http_model_endpoint: true` option permits literal IPv4 addresses in `10/8`, `172.16/12`, and `192.168/16`. It does not permit hostnames or other IP ranges unless they are explicitly listed in `insecure_http_model_hosts`. Both settings can be used together.

### MCP Configuration

Remote MCP endpoints require HTTPS except for loopback development endpoints.
They may define headers but not process arguments or environment variables.
Stdio servers may define arguments and environment variables but not headers.

Header values may reference `${NAME}`. Resolution checks NeMo Fabric
`environment.env` first and then the parent process environment. Unresolved
references fail startup. Normalized MCP authentication and per-server tool
filters are unsupported.

### Runtime Behavior

The adapter accepts plain-text input and returns the terminal assistant text in
`output.response`. See [Model Usage](#model-usage) for token counts and cost.
Ordered invocations reuse one warm session and its conversation history. A
prompt has a 30-minute deadline; on timeout the adapter asks Kilo Code to abort
the prompt and reports `kilo_prompt_timeout`.

The adapter disables project Kilo Code configuration and uses temporary Kilo
and XDG directories. The child process receives required operating-system
variables, explicit NeMo Fabric `environment.env` values, variables named by
`environment.env_names`, and the selected model credential. Other parent
variables are not forwarded.

The adapter is non-interactive. When `tools.enabled` is omitted, it allows shell
commands unless `tools.blocked` lists `bash`. It denies follow-up questions,
access outside the workspace, doom-loop continuation, and direct reads of `.env`
files. These permission rules are not a filesystem sandbox and cannot prevent an
enabled shell tool from reading workspace files. Use an environment provider
when the task needs stronger isolation.

`models.max_tokens`, provider-specific model settings, append-mode system
instructions, streaming, cancellation, service mode, and Relay telemetry are
unsupported.

## Model Usage

Each invocation counts Kilo Code's completed model steps linked to its prompt. Input counts include cache reads and writes. Output counts include reasoning. A supplied total is retained separately; the adapter does not invent one by adding other fields. Model calls made inside external tools are outside this measurement.

Kilo Code replaces some missing values with zero and clamps its token calculations at zero. The adapter recovers a count only when that calculation is reversible. A stored zero does not establish reported zero usage.

Complete counts appear in `RunResult.usage` only when the step records and retry events establish their coverage. Child tasks, scheduled work, internal continuation turns, retries, or a lost event connection leave coverage gaps. Failed requests retain available observations. Late records from an earlier prompt do not enter a later invocation.

`RunResult.usage.metadata["nvidia.fabric.kilo.usage_evidence.v1"]` keeps `observed` counts and `gaps`. Observed input and output use the inclusive conventions above. Missing fields remain unknown. A gap means the observations are incomplete, and the observed sum is not a complete total or a guaranteed lower bound. Cache and reasoning breakdowns appear only when their values can be recovered; their absence does not invalidate a known inclusive count.

The adapter leaves provider-reported cost unknown because Kilo Code exposes provider amounts and catalog estimates through the same field. Memory updates can make separate model calls. If memory is enabled or its status cannot be read, complete counts stay unknown for that runtime. Complete counts require the default Kilo runtime. Supplying `KILO_CONFIG` or `KILO_EXPERIMENTAL_NATIVE_LLM` leaves coverage unverified.

## Understand the Runtime Lifecycle

The adapter runs as a persistent Node.js process, but the Kilo Code harness does
not run in-process. `start` launches `kilo serve` as a separate child process on
an available loopback port, connects through `@kilocode/sdk`, and creates one
session. `stop` deletes the session, terminates that server, and removes its
temporary profile.

Kilo Code's `background_process` tool stops session-scoped processes when the session ends, the active session group changes, or the Kilo Code server exits. For a service that must survive runtime shutdown, set `persistent: true` on that tool call. This matters in Harbor, where verification runs after the runtime stops. Persistent processes require separate cleanup; Harbor removes them when it destroys the task container.

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

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

  subgraph KiloProcess["Separate Kilo Code server process"]
    Server["kilo serve<br />loopback only"]
    Session["One warm Kilo Code session"]
    Server --> Session
  end

  Fabric -->|"Adapter contract<br />NDJSON over stdio"| Adapter
  Adapter -.->|"Starts, configures, and stops"| Server
  SDK -->|"HTTP over loopback"| Server
  Session -->|"Model requests"| Provider["Model-provider endpoint"]
  Server -->|"stdio, HTTP, or SSE"| MCP["Configured MCP servers"]
```

Create a new runtime to change the selected model, workspace, skills, MCP
servers, or tool policy.

## Runtime health

`Fabric.check()` supports `live`, `active`, and `ready`. `live` observes the
owned Kilo server process exit and signal status. `active` requests the selected
session through `session.get()` and verifies its native session identifier.
`ready` requires `global.health()` to return `healthy: true`.

These read-only observations use the pinned Kilo SDK request interface and can
run during an invocation. Busy alone does not fail a check. Readiness covers
native local server health; readiness does not promise model access, valid
credentials, or MCP connectivity. Checks never send prompts or abort a turn.
At most one 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.