Das Kaeso-Gateway, eine Rust-Binary zwischen Ihren Apps und Ihren Anbietern. Es prüft jeden Schlüssel und jedes Limit, übersetzt jedes Format und protokolliert jede Anfrage.

Kaeso selbst hosten Den Ablauf einer Anfrage lesen

Schritt 1 von 8

Schlüssel

Der API-Schlüssel bestimmt das Projekt und das Mitglied oder Dienstkonto, für das er handelt. Schlüssel werden nur als Hashes gespeichert und 30 Sekunden lang aus dem Arbeitsspeicher beantwortet.

Was die App erhalten kann

401Nicht autorisiertDer Schlüssel fehlt, ist unbekannt, deaktiviert, archiviert oder abgelaufen.
403VerbotenDer Schlüssel hat nur Plattformzugriff, oder seinem Mitglied fehlt das Recht api.request.
429Ratenlimit erreichtVon derselben Adresse kamen zu viele Anfragen mit unbekannten Schlüsseln.

Das Gateway liest den Schlüssel aus x-api-key oder sonst aus Authorization: Bearer:

x-api-key: sk-kso-…Authorization: Bearer sk-kso-…

Schritt 2 von 8

Dekodieren

KPP dekodiert den Body aus dem Format der App in Kaesos kanonisches Format. Alles, was Kaeso nie an einen Anbieter sendet, wird hier abgelehnt.

Was die App erhalten kann

413Zu großDer Body ist größer als 8 MiB, das Standardlimit.
400Ungültige AnfrageKaeso kann die Anfrage nicht lesen, oder sie verlangt etwas, das Kaeso nie sendet, etwa mehr als eine Auswahl.
503Nicht verfügbarLaufende Übersetzungen belegen ihren Speicher, und die Anfrage hat 10 Sekunden gewartet.

Beide Limits sind Einstellungen; das sind ihre Standardwerte:

[body_limits]model_api = "8MiB"in_flight = "512MiB"

Schritt 3 von 8

Modell

Der Name wird im Katalog des Projekts aufgelöst, und die Anfrage wird mit den Fähigkeiten des Modells abgeglichen, bevor etwas gesendet wird.

Was die App erhalten kann

404Nicht gefundenDas Modell ist nicht im Katalog des Projekts, oder der Schlüssel darf es nicht nutzen. Beides wird gleich beantwortet, damit ein Schlüssel nicht erfährt, welche anderen Modelle es gibt.
400Ungültige AnfrageMehrere Anbieter stellen die ID bereit, oder dem Modell fehlt etwas, das die Anfrage braucht, etwa Tools oder Bilder.

Derselbe 404 in jedem Format, damit jedes SDK seinen gewohnten Fehler auslöst:

{  "error": {    "message": "The model `gpt-9` does not exist or this key may not use it.",    "type": "invalid_request_error",    "param": "model",    "code": null  }}

Schritt 4 von 8

Limits

Jede Rate und jedes Budget des Schlüssels, des Mitglieds und des Projekts wird in einem Schritt in Valkey geprüft. Über einem Limit erhält die App 429 mit Retry-After.

Was die App erhalten kann

429Ratenlimit erreichtEine Rate oder ein hartes Budget ist erreicht. Retry-After sagt, wann ein neuer Versuch möglich ist.
200OKEin weiches Budget ist überschritten. Die Anfrage läuft weiter, und das Budget meldet nur.
503Nicht verfügbarValkey ist nicht erreichbar, und die Anfrage fällt unter ein hartes Budget.

Retry-After nennt die Wartezeit in ganzen Sekunden, aufgerundet, und retry-after-ms die genaue:

HTTP/1.1 429 Too Many Requestsretry-after: 13retry-after-ms: 12400kaeso-request-id: req_…

Schritt 5 von 8

Anbieter-Schlüssel

Der Schlüssel des Projekts für den Anbieter wird gewählt, entschlüsselt und höchstens 30 Sekunden nur im Arbeitsspeicher gehalten.

Was die App erhalten kann

