Update an existing Kinra hosted connection

Use this one-time migration when Kin was connected with an early command from console.kinra.ai. It moves the saved connection from concrete runtime names to the stable default and vision service roles without replacing a saved API key.

On a current Kin build, the simpler replacement is /login: browser sign-in issues a per-device key and adopts the same stable profile with last-known-good refresh. An SSH host can use the fixed-port local-forward recipe in Connect a model and first run. Keep the command below when that tunnel is unavailable or for an intentionally retained Console-issued credential.

Before you start

Run the migration on the tester’s machine and user account. Kin stores this connection globally for that user, not in an individual project.

Record the installed version, then check for the migration capability:

kin --version
kin connect --help | grep -- --refresh-profile

The initial v0.3.11 release predates this option, but the option alone is not a sufficient readiness check either: some intermediate development builds can refresh the stable routes without labeling Vision and Utility calls for the service. Do not migrate with one of those builds.

If the option is absent, update and check again:

kin update
kin connect --help | grep -- --refresh-profile

For an authorized Git-backed dev install, kin update ends with the version and source identity, for example checkout updated — kin 0.3.12 @ …. Continue only with tested checkpoint 349ae96 or a descendant. The operator can prove an exact checkout with:

git -C /path/to/kin merge-base --is-ancestor 349ae96 HEAD

Exit status zero means the checkpoint is present. For an immutable wheel, continue only with a release newer than v0.3.11 whose release notes include the hosted Vision/Utility application-role contract. If neither condition is true, stop and ask the Kin operator for the current authorized build; do not replace the connection manually to work around an older client.

Do not delete the old connection or put the API key on the command line. The refresh is designed to retain the existing credential.

Run the migration

Prefer the current Connect Kin command shown by console.kinra.ai. On a current Kin build, the standard hosted connection is the catalog-driven short form — everything else is derived from the live service catalog and the connection joins the ongoing background profile refresh:

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

An older build (or a console still rendering the long form) spells the same values out explicitly; both shapes converge on the same saved configuration:

kin connect kinra-api \
  --base-url https://api.kinra.ai/v1 \
  --wire-api responses \
  --model default \
  --refresh-profile \
  --reasoning-effort inherit \
  --label "Kinra hosted inference" \
  --vision-route kinra-vision \
  --vision-model vision \
  --vision-description "Kinra hosted vision" \
  --vision-max-tokens 1024 \
  --vision-reasoning-profile inherit \
  --utility-route kinra-vision

The refresh makes one atomic settings change:

• the primary model becomes the stable default role;
• the kinra-vision route becomes the stable vision role;
• Vision and Utility work use that route;
• Main stores a service-managed reasoning sentinel that masks obsolete broad or connection-local pins, while the obsolete Vision route pin is removed; and
• an existing ready credential for kinra-api is retained.

Running the same command again is safe. Once current, it is a settings and credential no-op.

This profile refresh cannot widen the saved credential’s immutable audience. If it was issued before hosted web retrieval became available, it remains inference-only; use /logout followed by /login (or deliberately replace the Console credential) to receive the separately advertised hosted-web capability. See Web tools.

Confirm the result

Launch Kin and open /models:

kin

Confirm these values:

• Main connection: Kinra hosted inference, model default;
• Vision route: kinra-vision, model vision;
• Vision job: kinra-vision;
• Utility job: kinra-vision.

The service-qualified vision profile is text-capable and keeps Utility auto-titles and image work off the main chat model. Kin labels each Responses side-call with its application role, letting the service retain image reasoning for Vision while keeping the bounded Utility path non-thinking.

Send a normal test message. A successful response confirms that the retained credential and updated primary route work. An image test can separately confirm the vision route when needed.

If it does not migrate

• --refresh-profile is unrecognized, or the build predates 349ae96: this client is not qualified for the complete migration. Run kin update, recheck the source identity and help output, and use a current authorized dev build or qualifying newer release before changing the connection.
• Kin asks for an API key: no ready credential was found under the kinra-api provider id. Paste the tester’s existing key into the masked prompt; never add it as a shell argument or to a project settings file.
• Kin reports an endpoint, wire, or route conflict: nothing was changed. Open /models and inspect the existing connection. The automatic migration intentionally refuses a different endpoint, a non-Responses wire, another provider’s route, or an arbitrary main-model replacement.
• The command was already run: run it again. An already-current profile is deliberately a no-op.

For the complete command behavior, see kin connect. For the stable hosted API roles, see Models & providers.