kiroxy Architecture

This document is a living reference for how kiroxy is put together. It complements BUILD_LOG.md (which is the chronological construction log) and NOTICE (which carries the per-file licence attribution).

Last reviewed: Phase I (2026-05-12). Expect drift after each phase; update as packages change shape.

Overview

kiroxy is a single-user, self-hosted proxy that exposes an operator's Kiro IDE subscription (Amazon Q Developer / AWS CodeWhisperer upstream) as an Anthropic Messages API endpoint. Clients that speak the Anthropic protocol — opencode, Claude Code, Cursor, raw curl — point at kiroxy instead of api.anthropic.com; kiroxy rewrites each request into the CodeWhisperer protocol, forwards it upstream, and rewrites the streaming response back into Anthropic SSE.

What kiroxy is

A personal proxy. Single operator, 1–N accounts, one binary, one SQLite file, no external infrastructure.
An Anthropic-compatible edge. Streaming, non-streaming, tool use, vision, thinking blocks, tool_search, count_tokens — all of it speaks the Anthropic wire format.
A translator. Every request/response crosses the Anthropic↔CodeWhisperer boundary through internal/reqconv and internal/respconv.
A multi-account pool with cooldowns, generation-locked OAuth refresh, and a per-request selection policy.

What kiroxy is NOT

Not a production hosting layer. No tenancy, no rate-limiting per-key beyond loopback trust, no TLS termination. Put Caddy or nginx in front if you expose it beyond localhost.
Not an account manager. Onboarding lives in a separate Python sidecar under tools/onboard/ (Phase G). The Go binary does not ship a browser.
Not an inference engine. kiroxy forwards; Kiro decides the model.

High-level data flow

                    +---------------------+
                    |  opencode / Claude  |
                    |  Code / curl / SDK  |
                    +---------+-----------+
                              |
                  Anthropic Messages API (HTTP/JSON)
                              |
                   +----------v----------+
                   |       kiroxy        |
                   |  (this repo)        |
                   +----------+----------+
                              |
           AWS SigV4-less bearer-token JSON-RPC
           (X-Amz-Target: ...GenerateAssistantResponse)
                              |
                 +------------v------------+
                 | Kiro CodeWhisperer API  |
                 |  codewhisperer.us-east- |
                 |  1.amazonaws.com        |
                 +-------------------------+

The choice of upstream host (codewhisperer.* vs q.*) is decided by whether the account has a profileArn — see the Kiro client section.

Components

Every package in internal/ is listed below with its purpose, key types, and provenance. The Attribution line maps to NOTICE.

`internal/server` — HTTP surface

Purpose. Wire the HTTP mux, middleware stack, and route handlers; serve the dashboard; expose health endpoints.

Key types.

server.Options, server.Server — constructor-style wiring from cmd/kiroxy/main.go.
Middleware: auth.go (SHA-256 constant-time inbound-key check), logging.go (per-request ULID, JSON slog logger, X-Request-Id).
Routes:
- GET /healthz — liveness (bypass auth).
- GET /readyz — readiness with per-dep subchecks (readiness.go).
- POST /v1/messages — Anthropic handler (internal/messages).
- POST /v1/messages/count_tokens — token counting.
- GET /dashboard + GET /dashboard/api/state — HTML + JSON snapshot.

Attribution. Original to kiroxy.

`internal/auth` — credential sourcing

Purpose. Read credentials from the configured source (managed vault OR kiro-cli SQLite DB) and produce auth.Credentials ready for the Kiro client.

Key types.

Credentials — {AccessToken, RefreshToken, ExpiresAt, ProfileARN, AuthMethod, ClientID, ClientSecret}.
RefreshFn — callback invoked when ExpiresAt <= now.
refresh.go — Builder ID device-code refresh (auth_method="builderid").
refresh_social.go — Desktop-flow refresh (auth_method="social").

Attribution. Derived from kirocc; refresh paths kept structurally identical so bug fixes upstream can be ported. See NOTICE for commit SHA.

`internal/tokenvault` — SQLite credential store

Purpose. Persist OAuth bundles at rest; mediate safe concurrent refresh across goroutines and processes using the generation-lock pattern.

Key types.

Vault — SQLite handle, opened at KIROXY_DB_PATH.
Bundle — {Provider, ConnectionID, AccessToken, RefreshToken, ExpiresAt, Metadata, Generation}.
Generation-locked refresh: ReserveRefresh() captures generation, CommitRefresh() rejects if generation moved, ReleaseRefresh() rolls back a reservation.

Design decisions.

SQLite not Postgres — single user, zero external deps, self-healing schema migration on Open().
Mode 0600 enforced on Open() — vault at rest should be user-private.
modernc.org/sqlite — pure Go driver, no cgo, no libc surface area.
IMMEDIATE transactions — every mutation runs in an IMMEDIATE tx so the DB lock is acquired up front, eliminating the "upgrade from read to write" SQLITE_BUSY pathology.

Attribution. Ported from kadangkesel/hexos (MIT); generation-lock pattern preserved literally. See NOTICE.

`internal/pool` — account selection

Purpose. Pick an account for each outbound request using an LRU policy; cooldown accounts that return upstream errors; mark accounts failed after 3 consecutive errors.

Key types.

Pool — {accounts []Account, cooldownUntil map[string]time.Time, strikes map[string]int}.
Pick(ctx) (Account, error) — returns ErrNoAccount if nothing is usable.
TokenGetter — adapter that the Kiro client uses; reads the current access token from the vault, triggering refresh on expiry.

Design decisions.

LRU not round-robin — even in a multi-account deployment the workload is typically one-user-at-a-time, so LRU just means "spread load evenly". Donor project was weighted RR.
Cooldowns track recency, strikes track repeat failures. An account returning a 5xx once enters a short cooldown; 3 in a row marks it failed and it drops out of the pool until re-enabled.
profileArn threads from vault metadata into auth.Credentials (closed in v0.2.2).

Attribution. Derived from Quorinex/Kiro-Go (MIT); selection policy swapped to LRU.

`internal/kiroclient` — upstream HTTP

Purpose. Make HTTP calls to the Kiro CodeWhisperer API; parse the event stream; surface AWS-style errors in a Go-typed shape.

Key types.

HTTPClient — {http.Client, region, optional TokenRefresher}.
GenerateAssistantResponse(ctx, creds, body) (*Response, error) — the single upstream entry point.
aws_error.go — typed AWSError with Kind, Message, RequestID.
X-Amz-Target selection: chooseAmzTarget switches to the AmazonQ target when ProfileARN is empty (Builder ID path) and to the CodeWhisperer target otherwise (Desktop-flow path).