400Ungültige AnfrageDas Projekt hat keinen Anbieter-Schlüssel für den Anbieter des Modells.
500ServerfehlerKaeso kann den Anbieter-Schlüssel nicht entschlüsseln.

Hauptschlüssel erzeugt das Gateway selbst, und rewrap verschlüsselt jedes gespeicherte Geheimnis mit dem aktiven neu:

docker compose exec gateway kaeso master-key generatedocker compose exec gateway kaeso master-key rewrap

Schritt 6 von 8

Kodieren und senden

KPP kodiert die Anfrage für das Format des Anbieters. Was dieses Format nicht ausdrücken kann, wird abgelehnt, bevor es den Anbieter erreicht.

Was die App erhalten kann

400Ungültige AnfrageDas Format des Anbieters kann nicht ausdrücken, was die Anfrage verlangt.
502Bad GatewayDer Anbieter ist nicht erreichbar, oder er hat den Anbieter-Schlüssel des Projekts abgelehnt.
504Gateway-TimeoutDer Anbieter hat nicht rechtzeitig geantwortet.

Lehnt der Anbieter den Schlüssel des Projekts ab, bekommt Ihre App einen 502, der nach einem Admin fragt, nie den 401 des Anbieters:

{  "type": "error",  "error": {    "type": "api_error",    "message": "The provider refused this project's provider key. Ask an organization admin to check it under Providers."  },  "request_id": "req_…"}

Schritt 7 von 8

Antwort

Die Antwort wird dekodiert und im Format der App kodiert, bei einem Stream Ereignis für Ereignis, mit den Headern kaeso-model und kaeso-provider.

Was die App erhalten kann

200OKDie Antwort im eigenen Format der App, mit dem Modell und dem Anbieter, die sie geliefert haben.
529ÜberlastetDer Anbieter ist überlastet: 529 im Anthropic-Format, 503 in den OpenAI-Formaten.

Jede Antwort nennt die Anfrage und, sobald das Modell feststeht, wer sie bedient hat:

kaeso-request-id: req_…kaeso-provider: anthropickaeso-model: claude-haiku-5-5

Schritt 8 von 8

Protokoll

Nutzung, die Kosten zu den Preisen, die bei der Anfrage galten, und das Anfrageprotokoll werden erfasst, mit dem Inhalt, wenn die Organisation es erlaubt.

Was die App erhalten kann

200OKDas Protokollieren hält nie eine Anfrage auf: Die Antwort geht zuerst hinaus, und Protokolleinträge warten im Arbeitsspeicher.
499Client getrenntDie App hat die Verbindung geschlossen. Kaeso stoppt die Anfrage beim Anbieter sofort und berechnet, was verbraucht wurde.

Protokollzeilen warten im Arbeitsspeicher und gehen gebündelt an ClickHouse:

[logs]buffer_size = "256MiB"flush_interval = "1s"flush_rows = 5000

Was das Gateway mit jeder Anfrage macht.

Schlüssel, die im Gateway bleiben, Zustand in Datenbanken, die Sie bereits betreiben, und ein Dienst, den Sie wie jeden anderen führen.

Schlüssel bleiben im Gateway

Anbieter-Schlüssel erreichen nie Ihre Apps, und jede Aktion in der Konsole wird gegen genau ein Recht geprüft.

Mehr über Anbieter-Schlüssel

Was Ihre Apps verwahrensk-kso-AbC1…wxyzInferenz

Einen Kaeso-Schlüssel, nur als Hash gespeichert, mit Ablaufdatum und Inferenz- oder Plattformzugriff.

Was das Gateway verwahrtOpenAIAnthropicAES-256-GCM

Anbieter-Schlüssel, per Envelope-Verschlüsselung mit AES-256-GCM unter einem Hauptschlüsselbund, den Sie verwahren. Den Hauptschlüssel rotieren Sie mit kaeso master-key rewrap.

Anmeldung: Passwort mit Authenticator-App und Wiederherstellungscodes, Anmeldelinks und Single Sign‑on über den OIDC-Anbieter jeder Organisation
Rechte: Feingranulare Rechte mit eingebauten Rollen und bis zu 50 eigenen Rollen pro Organisation
Audit-Logs: Für die Instanz, jede Organisation und jedes Projekt

