Repository navigation
docs: add guide for custom Anthropic-compatible LLM endpoints - #8657
Conversation
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed Review detailsOne advisory finding: the new guide states background-worker routing as "any non-kiro harness", which is false for the FINDING — docs/guides/custom-llm-backend.md:47 — "they run on the provider-backed path for any non-kiro harness" is false for two baseline-selectable backends: [OPUS-REVIEWED] d31454f |
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Passthrough pin forbids the mechanism (scrub-list growth) instead of requiring the outcome, foreclosing the fix for the token leak the guide itself documents. WatchThe spec now says "the spawn scrub list must not grow to cover either namespace," and the test pins [DESIGN-REVIEWED] d31454f |
7efef71 to
3daa557
Compare
|
Rebased onto main Conflicts: clean rebase, no conflicts. One fix the rebase required: both links to Gates run locally: Please review the link repoint. A maintainer push makes the maintainer the last pusher, so under this repo's last-push rule a second approver is needed. Reply here if anything looks wrong. |
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days with failing CI. I've assessed the blockers and they appear resolvable — I'll push fixes directly to this branch as a co-author. Assessment: Both blocking lanes name the same single defect. The §5 MCP bullet in If you'd prefer I don't touch this PR, add the |
3daa557 to
4855dab
Compare
|
Intent: Give operators a guide for running Kiro Crew's agent against a self-owned Anthropic-compatible endpoint (DeepSeek, a self-hosted gateway) via the |
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca] — drive-to-green changes at 4855dab (branch rebased onto current main):
Original guide by th3l4ughingm4n, preserved as commit author. Local gates green (docs lint, related tests, both local review lanes). |
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]
|
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]
|
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]
|
|
span=b1a940ee005f
|
|
span=b1a940ee005f
|
|
span=b1a940ee005f
|
|
span=b1a940ee005f
|
b566414 to
d93a705
Compare
|
self-added: no
|
|
self-added: yes
|
|
self-added: no
|
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the external recipe claims — npm package name, What this change shipsInventory (5 items) — 5 justifiedIntent: Let an operator run the publicly selectable
Checks run: both scrub lists on base carry no [FIRST-PRINCIPLES-REVIEWED] d31454f |
Document running the agent on the claude harness against the operator's own endpoint (DeepSeek, self-hosted gateways): the acp_backend switch, the claude-agent-acp and claude CLI prerequisites, ANTHROPIC_* environment routing on each launch path, model resolution, and the boundaries that stay on the Kiro account. Original guide written by th3l4ughingm4n; review fixes applied by Kiro Crew (per-spawn MCP seeding wording aligned with claude-code-provider.md, launchctl secret-exposure note, guides index rebase). Co-Authored-By: Claude Code <noreply@anthropic.com> Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
d93a705 to
d31454f
Compare
|
self-added: yes
|
|
self-added: yes
|
bolichen97
left a comment
There was a problem hiding this comment.
Approving after an automated readiness screen against this head:
readiness: passedlabel present and thePR Readinessrequired status is green on this head- no failing, cancelled or pending required check on this head
mergeablewith no conflict against currentmain- no live reviewer
CHANGES_REQUESTED(GitHubreviewDecisionis notCHANGES_REQUESTED) - every review-lane finding on this head is either PASS, withdrawn, disposed of by the author, or advisory-only — no unresolved blocking change request
Auto-merge (squash) is enabled; branch protection still gates the merge.
Problem / Motivation
The
claudeharness is publicly selectable (ACP_BACKEND_CLAUDEis inBASELINE_SELECTABLE_BACKENDS, andacp/client.pyowns its full spawn path),but the operator path to actually run a session against a non-Anthropic
endpoint — DeepSeek, a self-hosted gateway, any Anthropic-compatible API —
exists only in code comments and
docs/system-specs/modules/claude-code-provider.md. A user who wants it hasto reverse-engineer which binaries the harness needs, which environment
variables route the request, and where those variables must live for each way
the gateway is launched. The public docs still describe model requests as
following kiro-cli's account alone.
Why it matters
Operators with their own endpoint cannot use the harness today without reading
the source. The launch-path gotchas are the expensive part to get wrong: a
macOS GUI launch never reads a shell profile, so the standard
exportrecipesilently does nothing and the session falls back to the wrong credentials.
Documenting the flow turns a selectable harness into an actually usable one for
the public build.
What changed
Goal: one task-oriented guide for running the agent on the operator's own
Anthropic-compatible endpoint via the
claudeharness, with the securityboundaries stated exactly as the owning spec states them — and the env
passthrough that auth depends on pinned by a test, not just prose.
docs/guides/custom-llm-backend.md(new)docs/system-specs/modules/claude-code-provider.mdANTHROPIC_*/CLAUDE_CODE_*to the harness child, so the spawn scrub list must not grow to cover themsrc/kiro_crew/sandbox.pytest/test_sandbox_argv.pyANTHROPIC_*/CLAUDE_CODE_*keys, andscrub_agent_subprocess_envpasses them through — a hardening edit that breaks custom-endpoint auth fails red instead of shipping greendocs/guides/README.mdThe guide covers: the
agent.acp_backend: "claude"switch and itsdegrade-to-kiro safety net; the
claude-agent-acpnpm package andclaudeCLI prerequisites, with the dashboard's backend probe as the live check; and
endpoint routing (
ANTHROPIC_BASE_URL,ANTHROPIC_MODEL,CLAUDE_CODE_SUBAGENT_MODEL) on each launch path, including thelaunchctl setenvrecipe for the macOS desktop app and its exposure note.Credential delivery is two-path. The recommended path is Claude Code's own
apiKeyHelperin~/.claude/settings.json: the helper's output is sent as theauth headers and refreshed on
CLAUDE_CODE_API_KEY_HELPER_TTL_MS, which keepsthe raw token out of the ambient environment that every agent-run child
inherits. The guide also states what this does not protect: code running as the
same user can still reach the helper and its store, and the helper itself runs
inside Crew's subprocess sandbox — which hides the home directories the common
secret stores read from, so a helper shelling out to
passor a cloud-CLIsecrets manager comes back empty in the default sandbox. The guide steers the
reader to a source that survives (the macOS keychain, or a store kept outside
the home directory) and defers the exact masked-directory set to
_STANDARD_DIRSinsandbox.pyand the spec. The fallback isANTHROPIC_AUTH_TOKENin the gateway environment, kept working but carryingthe plain warning that every agent-run child inherits it and a prompt-injected
command can read it. The guide notes the MCP secrets vault cannot deliver this
token, since it injects only into bound MCP server environments.
The account-boundary sections are written as non-exhaustive statements rather
than enumerated exceptions: chat and worker model turns go to the operator's
endpoint, while agent-internal and background paths can stay on the kiro-cli
sign-in (crew-member DM threads follow
agent.member_acp_backend). The MCPsection keeps the security kernel — Crew authors the session's settings seed;
tool calls pre-approved in the operator's own
~/.claudesettings bypassCrew's approval gate and audit log; a governed registry-mode install may
withhold spec-referenced servers — and defers finer mount rules to the linked
spec section.
Tests
test/test_sandbox_argv.py::TestAgentEnvPassthroughContractlocks in thespec's must-not-grow clause: for five representative
ANTHROPIC_*/CLAUDE_CODE_*keys, no_SENSITIVE_ENV_PREFIXESprefix matches, no_AGENT_DENIED_ENV_KEYSprefix matches, andscrub_agent_subprocess_envreturns them unchanged. Prefix semantics are asserted (both lists match by
startswith), so a prefix entry like"ANTHROPIC_"cannot slip past anequality check. The full module passes (219 passed, 4 skipped). The
src/kiro_crew/sandbox.pychange itself is comment-only (no value or logicchange).
Manual verification
scripts/docs-lint.shpasses (indexes and internal links verified; the newguide's relative links resolve).
Related Issues
N/A — none.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)TestAgentEnvPassthroughContract; docs-lint and flake8 pass)