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 & runexport 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 clientexport 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}