Anmeldung: Passwort mit Authenticator-App und Wiederherstellungscodes, Anmeldelinks und Single Sign‑on über den OIDC-Anbieter jeder Organisation
Rechte: Feingranulare Rechte mit eingebauten Rollen und bis zu 50 eigenen Rollen pro Organisation
Audit-Logs: Für die Instanz, jede Organisation und jedes Projekt

Zustand in Datenbanken, die Sie kennen

Gateway-Instanzen speichern nichts selbst, also stellen Sie weitere hinter Ihren Load Balancer. Sie teilen sich ein PostgreSQL, ein ClickHouse und ein Valkey.

Die Architektur lesen

Jede Gateway-InstanzZustandslos

PostgreSQLSchlüssel, Katalog, Limits, Nutzung und Audit-Logs

ClickHouseAnfrageprotokolle und Nutzungsaggregate

ValkeyRaten- und Budgetzähler, gemeinsame Caches

PostgreSQL: Schlüssel, Katalog, Limits, Nutzung und Audit-Logs
ClickHouse: Anfrageprotokolle und Nutzungsaggregate
Valkey: Raten- und Budgetzähler, gemeinsame Caches

PostgreSQL: Schlüssel, Katalog, Limits, Nutzung und Audit-Logs
ClickHouse: Anfrageprotokolle und Nutzungsaggregate
Valkey: Raten- und Budgetzähler, gemeinsame Caches

Wie jeden Dienst betreiben

Konfigurieren Sie es mit KAESO_*-Variablen oder einer TOML-Datei, lesen Sie jedes Geheimnis aus einer Datei und überwachen Sie es mit den Werkzeugen, die Sie schon nutzen.

Die Konfiguration lesen

kaeso.toml

1listen = "0.0.0.0:8080"2public_url = "https://kaeso.example.com"3 4[providers.anthropic]5base_url = "https://api.anthropic.com"6 7[upstream]8request_timeout = "600s"9 10[logs]11buffer_size = "256MiB"

1KAESO_LISTEN=0.0.0.0:80802KAESO_PUBLIC_URL=https://kaeso.example.com3KAESO_PROVIDERS_ANTHROPIC_BASE_URL=https://api.anthropic.com4KAESO_UPSTREAM_REQUEST_TIMEOUT=600s5KAESO_LOGS_BUFFER_SIZE=256MiB6KAESO_MASTER_KEYS_FILE=/run/secrets/master_keys

Metriken: Prometheus auf Port 9100, den Caddy nicht weiterleitet; halten Sie ihn privat
Zustand: /healthz, solange der Prozess läuft, und /readyz mit dem Zustand von PostgreSQL, Valkey und ClickHouse
Logs: Strukturiertes JSON, Anfrageprotokolle standardmäßig 90 Tage, Inhalte 30 Tage
Streams: Keepalives alle 15 Sekunden; der Aufruf beim Anbieter wird abgebrochen, wenn die App weg ist

Metriken: Prometheus auf Port 9100, den Caddy nicht weiterleitet; halten Sie ihn privat
Zustand: /healthz, solange der Prozess läuft, und /readyz mit dem Zustand von PostgreSQL, Valkey und ClickHouse
Logs: Strukturiertes JSON, Anfrageprotokolle standardmäßig 90 Tage, Inhalte 30 Tage
Streams: Keepalives alle 15 Sekunden; der Aufruf beim Anbieter wird abgebrochen, wenn die App weg ist

Ein Repository, eine Version.

Das Gateway, die Konsole, KPP und Kaeso UI erscheinen gemeinsam, unter der MIT-Lizenz.

Quellcode auf GitHub ansehen (öffnet in einem neuen Tab)

Stellen Sie es vor Ihre Apps.

Eine Compose-Datei mit Caddy, dem Gateway, der Konsole, PostgreSQL, ClickHouse und Valkey, auf Ihren eigenen Servern.

Kaeso selbst hosten Doku lesen