Skip to content

docs(guides): reach LM Studio and OpenRouter through OpenCode or Pi - #19384

Merged
cruisercohen merged 2 commits into
mainfrom
docs/11568-harness-provider-guide
Oct 12, 2026
Merged

cruisercohen merged 2 commits into
mainfrom
docs/11568-harness-provider-guide

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A user can run Kiro Crew chats on LM Studio (local) or OpenRouter models by following one guide, using the OpenCode or Pi harness Kiro Crew already drives.

There is no Kiro Crew documentation for reaching LM Studio or OpenRouter. Both harnesses already speak to these providers from their own configuration, but nothing tells a user which harness to pick, which harness file to edit, how each harness signs in, or how the chosen model shows up in the composer.

Why it matters

Users asking for local or OpenRouter models currently have no supported path written down, so they reach for forks or direct adapters. The harness route needs no new trust posture: the provider keys stay in each harness's own credential file and Kiro Crew holds none.

Not a goal

  • No Crew-hosted ACP adapter for LM Studio, OpenRouter or DeepSeek, and no new routing member (the issue's other two directions stay open on the issue).
  • No Crew-held provider credentials and no new external service.
  • No change to the model picker or the model list; that work is tracked on its own issue with its own assignee.
  • No product code, config default or harness behaviour change.

What changed (motivation → approach → change)

  • Goal: document the provider path that already works today.
  • Approach: route through the harnesses rather than new adapters, because OpenCode and Pi already reach these providers through routings Kiro Crew has verified, keep their own keys, and add no external dependency to Kiro Crew.
  • Change:
    • New guide docs/guides/lm-studio-and-openrouter.md: install and select the harness (Settings, Agent Harness, or agent.acp_backend), the member DM backend note, LM Studio server start and model id check, the OpenCode opencode.json provider entry and the Pi models.json entry for LM Studio, OpenRouter sign-in through opencode auth login and Pi's /login openrouter, picking the model in the composer, where the credentials live, and a troubleshooting table.
    • Every provider step is taken from the OpenCode, Pi and LM Studio documentation, linked at the top of the guide. Install commands are the ones the dashboard prints for a missing harness. No flag or setting is invented.
    • docs/guides/README.md: index row for the new guide.
    • Second commit: the terminal model checks (pi --list-models, OpenCode's "Provider not found" answer before an OpenRouter key is stored), added after running the harnesses.

Rejected alternatives:

  • Crew-hosted adapters per provider with a new routing member and vault-held keys: rejected for now; Kiro Crew would become the client of third-party model APIs and hold their keys, an extra-large change for a need the harnesses already meet.
  • One generic owned OpenAI-compatible adapter: rejected for now for the same trust-posture reason; it stays the better of the two owned shapes if a no-harness local stack becomes a product goal.

Backwards compatibility

Compatible: documentation only; no code, config or schema changes.

Removes nothing: the diff adds one guide and one index row.

Tests

N/A: documentation only. scripts/docs_lint.py --test and scripts/docs_lint.py pass locally (every internal link resolves, the new guide is indexed). The external links in the guide were checked to answer HTTP 200.

Manual verification

  • Checked each Kiro Crew statement against the current code: the install commands, the harness ids, the member DM backend set, the harness sign-in messages, and the picker's cold-cache behaviour described in the model-selection spec.
  • Checked each provider step against the upstream OpenCode, Pi and LM Studio docs pages linked in the guide.
  • Ran the guide's harness-side config against real harness binaries in throwaway config and data directories (no real credentials):
    • OpenCode 1.18.30 (the version the Real Adapter lane pins): with the guide's LM Studio opencode.json, opencode models lmstudio lists lmstudio/google/gemma-3n-e4b and opencode debug config resolves "model": "lmstudio/google/gemma-3n-e4b". opencode models openrouter answers "Provider not found: openrouter" until a credential is stored, and lists openrouter/... ids once auth.json holds an OpenRouter entry.
    • Pi 1.1.0: with the guide's LM Studio models.json, pi --list-models gemma lists provider lmstudio, model google/gemma-3n-e4b; with the apiKey line removed the model is not listed.
  • Not run against a live LM Studio server or a real OpenRouter key, and not driven through a Kiro Crew chat end to end.

Related Issues

Part of #11568
Related to #10088 (the picker, owned by its assignee)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

A step-by-step guide for running chats on LM Studio (local) or OpenRouter
models through the OpenCode and Pi harnesses Kiro Crew already drives:
installing and selecting the harness, each harness's own provider entry
and sign-in (taken from the OpenCode, Pi and LM Studio docs), picking the
model in the composer, and where the provider credentials live. Kiro Crew
holds no provider key for this setup.

Part of #11568
Related to #10088
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 333e3e1b15c78662d01a77e48083cead48cdc8c0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 333e3e1

Description read

[DESCRIPTION-READ] f9b03540f97e82ca5d062e6921aaf99318b55d793d8078342545c923f4b20070

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 333e3e1b15c78662d01a77e48083cead48cdc8c0 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

The supplied patch also contains the MembersPage, crew-mode spec and RFC hunks from #19346, which is already on base (c4c51aa); check that the PR's own commits touch only the guide.

What this change ships

Inventory (2 items) — 2 justified

Intent: a user can run chats on LM Studio or OpenRouter models by following one guide that uses the OpenCode or Pi harness. This is an ADDITION (docs only).

  1. A new guide, docs/guides/lm-studio-and-openrouter.md, covering how to install and select the harness, each harness's provider entry and sign-in, picking the model in the composer, where the credentials live, and troubleshooting — justified
  2. A new row for that guide in the docs/guides/README.md index — justified

Searching *.md for openrouter|lm ?studio|lmstudio finds only these two files, so no existing guide already covers this. custom-llm-backend.md is the nearest one, and it covers Anthropic-compatible endpoints through the claude harness, which is a different route.

[FIRST-PRINCIPLES-REVIEWED] 333e3e1

Description read

[DESCRIPTION-READ] 9191902f8fd73c7d8f49309b06156e2b0f2c0ed1a8dd4a3c3e6dc827e8030660

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 333e3e1b15c78662d01a77e48083cead48cdc8c0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 333e3e1

Description read

[DESCRIPTION-READ] 99ec21977dfe36fb791fb91fb0882c3b97ea06eba19c5cfcc67e4dee4cf3a30f

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 333e3e1b15c78662d01a77e48083cead48cdc8c0 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 333e3e1

Verdict parsed from the review's SHA-scoped output markers for commit 333e3e1b15c78662d01a77e48083cead48cdc8c0.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 333e3e1b15c78662d01a77e48083cead48cdc8c0: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 333e3e1b15c78662d01a77e48083cead48cdc8c0 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- website/src/pages/members/MembersPage.tsx:3465 -- rememberedMember(...) changes bare /members visits to prefer browser memory over the last-chatted crewmate, contradicting the stated documentation-only scope -> Fix: remove the unrelated Crewmates landing changes and their test/spec/RFC hunks from this PR.
[GPT-REVIEWED] 333e3e1

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 333e3e1b15c78662d01a77e48083cead48cdc8c0: <one-sentence reason>

Add pi --list-models as Pi's terminal check, say that OpenCode lists the openrouter provider only after a key is stored, and cover its 'Provider not found' answer in the troubleshooting table.

Part of #11568
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Re the Design Review note (a human should run the OpenCode LM Studio path end to end): I ran the harness side of the guide against real binaries, in throwaway config and data directories with no real credentials.

  • OpenCode 1.18.30, the version the Real Adapter lane pins: with the guide's LM Studio opencode.json, opencode models lmstudio lists lmstudio/google/gemma-3n-e4b, and opencode debug config resolves the model default. opencode models openrouter answers "Provider not found: openrouter" until a key is stored, and lists openrouter/... ids once one is. The guide now says that order and covers the message in its troubleshooting table.
  • Pi 1.1.0: with the guide's LM Studio models.json, pi --list-models gemma lists provider lmstudio, model google/gemma-3n-e4b. With the apiKey line removed the model is not listed, which is why the guide keeps it.

Not covered here: a live LM Studio server, a real OpenRouter key, and a Kiro Crew chat driven end to end. The PR description's Manual verification section says the same.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Re the First Principles note on 333e3e1: the PR's own commits (51abab8, 333e3e1) touch only docs/guides/README.md and docs/guides/lm-studio-and-openrouter.md, as the PR's file list shows. The MembersPage, crew-mode spec and RFC hunks the lane saw come from main moving under the branch, not from this PR.

@cruisercohen
cruisercohen marked this pull request as ready for review October 12, 2026 11:34
@cruisercohen
cruisercohen requested review from a team and KiroCrewCaptain as code owners October 12, 2026 11:34
@cruisercohen
cruisercohen enabled auto-merge (squash) October 12, 2026 11:34
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 12, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a docs-only guide for running chats on LM Studio or OpenRouter models through the OpenCode or Pi harness, plus one index row. I checked its Kiro Crew claims against the code on this head. The install commands match backends.py (npm i -g opencode-ai) and PI_INSTALL_COMMAND in acp/harness/pi.py. OpenCode is in ACP_BACKENDS_MEMBER_DISPATCH and Pi is not, which matches the member DM note. The "OpenCode is not signed in" / "Pi is not signed in" messages and the credential paths (.local/share/opencode/auth.json, .pi/agent/auth.json) match host_auth.py. The guide adds no product code or credential handling, and it says plainly what was not run end to end. Lanes are PASS and checks are green. — crew-pr-reviewer (deep re-check)

@cruisercohen
cruisercohen merged commit b4025be into main Oct 12, 2026
107 of 114 checks passed
@cruisercohen
cruisercohen deleted the docs/11568-harness-provider-guide branch October 12, 2026 17:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants