Models & providers

Use Connect a model for setup. This reference explains wires, model routes, effort, context limits, and cost.

provider selects the wire family, wire_api selects Chat or Responses, base_url selects the endpoint, and model selects its model. The spelling anthropic means Messages compatibility; it does not require an Anthropic account. Configuration owns precedence.

Your ChatGPT subscription

Use /login chatgpt or kin login chatgpt, then complete sign-in with your own account. Kin discovers subscription models and selects the main connection; explicit assignments for other jobs remain. On a remote host use:

kin login chatgpt --device-auth

Browser login instead requires a callback to localhost:1455. Device login may require enabling device-code authentication in the account’s security settings.

This connection runs Kin directly against OpenAI with subscription usage and limits. It needs no API key or other coding agent, creates no API balance, and cannot fall back to paid API billing. Its endpoint and headers are fixed. kin login chatgpt status checks local state; kin logout chatgpt removes Kin’s sign-in locally without remote revocation or signing other apps out.

The ChatGPT choices in /model are GPT-6 Astra, GPT-6 Sol, and GPT-6 Luna, limited to the models your account reports as available. They appear even when another provider is active. The Kinra Gateway connection and its default are unchanged.

Older ChatGPT models are no longer offered for new selections. Existing conversations keep their model and history; saved configurations and job assignments are not silently rewritten. Choose an available GPT-6 model when you want to replace an older selection. Favorites preserve connection identity; remove an unavailable favorite with f and favorite its replacement under ChatGPT. Discovery failure reports its reason and preserves saved sign-in.

Effort uses account metadata intersected with the supported request vocabulary. For Astra: low, medium, high, xhigh, max; ultra is a catalog orchestration label, not a valid request effort. Exact unpinned gpt-6-astra sends and displays medium before its first request. Explicit applied effort wins; raw reasoning_effort = "inherit" sends no field and survives resume. This default applies only to that exact subscription model.

Unknown discovery preserves the medium fallback and saved intent. Confirmed unsupported effort is rejected for the active backend; empty journal resets are not durable, so an older choice may be retried on later resume. Display follows the new backend’s actual request after a switch.

OpenAI owns generation length. Sampling and a small max_tokens cannot set a remote cap. Kin reserves input headroom (5% by default); a larger max_tokens increases only the local reserve.

Astra workflow guidance

Exact gpt-6-astra selects maintained guidance for following through, useful planning/delegation, and precise verification. File count alone does not require a child or plan. New children use their own model’s guidance; existing children keep their launch context. This adds no permission, effort setting, or approval.

Current Kinra-hosted contract

Use /login for browser enrollment. If a Console-issued credential is needed:

kin connect kinra-api --base-url https://api.kinra.ai/v1 --refresh-profile

Kin prompts for a new key privately, or retains the existing matching key on profile refresh. The short form derives Responses, the default primary, kinra-vision, and Vision/Utility assignments from the service catalog. Hosted migration covers earlier explicit configurations.

default and vision are stable public profiles, not frozen model versions. Discovery advertises current limits, capabilities, application roles, and service defaults. Responses report the concrete model that ran. Consult live discovery for those values; fleet appointments remain with the Gateway/Ops owner.

Managed refresh advances only values Kin last wrote; divergent values are operator pins. A managed route that is missing altogether is put back by the next refresh, and so is a managed Vision or Utility assignment while Kinra is the active provider. Deleting one therefore does not stick: to opt out, point the job at a route of your own. A Kinra connection installed beside another active provider leaves unassigned jobs alone. The official row adopts the advertised service effort (currently xhigh), while Vision uses inherit. An absent supported level leaves Main on inherit. Explicit /effort, connection pins/clears, and KIN_REASONING_EFFORT take precedence. Offline refresh retains last-known-good settings; older managed caches can refresh before their ordinary twelve-hour TTL.

recommended_max_output_tokens is a default, not a server ceiling. Kin adopts it only while local output is unpinned and it fits every hard boundary. A typed response.incomplete still means truncated; HTTP 200 does not establish completion.

Kin labels isolated requests with the advertised application role, allowing Vision and Utility to use different service defaults. The label names only a placement Kin resolved: an assigned route, the Utility binding, or a model you named. An unassigned inspection that falls back to Main carries no role. Role metadata is not an assignment or permission grant. task live-models is the maintainer proof for these profiles; direct DS4, vLLM, and llama.cpp configurations are separate compatibility targets, not current fleet appointments.

Chat, Responses, and Messages

API	Selection	Use
Chat Completions	provider = "openai", wire_api = "chat"	Broad compatibility default.
Responses	wire_api = "responses"	Explicit typed-stream/replay support at a qualified endpoint.
Messages	provider = "anthropic"	Official Anthropic or a compatible service.

