Authenticate the Claude Adapter | NVIDIA NeMo Fabric

The nvidia.fabric.claude adapter uses the Claude Agent SDK and its bundled Claude Code runtime. NeMo Fabric preserves Claude’s native credential precedence and forwards only supported operating-system, configuration, and authentication variables plus values explicitly configured in environment.env or named by environment.env_names.

The adapter package’s harness and full extras pin claude-agent-sdk==0.2.166. Use the same version for an environment-managed SDK. The SDK owns and selects its compatible Claude Code runtime.

Install the Adapter

To install the NeMo Fabric runtime, Claude adapter, and supported Claude Agent SDK in one environment:

pip install "nemo-fabric[claude]"

To install the adapter and supported Claude Agent SDK without the NeMo Fabric runtime, use the adapter package’s harness extra:

pip install "nemo-fabric-adapters-claude[harness]"

The adapter package’s full extra installs the same dependencies as harness; it does not install the NeMo Fabric runtime. Both extras install the supported nemo-relay CLI. Claude does not import the Relay Python API, so this adapter does not provide a separate relay extra.

If the environment already manages a compatible Claude Agent SDK, install only the adapter:

pip install nemo-fabric-adapters-claude

The bare adapter package does not install the NeMo Fabric runtime or SDK.

If the existing compatible Claude Agent SDK and NeMo Fabric runtime share an environment, install the runtime and bare adapter together:

pip install nemo-fabric nemo-fabric-adapters-claude

For separate environments, set ADAPTER_PYTHON in the runtime environment to the adapter environment’s Python interpreter. Use matching NeMo Fabric release versions for the runtime and adapter package unless a different pairing has been explicitly validated.

Configure the Adapter

Select the Claude harness integration in HarnessConfig:

from nemo_fabric import HarnessConfig
harness = HarnessConfig(adapter_id="nvidia.fabric.claude")

Use normalized FabricConfig fields to configure the model, workspace, skills, MCP servers, instructions, turn limit, tool policy, and telemetry. The resolved Claude descriptor accepts only these Claude-specific harness.settings keys:

Claude supports both replace and append system instructions. append preserves the claude_code preset and adds the configured content after it.

permission_mode: default, acceptEdits, bypassPermissions, plan, dontAsk, or auto
reasoning_effort: low, medium, high, xhigh, or max; omit to use the harness default
max_budget_usd: a number greater than 0
max_buffer_size: an integer greater than or equal to 1
setting_sources: an array containing user, project, or local

Planning rejects unknown keys, invalid types, and invalid values before the Claude runtime starts. When permission_mode is dontAsk, tools listed in tools.enabled are pre-approved so headless runs can invoke them. max_buffer_size sets the size limit the Claude Agent SDK applies to one JSON message from Claude Code, such as a large tool result. A message over the limit fails the invocation instead of being truncated.

Choose an Authentication Mode

Use the mode that matches the execution environment:

Mode	Credential Source	Recommended Use
Claude Code login	Cached Claude.ai or Anthropic Console login	Interactive local development
Bearer token	`ANTHROPIC_AUTH_TOKEN`	LLM gateways or proxies that authenticate with an `Authorization: Bearer` header
API key	`ANTHROPIC_API_KEY`	Local development, prototypes, and controlled servers
Workload Identity Federation (WIF)	Anthropic profile or direct federation environment variables	CI, cloud workloads, and Kubernetes without static API keys

Claude Code selects ANTHROPIC_AUTH_TOKEN before ANTHROPIC_API_KEY. Both environment credentials take precedence over WIF and cached login credentials. An empty value still occupies its precedence slot, so unset an unused variable instead of setting it to an empty string.

Claude Code can use a Claude.ai Pro or Max login, an Anthropic Console login, or supported enterprise providers. Refer to the Claude Code authentication documentation for the current subscription and enterprise options.

