Reference on Krypton Runtime

Agent CRD

Mon, 01 Jan 0001 00:00:00 +0000

apiVersion: krypton.ai/v1alpha1, kind: Agent, namespaced (short name ag).

Minimal example

apiVersion: krypton.ai/v1alpha1
kind: Agent
metadata:
 name: travel
 namespace: agents
spec:
 image: ghcr.io/org/travel-agent:latest

That’s the smallest valid Agent. Everything else has a default.

Full example

apiVersion: krypton.ai/v1alpha1
kind: Agent
metadata:
 name: travel
 namespace: agents
spec:
 # Container
 image: ghcr.io/org/travel-agent:latest
 imagePullPolicy: IfNotPresent
 imagePullSecrets:
 - name: ghcr-secret

 # Metadata (informational — surfaced in UI + metrics)
 runtime: python
 framework: langgraph

 # Wire protocol the agent speaks
 protocol: a2a  # a2a | mcp | http

 # Mode
 mode: always-on  # always-on (default); scale-from-zero is on the roadmap

 # Scaling
 minReplicas: 1
 maxReplicas: 10
 concurrency: 8 # in-flight requests per pod

 # Networking
 port: 8080
 invocationPath: /a2a

 # Pod
 resources:
 requests: { cpu: 100m, memory: 256Mi }
 limits: { cpu: 1000m, memory: 1Gi }
 env:
 - { name: LOG_LEVEL, value: info }
 envFrom:
 - secretRef: { name: travel-secrets }
 serviceAccountName: "" # blank = auto-create

 # Lifecycle
 timeout: 60s  # per-invocation
 startupTimeout: 30s  # cold-start grace

Spec reference

Container

Field	Type	Default	Notes
`image`	string (required)	—	Container image, including registry + tag
`imagePullPolicy`	string	`IfNotPresent`	Standard K8s pull policy
`imagePullSecrets`	`[]corev1.LocalObjectReference`	—	Same shape as a pod’s `imagePullSecrets`

Metadata

Field	Type	Default	Notes
`runtime`	string	—	Informational (`python`, `node`, `go`, …)
`framework`	string	—	Informational (`langgraph`, `crewai`, …)
`protocol`	string	`a2a`	One of `a2a`, `mcp`, `http`

Mode + scaling

Field	Type	Default	Notes
`mode`	string	`always-on`	Currently `always-on` only; scale-from-zero is on the roadmap
`minReplicas`	int32 (≥ 1)	`1`	Always-on floor
`maxReplicas`	int32 (≥ 1)	`10`	Must be ≥ `minReplicas`
`concurrency`	int32 (≥ 1)	`8`	In-flight requests per pod cap (enforced by sidecar)

Networking

Field	Type	Default	Notes
`port`	int32 (1–65535)	`8080`	User container’s listen port
`invocationPath`	string	`/`	Path the gateway forwards invocations to (prefix-stripped)

Pod

Field	Type	Default	Notes
`resources`	`corev1.ResourceRequirements`	—	Same as a pod’s `resources`
`env`	`[]corev1.EnvVar`	—	Passed to user container
`envFrom`	`[]corev1.EnvFromSource`	—	Same
`serviceAccountName`	string	`""`	Empty = auto-created SA with minimal permissions

Lifecycle

Field	Type	Default	Notes
`timeout`	duration	`60s`	Bounds a single invocation
`startupTimeout`	duration	`30s`	Activator’s cold-start grace; gateway returns 504 if exceeded

Status (read-only)

Field	Type	Written by
`phase`	enum	Manager
`replicas`	int32	Manager
`readyReplicas`	int32	Manager
`desiredReplicas`	int32	Scaler + activator
`url`	string	Manager
`lastInvocationAt`	time	Gateway
`observedGeneration`	int64	Manager
`conditions`	`[]Cond.`	Manager

Phases

Phase	Meaning
`Pending`	At least one desired replica, none ready yet
`Ready`	At least one replica ready, OR scaled to zero
`Scaling`	(reserved; not currently emitted)
`Failed`	Persistent reconcile errors (e.g. crashloop)

Validation

Beyond OpenAPI defaults, the (optional) validating webhook enforces:

Model CRD

Mon, 01 Jan 0001 00:00:00 +0000

apiVersion: krypton.ai/v1alpha1, kind: Model, namespaced (short name mdl).

The Model CRD declares “host this Hugging Face GGUF as an OpenAI-compatible model named X”. The controller turns it into a Deployment running llama.cpp’s HTTP server, plus a Service. The gateway aggregates every Model in the cluster at /v1/models and routes incoming /v1/chat/completions (etc.) requests by the model field in the body.

Minimal example

apiVersion: krypton.ai/v1alpha1
kind: Model
metadata:
 name: qwen2-0-5b
 namespace: models
spec:
 source:
 huggingface: Qwen/Qwen2.5-0.5B-Instruct-GGUF
 file: qwen2.5-0.5b-instruct-q4_k_m.gguf

That’s the smallest valid Model — every other field has a default.

CLI flags

Mon, 01 Jan 0001 00:00:00 +0000

Every binary uses Go’s standard flag package. --help on any of them prints the full list.

Manager (`cmd/manager`)

The controller + scaler.

Flag	Default	Notes
`--metrics-bind-address`	`:8080`	Prometheus scrape target
`--health-probe-bind-address`	`:8081`	`/healthz`, `/readyz`
`--leader-elect`	`false`	Required when running multiple replicas
`--enable-webhooks`	`true`	Set false to skip webhook server (Helm chart does)
`--proxy-image`	`ghcr.io/kryptonhq/krypton-proxy:latest`	Sidecar image injected into agent pods
`--enable-scaler`	`true`	Disable to run controller only
`--scaler-interval-ms`	`1000`	Tick interval for the scaling decider
`--scaler-stable-window-ms`	`60000`	Hysteresis: refuse scale-down within this window
`--sidecar-port`	`8888`	Where the scaler probes `/_krypton/inflight`

Control plane (`cmd/control-plane`)

REST API + UI.

Helm values

Mon, 01 Jan 0001 00:00:00 +0000

Chart source: deploy/helm/krypton.

Common overrides

# values.yaml
image:
 registry: ghcr.io/kryptonhq
 tag: v0.0.4

controlPlane:
 databaseUrl: "postgres://user:pass@host:5432/db"

manager:
 enableWebhooks: false
 enableScaler: true

gateway:
 service:
 type: ClusterIP  # operators add their own ingress in front

Full reference

`image`

Default image base for all components. Per-component overrides under images.* take precedence.

image:
 registry: ghcr.io/kryptonhq
 tag: "" # empty → falls back to .Chart.AppVersion
 pullPolicy: IfNotPresent

Leaving tag empty makes the chart pin images at the same version as the chart release (the helper falls back to .Chart.AppVersion), so helm install Just Works without explicit --set image.tag=....

Reference on Krypton Runtime

Agent CRD

Minimal example

Full example

Spec reference

Container

Metadata

Mode + scaling

Networking

Pod

Lifecycle

Status (read-only)

Phases

Validation

Model CRD

Minimal example

CLI flags

Manager (cmd/manager)

Control plane (cmd/control-plane)

Helm values

Common overrides

Full reference

image

Manager (`cmd/manager`)

Control plane (`cmd/control-plane`)

`image`