Public wire_api accepts only chat or responses; either implies OpenAI. messages is an internal discriminator, not a public wire setting. Unknown values and contradictory provider/wire choices fail configuration.

kin --wire-api responses --base-url http://localhost:8000/v1 --model MODEL_ID

Kin’s Responses subset uses HTTP/SSE, typed terminal items, functions, structured output, supported images, and local replay. Same-endpoint history preserves returned phase and encrypted reasoning. It sends store=false and does not use remote Conversations, previous_response_id, server compaction, background responses, WebSocket continuation, or hosted tools. Endpoint/wire changes convert neutral history and discard nonportable ids and encrypted data. Kin retains journal, compaction, tools, and permission ownership.

Messages preserves provider-native thinking signatures for compatible replay. Each endpoint owns accepted reasoning controls. Unknown usage remains unknown; it does not turn an otherwise complete response into failure.

The KIN_BASE_URL heuristic

With base_url set and both provider and wire unset, Kin selects Messages. Set KIN_PROVIDER=openai for Chat Completions or KIN_WIRE_API=responses for Responses. An explicit choice always wins. With no endpoint or identity selection, Chat remains the default.

base_url handling

Use the conventional /v1 base. Kin keeps it for OpenAI-compatible APIs and trims that suffix before the Messages adapter appends /v1/messages:

http://model-host:8000/v1 → Chat base:     http://model-host:8000/v1
                         → Messages base: http://model-host:8000

Model routes

/models separates Jobs, Connections, and Routes (j, c, r). Assign jobs to existing compatible routes or create one. /providers opens Connections; /routes opens route assignments. Test a connection with t (p is an alias).

Forms stage changes with Ctrl+S. Save & apply validates the whole graph, checks for conflicting edits, saves once, and installs a prepared live snapshot. Escape discards a draft after confirmation when needed. Orphaned keys can be removed with Delete or reclaimed by a connection with the same id; kin doctor also reports them.

A route names an existing provider and model, never a URL or key. Routes and assignments are global-only. For example:

[model_routes.primary]
provider_preset = "anthropic"
model = "your-text-model-id"
vision = false

[model_routes.visual]
provider_preset = "openai"
model = "your-vision-model-id"
vision = true

[model_assignments]
mca = "primary"
vision = "visual"
task = "primary"
utility = "visual"

[model_assignments.profiles]
researcher = "primary"

Create credentials through Connections. Custom endpoints use [[providers]] rows whose ids can be reused by routes. Built-in direct presets use vendor endpoints and do not inherit an unrelated ambient local KIN_BASE_URL.

Qwen / llama.cpp bounded thinking

This explicit route profile uses budgets, not semantic low/high levels:

[model_routes.direct-qwen-vision]
provider_preset = "direct-qwen"
model = "qwen3.5-9b"
vision = true
reasoning_profile = "qwen-llamacpp"
effort = "thinking-512"
max_tokens = 1024

Choices are default, off, and thinking-128/512/1024/2048. Default sends no Qwen controls; off disables thinking; a budget sends enable_thinking=true and the qualified gateway’s reasoning_budget_tokens. It is never inferred from names and does not substitute upstream thinking_budget_tokens. Total output must exceed the reasoning budget; Utility needs another 512 tokens. Isolated media/Utility do not enable preserve_thinking.

Resolution and model authority

Delegated calls resolve profile assignment → task assignment → allowed requested route → legacy per-call model → parent backend. route and model are exclusive, and invalid selections fail visibly. Only routes marked selectable_for = ["task"] can be model-requested. Forks keep the exact parent backend. Model-visible routing lists contain no endpoints or keys.

The utility job (housekeeping side-calls)

Utility handles bounded auto-titles on an explicitly assigned route. It is assignment-only, skips busy idle windows, and never retries on Main when the route fails; the first-message title remains. Visible titles keep their short output bound. The model cannot select Utility as a task route. A conversation hosted for a local client titles itself only when Utility is assigned.

Hosted Kinra inference may advertise its own stable utility model. When it does, kin login adopts it as a separate kinra-utility route and assigns Utility there, so housekeeping stops sharing the vision endpoint’s single admission slot; when it does not, Utility keeps riding kinra-vision. Either way an operator pin on those rows survives every refresh, and kin logout refuses while a managed route carries changes of your own.

Vision routing and manual overrides

vision=true/false overrides missing or incorrect discovery. Unknown support can be attempted and cached for the loaded catalog; /reload resets discovery. An @image call sends only the question and image to the Vision route, without root instructions, tools, or history. The returned observation is attributed and framed as untrusted evidence.

