Oceans LLM Gateway

Rust-first LLM gateway workspace with an embedded TanStack Start admin control plane.

Overview

• crates/gateway
  • Rust HTTP runtime for /healthz, /readyz, /v1/*, and /api/v1/admin/*
• crates/gateway-core
  • shared domain types, traits, OpenAI-compatible Chat/Responses/Embeddings DTOs, and errors
• crates/gateway-mcp
  • protocol-only MCP JSON-RPC, Streamable HTTP discovery, tool normalization, and schema hashing
• crates/gateway-store
  • libsql or SQLite and PostgreSQL stores, migrations, and seed behavior
• crates/gateway-service
  • auth, model resolution, routing, accounting, and request logging
• crates/gateway-providers
  • provider adapters and transport helpers
• crates/admin-ui
  • Rust reverse-proxy integration for /admin*
• crates/admin-ui/web
  • TanStack Start and React admin UI

Quick Start

Install the repo toolchain:

eval "$(mise activate zsh)"
mise install
mise run ui-install

Run the local development stack:

mise run dev-stack

Default local endpoints:

• gateway API: http://localhost:8080
• admin UI: http://localhost:8080/admin
• active config: ./gateway.yaml
• database backend: local libsql or SQLite

On a first mise run dev-stack with no ./gateway.db, the local demo dataset is seeded automatically. Use mise run gateway-reset-local-demo any time you want to recreate that richer sample state from scratch.

Core Commands

• local dev stack:
  • mise run dev-stack
• local gateway:
  • mise run gateway-serve
• local explicit migration:
  • mise run gateway-migrate
• local explicit bootstrap admin:
  • mise run gateway-bootstrap-admin
• local explicit config seed:
  • mise run gateway-seed-config
• request-log retention purge:
  • mise run gateway-purge-request-logs-dry-run
  • mise run gateway-purge-request-logs
  • mise run gateway-purge-request-logs-dry-run-prod
  • mise run gateway-purge-request-logs-prod
• local-only demo dataset seed:
  • mise run gateway-seed-local-demo
• local-only demo dataset reset:
  • mise run gateway-reset-local-demo
• production-shaped local stack:
  • mise run prod-stack
• production-shaped explicit migration:
  • mise run gateway-migrate-prod
• production-shaped explicit bootstrap admin:
  • mise run gateway-bootstrap-admin-prod
• production-shaped explicit config seed:
  • mise run gateway-seed-config-prod
• admin contract generation:
  • mise run admin-contract-generate
• admin contract drift check:
  • mise run admin-contract-check
• full lint:
  • mise run lint
• full test:
  • mise run test
• E2E contract suite:
  • mise run e2e-test

Migration Policy

• Fresh databases apply one active V17 baseline per backend.
• Databases carrying pre-baseline V1 through V16 history must be recreated instead of upgraded in place.
• Use mise run gateway-migrate to apply or inspect the active migration state.

Documentation Map

Use the docs site instead of treating this file as the full admin and maintainer manual.

• repo workflow:
  • Contributing
• docs site:
  • Documentation Home
• startup and first access:
  • Runtime Bootstrap and Access
• config contract:
  • Configuration Reference
• identity:
  • Identity and Access
• gateway API keys and service-account-style callers:
  • Admin Control Plane
• budgets:
  • Budgets
• routing:
  • Model Routing and API Behavior
• provider API compatibility:
  • Provider API Compatibility
• cross-cutting request flow:
  • Request Lifecycle and Failure Modes
• pricing and spend:
  • Pricing Catalog and Accounting
  • Budgets and Spending
• observability:
  • Observability and Request Logs
  • MCP Registry and Discovery
• admin UI:
  • Admin Control Plane
• maintainer-facing docs source notes:
  • Documentation Source Notes
• deploy quick start:
  • Deploy
• Kubernetes and Helm:
  • Kubernetes and Helm
  • Helm Chart

Same-Origin Runtime Model

The product runs as a same-origin control plane:

1. the gateway listens on the configured bind address
2. the admin UI SSR process runs separately
3. the gateway reverse-proxies /admin* to the admin UI upstream

This is part of the product contract, not only a local-dev trick.

Admin Contract Generation

The live admin control plane ships checked-in contract artifacts:

• gateway OpenAPI artifact:
  • crates/gateway/openapi/admin-api.json
• generated admin UI types:
  • crates/admin-ui/web/src/generated/admin-api.ts

Regenerate them with:

mise run admin-contract-generate

Verify drift with:

mise run admin-contract-check

For the full maintainer workflow, use Admin API Contract Workflow.