Skip to content

Developer Onboarding

Quick Start

1. Prerequisites

  • [ ] Go toolchain matching go.mod installed (go version)
  • [ ] Repository access granted
  • [ ] (Optional) Docker for container builds; Helm + kubectl for cluster deploys
  • [ ] Upstream credentials for local testing (e.g. ANTHROPIC_API_KEY)

2. Setup

# Clone and fetch dependencies
git clone https://github.com/inferplane/inferplane.git
cd inferplane
go mod download

# Build the static binary
CGO_ENABLED=0 go build -trimpath -o bin/mayu ./cmd/mayu

3. Verify

go test ./... -race      # full suite, race detector
go vet ./...             # static checks
gofmt -l .               # must print nothing

For a running gateway, use the first-request guide. It prepares writable state, reads credentials without shell-history values, and uses one config for key issuance and serving. Database integration tests require both INFERPLANE_TEST_PG_DSN and KEYSTORE_TEST_POSTGRES_DSN pointing to the same disposable test service; a skipped database suite is not a passing qualification.

Project Overview

  • Read CLAUDE.md for project context and conventions.
  • Read docs/architecture.md for the current system design (source of truth).
  • Read docs/specs/2026-06-10-inferplane-gateway-design.md for the original v0.1 design rationale (historical).
  • Browse docs/reference/INDEX.md for per-layer implementation detail.
  • Review docs/decisions/ for architectural decisions.

Development Workflow

  • Branch naming: feat/, fix/, docs/, refactor/, chore/.
  • Commit convention: Conventional Commits, DCO signed off (git commit -s). This adds a Signed-off-by trailer; cryptographic signing uses git commit -S and is separate. Sign-off is required by project policy; the repository's workflows currently contain no DCO enforcement job.
  • Provider PRs touch only providers/<name>/, the blank-import line in cmd/mayu/main.go, and provider docs — zero core diff (design §8).
  • Run go test ./... -race and bash tests/run-all.sh before submitting.

Key Concepts

  • Virtual key (ik_...) -- the client credential; SHA-256 hashed at rest, shown once.
  • Canonical schema -- Anthropic-superset used for cross-protocol conversion.
  • Verbatim forwarding -- byte-for-byte body passthrough when protocols match (cache safety).
  • Two-phase governance -- PreCheck before billing, Settle after.
  • Tamper-evident audit -- per-instance SHA-256 hash chain, offline-verifiable.

Troubleshooting

  • 401 from the gateway: the virtual key is wrong/revoked, or the admin token is missing for /admin/keys.
  • count_tokens must always return 200 — a non-200 crashes Claude Code; never change that contract.
  • Cache hit rate dropped: a conversion path is corrupting cache_control; confirm verbatim forwarding on the matching-protocol path.
  • Audit verify reports a break: confirm you are verifying per-instance segments, not one continuous chain across restarts.

Resources

  • Architecture: docs/architecture.md
  • Historical design doc: docs/specs/2026-06-10-inferplane-gateway-design.md
  • Grafana dashboard: deploy/grafana/inferplane.json
  • Helm chart: charts/inferplane