LLM Connections

LLM Connections let you add multiple AI provider configurations and switch between them. Each session locks to a specific connection after the first message, and workspaces can define their own default connection.

Location

LLM connections are stored in:

~/.craft-agent/config.json

How Connections Are Used

Connections resolve in this order:

1. Session connection (locked after first message)
2. Workspace default connection (defaults.defaultLlmConnection)
3. Global default connection (defaultLlmConnection)
4. First connection in the list (fallback)

Note

Each session locks to a connection after the first message. To change connections, start a new session.

Connection Schema

{
  "slug": "anthropic-api",
  "name": "Anthropic (API Key)",
  "providerType": "anthropic",
  "authType": "api_key",
  "baseUrl": "https://api.anthropic.com",
  "defaultModel": "claude-sonnet-5",
  "createdAt": 1737451800000
}

Fields

Field	Required	Description
slug	Yes	URL-safe identifier (e.g., anthropic-api, codex)
name	Yes	Display name shown in the UI
providerType	Yes	Provider backend (see list below)
authType	Yes	Auth mechanism (see list below)
baseUrl	No	Custom base URL for compatible providers
models	No	Explicit model list. Accepts strings ("gpt-5.4") or objects with optional contextWindow and supportsImages overrides (see Custom Endpoint Capabilities).
customEndpoint	No	Custom endpoint protocol config. Use api to select the wire format and optional supportsImages to opt an entire endpoint into image input.
midStreamBehavior	No	How mid-stream user sends are handled ("steer" or "queue"). Defaults to "queue" for anthropic, "steer" for Pi-backed providers. See Mid-stream behavior.
defaultModel	No	Default model for this connection
codexPath	No	Path to Codex binary (OpenAI/Codex only)
awsRegion	No	AWS region for Bedrock
gcpProjectId	No	GCP project for Vertex
gcpRegion	No	GCP region for Vertex
createdAt	Yes	Timestamp (ms) when created
lastUsedAt	No	Timestamp (ms) when last used

providerType Values

Value	Description
anthropic	Direct Anthropic API
anthropic_compat	Anthropic‑compatible endpoints (OpenRouter, Vercel AI Gateway, custom)
openai	OpenAI via Codex app‑server
openai_compat	OpenAI‑compatible endpoints
bedrock	AWS Bedrock
vertex	Google Vertex AI

authType Values

Value	Description
api_key	API key only
api_key_with_endpoint	API key + custom endpoint
oauth	OAuth login (Claude Max / Codex / OpenAI)
iam_credentials	AWS IAM credentials (Bedrock)
service_account_file	GCP service account JSON (Vertex)
environment	Uses environment variables
none	No auth required

Examples

Anthropic (API Key)

{
  "slug": "anthropic-api",
  "name": "Anthropic (API Key)",
  "providerType": "anthropic",
  "authType": "api_key",
  "defaultModel": "claude-sonnet-5",
  "createdAt": 1737451800000
}

Claude Max (OAuth)

{
  "slug": "claude-max",
  "name": "Claude Max",
  "providerType": "anthropic",
  "authType": "oauth",
  "defaultModel": "claude-opus-4-8",
  "createdAt": 1737451800000
}

Note

claude-opus-4-8 is the current default Opus model. claude-opus-4-7 and claude-opus-4-6 (claude-opus-4-6, 200K context) remain selectable as previous generations. Existing connections pinned to Opus 4.7 are upgraded to Opus 4.8 on launch; Opus 4.5 selections migrate to the best available Opus model, and Opus 4.6 selections are left as-is. On direct Anthropic connections that list Opus 4.7 or 4.8, Craft Agents also appends Opus 4.6 once so it shows up in the model picker; if you deliberately remove it after that, it stays removed.

Note

Claude Fable 5 (claude-fable-5) is selectable on the Claude Agent SDK path alongside Opus and Sonnet — Anthropic’s most capable widely released model, with a 1M-token context window. It’s available on direct Anthropic connections and on AWS Bedrock (us/eu/global inference profiles). Opus 4.8 remains the default; pick Fable 5 explicitly in the model picker (or set defaultModel: "claude-fable-5" on the connection) when you want it. Fable 5 runs with adaptive thinking always on — the “off” and minimize-thinking options map to low-effort adaptive thinking for this model and for Mythos 5; Opus, Sonnet, and Haiku are unchanged. Claude Sonnet 5 (claude-sonnet-5) is the current default Sonnet-class model, with a 1M-token context window and the best combination of speed and intelligence for everyday tasks. It’s available on direct Anthropic connections and on AWS Bedrock (us/eu/global inference profiles). claude-sonnet-4-6 remains selectable as the previous Sonnet generation. Opus 4.8 is still the app-wide default; pick Sonnet 5 in the model picker (or set defaultModel: "claude-sonnet-5" on the connection) when you want speed over depth. Toggling thinking off works normally on Sonnet 5.

OpenRouter (Anthropic‑compatible)

{
  "slug": "openrouter",
  "name": "OpenRouter",
  "providerType": "anthropic_compat",
  "authType": "api_key_with_endpoint",
  "baseUrl": "https://openrouter.ai/api",
  "models": [
    "anthropic/claude-opus-4.8",
    "anthropic/claude-haiku-4.5"
  ],
  "defaultModel": "anthropic/claude-opus-4.8",
  "createdAt": 1737451800000
}

OpenRouter (OpenAI‑compatible)

