Timoni packs Kubernetes apps as CUE modules and bundles

CUE types replace Helm templates and Kustomize overlays

Kubernetes shops tend to carry two separate patching systems. Helm mixes Go template strings into YAML documents, and Kustomize layers YAML on top of other YAML. Timoni takes a different route: an application is a CUE program with a schema, and its design is credited to cuelang's type safety, code generation and data validation. The audience is the same in each case, platform engineers who publish an app once and let other people configure it at install time, so the interesting question is not what Timoni manages but what a configuration author has to write.

One note in the README sits above the rest of the documentation and is worth quoting, because it frames the whole tool: Timoni is in its infancy, and its APIs and command-line interface may change in a backwards incompatible manner. Anyone wiring it into a pipeline should plan for flag churn rather than assume the command surface has settled.

Module, instance, bundle and the OCI artifact boundary

Four nouns carry the design. A module is an app definition holding Kubernetes CUE templates plus a configuration schema, and it travels as an OCI artifact. An instance is that module instantiated on a cluster. A bundle composes several modules and their configurations into one deployable unit, and the same artifact format carries both modules and bundles through registries or through local OCI archives and layouts.

Helm users get a direct mapping in a single sentence: module to chart, bundle to umbrella chart. That is enough to plan a migration, and it also shows where the analogy breaks, because a Timoni instance references a module and workloads rather than a rendered chart paired with a values file. Bundles add a runtime dimension the four nouns do not name on their own, since secrets and other environment-specific config values are loaded dynamically during installation or upgrades instead of being frozen at build time.

Getting the binary, then building your first module

The README carries no installation command. Its Get Started line sends readers to the documentation site at https://timoni.sh/quickstart/, and the platforms badge points at https://timoni.sh/install, so the binary itself is announced outside the repository text. Anyone building a tutorial from this README has to stop there and link out.

What the repository does give is the module distribution path, and those two commands are the real first use. The first builds a module directory into a local OCI archive whose name comes from the output flag and whose version comes from the version flag. The second pushes that archive to a registry path.

timoni mod build ./my-app -v 1.0.0 -o my-app-1.0.0.oci.tar
timoni mod push my-app-1.0.0.oci.tar oci://registry.example.com/my-app

The version is semver, and go.mod pins github.com/Masterminds/semver/v3 v3.5.0 for that check. Note the signature status difference between the two steps: local build output is an unsigned OCI archive or layout meant for offline handoff, while a module pushed to a registry can be cryptographically signed.

Bundle apply gated behind a diff render

The bundle lifecycle is documented as four lines, and the middle pair is the point. Render first, preview second, apply third, uninstall last.

timoni bundle build  -f ./bundle.cue # Render without applying (optional)
timoni bundle apply  -f ./bundle.cue --diff # Preview changes before applying
timoni bundle apply  -f ./bundle.cue # Install or upgrade
timoni bundle delete -f ./bundle.cue # Uninstall

`--diff` prints what would change before that same command writes to the cluster, which is a habit worth copying into any pipeline built around this tool. Watch the naming collision though: `bundle build` renders manifests and applies nothing, so a reader arriving from `mod build`, which produces an OCI tar, can expect an artifact and get YAML instead. One install verb covers upgrades too, so there is no separate upgrade command to learn or forget.

One registry path, two payload semantics

Packaging is where a close read pays off. Modules travel up through `timoni mod push`. A second command writes to the same kind of path, yet what it carries is explicitly not a module.

timoni artifact push -f ./delivery -t 1.0.0 oci://registry.example.com/my-app

Generic artifacts transport bundle files, runtime files and other content without module, instance or deployment semantics, and the tag flag here is -t, where module versioning uses -v. Both README examples target the identical repository, oci://registry.example.com/my-app, so a registry holding two kinds of payload is the documented arrangement rather than an accident of the docs. Nothing states how a consuming client tells the two apart on pull, and closing that gap in your own tooling matters before you build a pipeline on the pattern.

What the Go module and Makefile expose

Prose explains what Timoni is for; go.mod and the Makefile show what it is built from. The dependency list borrows server-side apply machinery from github.com/fluxcd/pkg/ssa v0.78.0, pins the Kubernetes client libraries at v0.37.1, stacks sigs.k8s.io/controller-runtime v0.25.1 on top, and lets cuelang.org/go v0.17.1 handle CUE evaluation. The build target produces one static binary.

CGO_ENABLED=0 go build -ldflags="-s -w -X main.VERSION=$(DEV_VERSION)" -o ./bin/timoni ./cmd/timoni

The test target runs tidy, generate, fmt, vet, lint and install-envtest before the Go tests, with KUBEBUILDER_ASSETS supplying control plane binaries and ENVTEST_KUBERNETES_VERSION set to 1.37. The cue-vet target is the interesting one, because it vets the project's own schema directory as well as every example module.

./bin/timoni fmt ./schemas
cue vet ./schemas/...

Two details there show how carefully the wiring is done. Module vetting is skipped for ./examples/bundles, the example directory holding bundles instead of a single module, so a broken bundle example cannot fail that target. And the Redis image version is scraped out of a CUE file by a shell pipeline rather than read from a manifest.

REDIS_VER=$(shell grep 'tag:' examples/redis/images.cue | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)

Gaps in the documented lifecycle, including rollback

The feature prose promises more than the command list shows. The lifecycle paragraph names customised installation, upgrades, end-to-end testing, safe rollback and uninstallation, yet the only bundle verbs documented anywhere in the README are build, apply and delete. No rollback command, flag or example appears, so treat that word as an intention until you can point at the invocation. Nothing describes how an existing Helm chart becomes a module either, or whether a mixed estate can share a cluster with Helm still installed.

Two facts frame the upgrade cost. Timoni is distributed under the Apache-2.0 licence and accepts contributions through pull requests, and the last push was on 2026-10-05. Set against the warning about backwards incompatible API and command changes, those pinned Kubernetes dependencies mean a cluster version bump becomes a dependency bump in this repository, which is where the real work sits for anyone tracking upgrades.

Agent skills and a docs MCP server ride along

Timoni also ships integration for coding agents, which is the one part of the distribution story reaching entirely outside the Kubernetes workflow. Two commands are documented for it.

npx skills add https://timoni.sh # Install the skills for your agent
claude mcp add --transport http timoni-docs https://timoni.sh/mcp # Connect the docs MCP server

The first pulls a skill bundle into whatever agent runtime you already run, and the second registers a documentation MCP server over HTTP. The repository backs this with a skills/ directory, a .mcp.json file at the root, and an AGENTS.md that contributors are asked to point coding agents at. What that docs server is not is a control channel, since it serves the site: cluster actions still go through the timoni binary and a kubeconfig, and an agent run against this project is only as good as the CUE schema it is allowed to edit.

Editorial conclusion

Adopt Timoni when your team writes an application definition once and ships it to many clusters, and when you are ready to author that definition in CUE instead of Helm templates. Leave it aside if an existing chart library is what you need to keep, because no path from a chart to a module is documented. Before committing, run `timoni mod vet` on your module and read the `--diff` output of `timoni bundle apply` against what the cluster holds, since the README lists rollback without showing the command.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. stefanprodan/timoni on GitHub