ktx/docs-site/content/docs/guides/llm-configuration.mdx

---
title: LLM configuration
description: Configure ktx LLM providers, model roles, and prompt caching.
---

Configure text generation, structured extraction, and ingest or memory loops in
the top-level `llm` block.

## Backends

Set `llm.provider.backend` to one of these values:

- `anthropic`: Use the Anthropic API through `ANTHROPIC_API_KEY` or the
  configured `api_key` reference.
- `vertex`: Use Vertex AI Anthropic models through Google Cloud credentials.
- `gateway`: Use AI Gateway-compatible Anthropic model ids.
- `claude-code`: Use your local Claude Code session through the Claude Agent
  SDK. **ktx** strips provider-routing environment variables from child processes.
- `codex`: Use your local Codex authentication through the Codex SDK.

## Claude Code

Use aliases or full Claude model IDs in `llm.models`:

```yaml
llm:
  provider:
    backend: claude-code
  models:
    default: sonnet
    triage: haiku
    candidateExtraction: sonnet
    curator: sonnet
    reconcile: sonnet
    repair: sonnet
```

During setup, choose the backend interactively or pass the model in automation:

```bash
ktx setup --llm-backend claude-code --llm-model opus --no-input
```

For Claude Code, `sonnet`, `opus`, and `haiku` map to **ktx** defaults. Full Claude
model IDs are also accepted.

`claude-code` exposes only **ktx** MCP tools for the current agent loop. SDK init
metadata may still list host slash commands, skills, and subagents; **ktx** does not
grant execution access to them.

## Codex backend

Use `codex` when you want **ktx** to run LLM-backed workflows through your
local Codex authentication instead of a direct provider API key.

```yaml
llm:
  provider:
    backend: codex
  models:
    default: gpt-5.3-codex
```

Configure it non-interactively:

```bash
ktx setup --llm-backend codex --llm-model gpt-5.3-codex --no-input
```

This is separate from Codex agent-client setup. `ktx setup --agents --target
codex` installs instructions and MCP access for an end-user Codex session.
`ktx setup --llm-backend codex` makes **ktx** itself execute ingest, scan
enrichment, memory, and other LLM-backed work through Codex.

During runtime loops, **ktx** starts a temporary loopback MCP server for the
current run, exposes only the tools passed to that run, asks Codex to use a
read-only sandbox, sets `approval_policy=never`, auto-approves only those
run-scoped MCP tools, and disables Codex web search.

Codex backend isolation is currently limited by the public Codex SDK and CLI
surface. Codex may still load user Codex config and built-in command execution
or read-only file capabilities. Use `llm.provider.backend: claude-code` when
you need stricter Claude-Code-style runtime tool isolation, or remove host
Codex MCP and tool config before running untrusted prompts through the `codex`
backend.

## Prompt caching

`llm.promptCaching` has partial parity on `claude-code`. Status and doctor warn
when the Claude Agent SDK backend ignores configured cache fields.