Without an assignment, Kin may use Main only when it is not explicitly text-only. An unavailable route produces a configuration hint. When an inspection fails, Kin states its own reading outside the framed provider text: no route is assigned to Vision, with [model_assignments].vision, kin connect --vision-route or the /models hub as the remedy, or the service refused vision placement for the route you assigned. Automatic attachments preserve the text turn with a failure notice. Multiple images use sequential isolated requests in order, with failures identified. Tool images remain in canonical history; text-only wires receive stable refs for inspect_media, without rewriting that history.

Sessions, reloads, budgets, and concurrency

Resume reconstructs saved non-secret backend identity. Reload prepares the complete catalog atomically for the root and future children; existing children retain their snapshot. Routed model, vision, compaction, and structured-output attempts follow shared budget/admission rules. Isolated requests do not replace the active conversation’s context reading. Route permits cover model I/O only, so a child can delegate without a lease held through its tools.

OpenAI endpoints and the Responses API

For a custom Responses connection, set provider="openai" and wire_api="responses". An endpoint-local reasoning_effort supplies the row default; KIN_REASONING_EFFORT overrides it for one launch. Setting effort also requests reasoning summaries. Kin’s stream watchdog measures silence, not total turn duration: ten minutes by default, adjustable with KIN_STREAM_STALL_TIMEOUT.

vLLM wire behavior

Choose the API the server exposes explicitly. Kin does not select behavior from server-version or model-name guesses. The local maintainer gate can qualify text, reasoning, functions, replay, resume, and usage; vision needs its own declared capability.

Kin refines implicit context limits from the matching /v1/models entry, or an unambiguous single-model listing. Explicit context pins win; failed discovery keeps conservative limits. Shared context constrains input plus output reserve; input-only limits independently constrain the prompt. Automatic limits are re-probed on resume.

Responses exact counting runs only with proven capability or the official OpenAI endpoint. Unsupported counting remains unavailable; Kin uses ordinary admission/recovery rather than claiming an exact client-tokenizer estimate. Messages sampling stays server-side.

llama.cpp-compatible Responses endpoints

A Chat-compatible endpoint does not by itself establish Responses support. Use an explicitly qualified connection:

[[providers]]
id = "local-llamacpp"
provider = "openai"
wire_api = "responses"
base_url = "http://model-host:8080/v1"
model = "laguna-s-2.1"

Qualify typed text/reasoning, strict functions, structured output, stable call ids, local replay/resume, terminal usage, and advertised counting before relying on them. The text-only profile does not imply hosted response storage or tools. An empty encrypted-reasoning placeholder may be replayable at that endpoint; a non-empty hosted envelope is not portable.

Laguna S 2.1 on vLLM

Laguna’s Messages behavior is selected with the explicit Poolside profile:

[[providers]]
id = "laguna"
label = "Laguna S 2.1"
provider = "anthropic"
base_url = "http://model-host:8000/v1"
model = "default"
reasoning_profile = "poolside"

/effort max/off controls enable_thinking; Kin omits Anthropic-native effort fields for this profile. Compaction and forced structured output disable thinking. The profile is text-only; separate Vision can inspect images. Choose context/output reserves to match the serve, remembering that output reservation reduces prompt headroom.

task live-laguna qualifies the adapter without real tool dispatch. KIN_LAGUNA_REQUIRE_SIGNED_REASONING=1 requires an observed signed block. Server installation and hardware tuning belong to the model’s deployment notes.

The default alias pattern

Use model="default" only when the server defines that alias. Kin sends it unchanged and separately displays observed model identity from discovery or completed responses. A hosted/local alias is not a valid model selector at arbitrary direct provider endpoints.

Swapping at runtime

/model opens the cross-provider picker; /model MODEL_ID selects directly. Use arrows/Enter, f for favorites, and Escape to cancel. Missing credentials open a masked prompt; cancelling keeps the active backend. /models manages connection keys and headers through its staged transaction.

Key precedence is explicit caller key → active provider’s saved key → matching environment → shared key. Direct OpenAI uses OPENAI_API_KEY then KIN_API_KEY; direct Anthropic uses ANTHROPIC_API_KEY then KIN_API_KEY. Custom/compatibility presets retain their documented broader fallback chain. Provider-specific stored keys prevent an unrelated environment key from winning.

Sessions save identity, never credentials. Resume reattaches the current key only to its matching saved connection; a changed custom URL cannot send the new key to an old endpoint. Cross-wire/provider switches convert history and drop endpoint-private replay data. See Sessions.

Sampling

Setting	Environment	Request effect
temperature	KIN_TEMPERATURE	Sampling temperature.
top_p	KIN_TOP_P	Nucleus sampling.
top_k	KIN_TOP_K	Compatible endpoint extension.
enable_thinking	KIN_ENABLE_THINKING	Supported chat-template thinking control.