{
  "slug": "openrouter-openai",
  "name": "OpenRouter (OpenAI‑compat)",
  "providerType": "openai_compat",
  "authType": "api_key_with_endpoint",
  "baseUrl": "https://openrouter.ai/api/v1",
  "models": [
    "openai/gpt-5.2-codex",
    "openai/gpt-5.1-codex-mini"
  ],
  "defaultModel": "openai/gpt-5.2-codex",
  "createdAt": 1737451800000
}

AWS Bedrock (IAM Credentials)

{
  "slug": "bedrock",
  "name": "AWS Bedrock",
  "providerType": "bedrock",
  "authType": "iam_credentials",
  "awsRegion": "us-east-1",
  "defaultModel": "claude-sonnet-5",
  "createdAt": 1737451800000
}

With iam_credentials, your AWS Access Key ID, Secret Access Key, and optional Session Token are stored securely and injected into the subprocess environment at runtime. Use this when you want to configure credentials directly in the UI.

AWS Bedrock (Environment)

{
  "slug": "bedrock",
  "name": "AWS Bedrock",
  "providerType": "bedrock",
  "authType": "environment",
  "awsRegion": "us-east-1",
  "defaultModel": "claude-sonnet-5",
  "createdAt": 1737451800000
}

With environment, the subprocess inherits your shell’s AWS credential chain — ~/.aws/credentials, AWS_PROFILE, IAM roles, SSO sessions, and environment variables all work. No credentials are stored in Craft Agents.

Tip

To set up Bedrock in the UI: Settings → AI → Add Connection → I use other provider → Amazon Bedrock. You can choose between IAM Credentials and Environment (AWS CLI) authentication.

Set awsRegion to the region where you have Bedrock model access enabled (e.g., us-east-1, us-west-2, eu-west-1).

Codex / OpenAI (OAuth)

{
  "slug": "codex",
  "name": "OpenAI (Codex)",
  "providerType": "openai",
  "authType": "oauth",
  "codexPath": "/Applications/Craft Agents.app/Contents/Resources/vendor/codex/darwin-arm64/codex",
  "defaultModel": "codex-mini-latest",
  "createdAt": 1737451800000
}

Custom Endpoint Capabilities

Custom endpoints default to a 128K context window and text-only input. If your model supports a larger context window or accepts image input, set those capabilities explicitly in the connection config.

Tip

For toggling per-model image support specifically, the chat input model picker now exposes an inline image icon on each row of a custom-endpoint connection — one click flips models[i].supportsImages and persists. See API Providers → Image Input for Custom Endpoints. The JSON forms below remain useful for automation and for setting customEndpoint.supportsImages (the endpoint-wide default), which has no UI surface.

Per-model overrides (recommended)

Use model objects when an endpoint hosts a mix of text-only and multimodal models:

{
  "slug": "ollama",
  "name": "Ollama",
  "providerType": "pi_compat",
  "authType": "none",
  "baseUrl": "http://localhost:11434/v1",
  "customEndpoint": { "api": "openai-completions" },
  "models": [
    { "id": "gemma4", "contextWindow": 262144, "supportsImages": true },
    { "id": "qwen3-coder", "contextWindow": 131072 }
  ],
  "defaultModel": "gemma4",
  "createdAt": 1737451800000
}

Whole-endpoint opt-in

If every model behind the endpoint is multimodal, you can opt in at the endpoint level:

{
  "customEndpoint": {
    "api": "openai-completions",
    "supportsImages": true
  }
}

Note

Craft Agents does not auto-detect image support for arbitrary endpoints. Custom endpoints stay text-only unless you explicitly set supportsImages: true at the endpoint or model level. Plain string model entries continue to use the default 128K context window and text-only input.

Tip

For models like Gemma 4 served through Ollama, vLLM, or another OpenAI-compatible proxy, prefer the per-model form so only the vision-capable model opts into image input.

Mid-stream Behavior

When you send a message while the agent is still streaming a previous turn, Craft Agents needs to decide whether to deliver it into the in-flight turn or hold it for the next one. The midStreamBehavior field on the connection controls this.

Value	Behavior
"steer"	Deliver the message into the in-flight turn (Pi’s native .steer() or Claude’s PreToolUse hook injection).
"queue"	Hold the message; let the current turn finish naturally; replay as a new turn afterwards.

{
  "slug": "anthropic-api",
  "providerType": "anthropic",
  "authType": "api_key",
  "midStreamBehavior": "queue",
  "createdAt": 1737451800000
}

Defaults by backend

If midStreamBehavior is omitted (legacy connections, fresh setups), the default depends on the backend:

• anthropic → "queue". Claude’s emulated steer relies on the model invoking a tool before the turn ends. If no tool fires, the steer becomes undelivered and Craft Agents falls back to a re-queue anyway — with the original turn’s tokens already paid. Defaulting to queue avoids the wasted round-trip.
• pi / pi_compat → "steer". Pi’s native steer is non-destructive: your message is delivered after the current tool finishes, full conversation context preserved.

Changing it from the UI

Open Settings → AI, scroll to the Connections section, click the … menu on the relevant connection (or right-click the row), and choose Mid-stream sends → Steer immediately or Queue until ready. The selection is saved on the connection and takes effect immediately for the next mid-stream send.

Note

This is a per-connection setting, not per-session. Two sessions sharing the same connection will both use the same mode.

For the user-facing concept and UI walkthrough, see Interactions → Sending while the agent is responding.

Managing Connections

Connections are managed in Settings → AI:

• Add/edit/delete connections
• Set a global default connection
• Validate connection status
• Set per‑workspace defaults

Tip

If you only need a single provider, keep one connection and set it as default.