Use the Kilo Code Adapter | NVIDIA NeMo Fabric

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:

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:

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:

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:

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

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 for shared behavior and a comparison of native evidence across adapters.