Sampling is sent on OpenAI-compatible APIs only when the endpoint supports it; subscription ChatGPT ignores it. Messages sampling is server-owned. The Poolside profile explicitly supports its thinking control over Messages.

Priority-scheduling passthrough (vLLM)

request_priority / KIN_REQUEST_PRIORITY passes an integer through a qualified OpenAI-compatible priority endpoint. Lower values run earlier. Keep it unset unless the server is configured for priority scheduling; nonzero values can be rejected otherwise. Messages and the hosted Kinra contract do not promise this extension. The run token budget remains provider-independent.

Strict decoding (schema-valid tool calls)

Strict decoding asks the server to constrain tool arguments to JSON Schema. Set strict_tools=true / KIN_STRICT_TOOLS=1 for the supported automatic OpenAI-compatible tool path. Endpoint and call shape determine enforcement; compatibility alone does not prove a grammar guarantee.

Kin normalizes a copy of compatible schemas, closing objects and representing optional fields as required nullable values. A schema that cannot be normalized losslessly is sent without strict enforcement. Messages does not send the OpenAI strict field; qualified forced-tool paths may still constrain output.

Client validation always remains. Malformed or invalid arguments return a bounded error before review/execution, and structured outputs are checked against the requested schema. Server decoding never grants authority.

Cost display

Use /cost on, pricing_enabled=true, or KIN_PRICING=1 for estimated USD costs. It is off by default. /cost reports state and /cost off disables and clears accumulation. Rates come from Kin’s local pricing table, not a live billing feed; unknown models show no price rather than a false zero.

Accuracy boundary (cache-write approximation)

Usage merges cache-creation input with ordinary input, so the estimate charges it at the input rate and can undercount providers’ cache-write surcharges. Subscription usage is not an API invoice.

Edge cases

Provider swaps reset the running total and retain the earlier value in a note. Resume starts a new usage counter; it does not reconstruct prior request spend from journal message size. See /tokens for the accounting distinction.

Effort picker

/effort opens the active backend’s choices; /effort LEVEL changes after confirmation. The vocabulary is endpoint-specific:

Active backend	Vocabulary	Wire knob
AnthropicBackend (real Anthropic, vLLM Anthropic serve)	low / medium / high / xhigh / max	output_config.effort
AnthropicBackend against the MiniMax preset	adaptive / enabled / disabled	thinking.type (M2.x silently ignores disabled)
AnthropicBackend against the Z.ai preset	max / high / low	output_config.effort for the GLM-5.3 family (max is Z.ai’s provider default)
AnthropicBackend with the Poolside profile	max / off	extra_body.chat_template_kwargs.enable_thinking
OpenAIBackend against OpenAI / OpenRouter	low / medium / high	top-level reasoning_effort
OpenAIBackend against Z.ai OpenAI-compat	auto / max / xhigh / high / medium / low / minimal / none	top-level reasoning_effort
ChatGPTBackend subscription	Account model metadata intersected with the supported request vocabulary; Astra offers low / medium / high / xhigh / max	reasoning.effort; exact unpinned Astra defaults to medium
OpenAIResponsesBackend against a custom Responses endpoint (wire_api = "responses")	max / xhigh / high / medium / low / minimal / none (pass-through; the serve owns which levels it accepts)	reasoning: {"effort": ..., "summary": "auto"}
OpenAIBackend against a vLLM OpenAI-compat serve (Qwen-style, Chat wire)	auto / on / off	extra_body.chat_template_kwargs.enable_thinking (auto = unset)

A blank effective value shows a disabled (default) row, not a reset button. Raw inherit leaves policy to the service and is not a selectable effort level. Supported explicit choices survive replacement/refresh; pending incompatible intent must not label the active request. Changes can invalidate prefix caches. Only human controls or an approved supported settings proposal change effort.

First-party presets

Use /providers or kin --preset NAME for curated provider defaults. The provider catalog owns tiers, models, authentication, and provider-specific caveats.

Preset selection is CLI --preset > nonempty KIN_PRESET > selected provider_preset file default. The winning id must resolve: an unknown id or invalid custom row is a configuration error (exit 1), never a fallback to another provider. A valid higher-priority choice ignores an invalid lower one. An explicit blank CLI id or whitespace-only selected id is invalid; an empty environment/file default remains unset.

Current built-ins take precedence over same-id custom rows. For custom ids, the first case-insensitive matching row must be valid; a later duplicate does not rescue it. Unrelated malformed rows do not change the chosen preset. Existing MCA assignments still outrank an ambient file default, and saved conversations retain their frozen endpoint. A custom row’s id does not certify its URL: valid URL-less custom rows retain their ambient URL behavior, and an explicit URL override still wins.