English | 中文

Kova is a cloud-neutral seed image build execution plane for agentic infrastructure. It verifies immutable source bundles, schedules BuildKit, pushes OCI or Nydus images, and returns verified OCI manifest digests.

Quick start

You need a Kubernetes cluster, Helm with OCI support, and kubectl. Choose a tag from GitHub releases so the chart, CLI, and runtime images stay aligned. Provenance-attested CLI archives for Linux, macOS, and Windows are published there as well.

Install the CLI:

go install github.com/cofy-x/kova/cmd/kova@latest
kova version

Install the service. The quick-start profile uses a generated static token; shared environments should use TokenReview:

export KOVA_VERSION=vX.Y.Z
export KOVA_SERVICE_TOKEN=$(openssl rand -hex 32)
export KOVA_PLATFORM=linux/amd64 # or linux/arm64

kubectl create namespace kova --dry-run=client -o yaml | kubectl apply -f -
kubectl -n kova create secret generic kova-service-auth \
  --from-literal=token="${KOVA_SERVICE_TOKEN}"

helm show crds oci://ghcr.io/cofy-x/charts/kova \
  --version "${KOVA_VERSION#v}" | kubectl apply -f -
helm upgrade --install kova oci://ghcr.io/cofy-x/charts/kova \
  --version "${KOVA_VERSION#v}" \
  --namespace kova \
  --create-namespace \
  --set serviceDaemon.enabled=true \
  --set serviceDaemon.authentication.mode=static \
  --set serviceDaemon.authentication.staticPrincipal=kova:quickstart \
  --set serviceDaemon.authentication.staticTokenSecret.name=kova-service-auth \
  --set-string worker.platform="${KOVA_PLATFORM}" \
  --wait

kubectl -n kova create rolebinding kova-quickstart \
  --role=kova-service-submitter \
  --user=kova:quickstart

Applying the release CRD before every Helm upgrade is required because Helm does not upgrade files from a chart's crds/ directory.

Run your first build:

kubectl -n kova port-forward service/kova-service 8080:8080 &

kova ctx set --mode service --service-url http://127.0.0.1:8080 --use quickstart
kova doctor
kova job submit \
  --source-repository registry.example.com/team/kova-sources:quickstart \
  --target registry.example.com/team/image:dev \
  --platform "${KOVA_PLATFORM}" \
  ./image
kova job wait <job-id>
kova job results <job-id>

Registry credentials, Nydus output, and batch archives are covered in the installation and first-build guide.

Python SDK

kova-client is the official Python-first Service SDK:

python -m pip install kova-client
python examples/service-sdk/python/main.py

The synchronous and asynchronous clients expose the same thin HTTP v1 operations and never own workflow recovery or durable receipts. See the Python client contract and the executable Service SDK examples for the shared environment and caller-owned receipt flow.

Go SDK

External Go callers can use the stable Service API types in pkg/api/v1 and the shared client used by the Kova CLI in pkg/client:

go run ./examples/service-sdk/go

Compatibility checks are explicit, so CreateBuild performs exactly one submission request. The SDKs do not own retry or recovery workflows and never automatically retry CreateBuild or other mutating requests. Callers use an idempotency key for safe submission retries and persist the immutable source identity, build ID, manifest digest, and immutable reference before the terminal Kova job expires. The verified manifest digest and immutable_ref are success facts; tags and ephemeral logs are not. See the external Go client and HTTP contract, the executable Service SDK examples, and the machine-readable Service API.

Why Kova

• Immutable source to verified image — every build consumes a digest-verified OCI or HTTPS source and returns the pushed single-platform image manifest digest and verified platform.
• A bounded execution model — one immutable KovaBuild accepts up to 100 logical targets and records at most 200 concrete outputs; callers own larger workflow partitioning and retries.
• Fair, work-conserving scheduling — queued jobs interleave by authenticated requester; admission reserves actual BuildKit worker slots.
• Isolated execution — one runner Pod per job drives shared upstream rootless BuildKit workers; controller and runner run as non-root with all capabilities dropped.
• Kubernetes-native auth — TokenReview and SubjectAccessReview by default; submitters never touch Pods, Secrets, or other users' jobs.
• Cloud-provider-neutral — registry and API credentials are external Secret inputs. The chart creates no clusters, cloud accounts, object stores, or registries.
• Observable — stable OpenTelemetry metrics for queue delay, job duration, and capacity waits.

Documentation

• Documentation map: choose the guide for a task.
• Installation and first build: OCI chart, matching CLI, and a verified build.
• Service job workflow: immutable sources, identity, RBAC, bounded results, and job operations.
• CLI workflow: direct runner builds for development and low-level debugging.
• Runtime design: roles, topology, build/export, preheat, and scaling flows.
• Kubernetes deployment: registry credentials, worker sizing, and production configuration.
• Release process: CLI archives, OCI charts, runtime images, SBOMs, and provenance.
• Examples: build input examples and runtime smoke services.

Develop

The repository requires the Go version declared in go.mod, Docker, kind, Helm, kubectl, curl, zip, and LMDB development headers.

make test
make lint-scripts
make helm-template
make e2e-helm-quickstart   # released-chart install path on kind

Use the validation matrix to choose broader E2E coverage. Contributions are welcome; the contribution workflow covers the full setup and pull request process. Report vulnerabilities through the private process in the security policy.

License

Kova is licensed under the Apache License 2.0.