Authenticate Claude Code outside NeMo Fabric. The adapter inherits HOME and CLAUDE_CONFIG_DIR, so the bundled runtime can reuse the same cached login. NeMo Fabric does not copy the credential store into its configuration or artifacts.

Use an API Key

Set the API key in the process that invokes NeMo Fabric:

export ANTHROPIC_API_KEY=sk-ant-api03-example

The adapter also forwards the selected model’s api_key_env when the model configuration names a different environment variable.

Use a Compatible Custom Provider

Use provider="anthropic" for Claude’s native authentication and endpoint discovery. For another provider name, set both api_key_env and base_url. The configured endpoint must implement the Anthropic Messages protocol. NeMo Fabric maps the named credential and endpoint into Claude Code’s environment; it does not maintain a provider-name allowlist or infer provider endpoints.

Use Workload Identity Federation

For a named WIF profile, set the profile and optional nondefault configuration directory:

export ANTHROPIC_CONFIG_DIR=/etc/anthropic
export ANTHROPIC_PROFILE=production

For direct environment configuration, provide the federation rule, organization, service account, and one identity-token source:

export ANTHROPIC_FEDERATION_RULE_ID=fdrl_example
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_example
export ANTHROPIC_WORKSPACE_ID=wrkspc_example
export ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token

Use ANTHROPIC_IDENTITY_TOKEN instead of ANTHROPIC_IDENTITY_TOKEN_FILE when the platform injects the identity token as an environment variable. Refer to the Anthropic WIF reference for credential precedence, profile structure, required claims, and provider setup.

Unset ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN before using WIF. These variables take precedence over federation even when their value is empty.

Use Authentication with Relay

NeMo Relay does not authenticate Claude. A Relay-enabled NeMo Fabric runtime starts one gateway as a supervised sidecar, sets ANTHROPIC_BASE_URL for the Claude runtime, passes an explicit selected model endpoint to the gateway as its Anthropic upstream, and reuses the gateway across ordered invocations. Fabric.run(...) starts the same runtime, invokes it once, and stops it, so the gateway is scoped to that single invocation. Claude still resolves its credential through the selected mode, and NeMo Fabric does not write authentication values to Relay configuration or artifacts.

Claude PreToolUse hooks set onFailure: "block" to block tool calls when the Relay hook fails to start, crashes, or times out. This requires Claude Code 2.1.295 or later. The pinned claude-agent-sdk==0.2.166 bundles Claude Code 2.1.299.

NeMo Fabric supports the external NeMo Relay CLI in the >=0.9,<0.12 range. NeMo Fabric’s relay extra installs only the Relay Python library and does not install the CLI. NeMo Fabric owns sidecar supervision, Claude configuration, and upstream selection. Relay owns the gateway transport and semantic observability pipeline.

Runtime Health

Fabric.check() supports live, active, and ready. Liveness observes the owned CLI process. Active and ready require a fresh, valid get_mcp_status() response; reported MCP connection failures do not themselves fail readiness.

Refer to the SDK health-check overview for shared behavior and a comparison of native evidence across adapters.

Private HTTP model gateways with Relay

Relay-enabled runs can set harness.settings.insecure_http_model_hosts to an explicit list of hostnames or IP addresses, for example ["inference.internal", "10.0.0.10"]. This requires NeMo Relay CLI 0.11.x. Entries have no scheme, port, path, or wildcard; matching ignores DNS case and a trailing dot and permits any port or path on the listed host. An explicit empty list clears inherited HTTP trust. Omitting the setting preserves existing Relay configuration behavior. System Relay configuration takes precedence and can enforce an empty list.

Use this for unauthenticated inference gateways. Relay strips authorization, API-key, cookie, and other credential headers before remote HTTP forwarding, including credentials provided to the harness, and rejects conflicting upstream authorization configuration. Prompts and responses travel unencrypted. HTTPS remains the default, and MCP policy is unchanged. This option applies to Relay-enabled Codex, Claude, and Pi runs.