Quick Start · Architecture · Troubleshooting · Discussions · Changelog

What is kiroxy?

A single-binary, self-hosted proxy that exposes your Kiro IDE subscription as a standard Anthropic Messages API endpoint. Point Claude Code, Cursor, or any Anthropic-compatible client at kiroxy — it handles credential pooling, token refresh, and request routing transparently.

Why Kiroxy?

⚡ Blazing fast 23,810 req/s on a single core. Zero-copy SSE streaming. No GC pauses in the hot path.	📦 Single binary One go build, one file, done. No runtime, no sidecar, no config server.
🏠 Truly self-hosted Your credentials never leave your machine. Zero telemetry, zero phone-home.	🔄 Drop-in API Standard Anthropic Messages API — existing SDKs and tools work unchanged.

How it compares

	kiroxy	LiteLLM	One-API	OpenRouter
Self-hosted	✅	✅	✅	❌
Single binary	✅	❌	❌	—
Zero dependencies	✅	❌	❌	—
Kiro IDE support	✅	❌	❌	❌
Multi-account pool	✅	❌	✅	—
Memory footprint	~30 MiB	~500 MiB	~200 MiB	—
No telemetry	✅	❌	❌	❌

_{kiroxy is purpose-built for Kiro IDE credentials. For multi-provider routing, use LiteLLM or OpenRouter.}

Quick Start

# Pre-built binary (Linux/macOS, amd64/arm64)
VERSION=1.4.0 OS_ARCH=Darwin_arm64
curl -sSL "https://github.com/nopperabbo/kiroxy/releases/download/v${VERSION}/kiroxy_${VERSION}_${OS_ARCH}.tar.gz" | tar xz
./kiroxy version

# Or via Docker
docker pull ghcr.io/nopperabbo/kiroxy:latest
docker run --rm -p 127.0.0.1:8787:8787 -v kiroxy-data:/data ghcr.io/nopperabbo/kiroxy:latest

# Configure & run
export KIROXY_KIRO_DB_PATH="$HOME/Library/Application Support/kiro-cli/data.sqlite3"
./kiroxy serve
# → kiroxy listening on http://127.0.0.1:8787

# Connect any Anthropic-compatible client
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_AUTH_TOKEN=$(openssl rand -hex 32)
claude  # ← just works

Dashboard

The bundled Mansion dashboard ships in the same binary. Seven views, dark + light themes, mobile-responsive.

Live Request Stream — Real-time SSE feed with drill-down	Metrics — Time-series charts, SLO gauges
Account Pool — Density viz with anomaly emphasis	Logs — Volume histogram, facets, JSONL export

More screenshots

Light Theme — WCAG AA contrast

Mobile — All views adapt to 390px

Architecture

Full component-by-component overview: docs/ARCHITECTURE.md

  Claude Code ─┐   ┌─────────────┐   ┌──────────┐   ┌──────┐
  Cursor       ├──▶│ /v1/messages │──▶│ reqconv  │──▶│ kiro │──▶ Kiro IDE
  any client  ─┘   │ auth · log   │   │ anthropic│   │client│
                    └──────┬───────┘   │ → kiro   │   └──────┘
                           │           └──────────┘       │
                           ▼                              ▼
                    ┌─────────────┐              ┌────────────┐
                    │ pool.Token  │              │  respconv  │
                    │ (LRU+cool) │              │ kiro → SSE │
                    └──────┬──────┘              └─────┬──────┘
                           │                           │
                           ▼                           ▼
                    ┌─────────────┐              your client
                    │ tokenvault  │           (streamed chunks)
                    │ SQLite+OAuth│
                    └─────────────┘

Environment Variables

Variable	Default	Purpose
KIROXY_API_KEY	(empty = open)	Client auth key
KIROXY_BIND	127.0.0.1	Bind interface
KIROXY_PORT	8787	TCP port
KIROXY_DB_PATH	~/.kiroxy/tokens.db	Vault SQLite path
KIROXY_KIRO_DB_PATH	(empty)	Read creds from kiro-cli DB
KIROXY_KIRO_REGION	us-east-1	AWS region
KIROXY_LOG_LEVEL	info	Log level
KIROXY_SHUTDOWN_TIMEOUT	30	Drain timeout (seconds)

API Endpoints

Method	Path	Auth	Purpose
POST	/v1/messages	✓	Anthropic Messages API
POST	/v1/messages/count_tokens	✓	Token count
GET	/healthz	—	Liveness probe
GET	/readyz	✓	Readiness probe
GET	/dashboard-mansion	loopback	Operator dashboard

CLI Reference

kiroxy serve              # Run the proxy
kiroxy add-account        # Register via AWS Builder ID OAuth
kiroxy import-accounts    # Bulk import from triplet file
kiroxy list-accounts      # Show vault accounts
kiroxy remove-account     # Delete an account
kiroxy status             # Pool + request snapshot
kiroxy debug-refresh      # Force token refresh
kiroxy healthcheck        # Docker HEALTHCHECK probe
kiroxy opencode-config    # Emit opencode.json snippet
kiroxy version            # Print version

Docker

docker pull ghcr.io/nopperabbo/kiroxy:latest
docker run --rm \
  -p 127.0.0.1:8787:8787 \
  -v kiroxy-data:/data \
  --read-only --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  -e KIROXY_API_KEY="your-key" \
  ghcr.io/nopperabbo/kiroxy:latest

Control	Setting
Base image	gcr.io/distroless/static-debian12:nonroot
User	nonroot (UID 65532)
Root FS	Read-only
Capabilities	All dropped
Healthcheck	In-binary kiroxy healthcheck

Supply Chain Security

Releases are signed with Sigstore cosign and include SBOM (SPDX format).

cosign verify-blob \
  --certificate kiroxy_1.4.0_Darwin_arm64.tar.gz.cert \
  --signature kiroxy_1.4.0_Darwin_arm64.tar.gz.sig \
  --certificate-identity-regexp "github.com/nopperabbo/kiroxy" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  kiroxy_1.4.0_Darwin_arm64.tar.gz

Troubleshooting

Full diagnostics: docs/TROUBLESHOOTING.md

Symptom	Fix
401 authentication_error	No account added. Set KIROXY_KIRO_DB_PATH or run kiroxy add-account
401 missing_api_key	Client missing X-Api-Key header
SSE chunks arrive all at once	Disable proxy buffering (proxy_buffering off)
go build fails with json/v2	Missing GOEXPERIMENT=jsonv2 — use make build

Contributing

PRs welcome. See CONTRIBUTING.md for guidelines.

make gate       # fmt + vet + build + test
make lint       # golangci-lint (25+ linters)
make test-race  # race detector

License

MIT

---

_{Built with care by @nopperabbo
💛 Sponsor · Report Bug · Discuss}