timoni
Timoni is a package manager for Kubernetes,
powered by CUE
and inspired by Helm.
The Timoni project strives to improve the UX of authoring Kubernetes configs.
Instead of mingling Go templates with YAML like Helm,
or layering YAML on top of each-other like Kustomize,
Timoni relies on cuelang's type safety, code generation, and data validation features
to offer a better experience of creating, packaging, and delivering apps to Kubernetes.
> [!IMPORTANT]
> Note that Timoni in under active development and is still in its infancy.
> The APIs and command-line interface may change in a backwards incompatible manner.
Get Started
To get started with Timoni please visit the documentation website at timoni.sh.
Concepts
- Module - App definition containing Kubernetes CUE templates and configuration schema, distributed as OCI artifacts.
- Instance - App instantiation referencing the module and workloads deployed on a Kubernetes cluster.
- Bundle - App composition bundling multiple modules and configurations into a deployable unit.
- OCI Artifact - Packaging format used for distributing modules and bundles through registries or local OCI archives and layouts.
> [!TIP]
> If you are familiar with Helm, a Timoni module is the equivalent of a chart,
> a Timoni bundle is the equivalent of an umbrella chart,
> and a Timoni instance is the equivalent of a Helm release.
Features
App Packaging and Distribution
Timoni enables software vendors to define complex application deployments,
packaged as Modules, using type-safe
Kubernetes templates and rich customisation options for end-users.
The app configuration packaged in a Module is
distributed as an
Open Container Initiative (OCI) artifact, next to the app images,
in a container registry. Timoni Modules are semantically versioned
and can be cryptographically signed when pushed.
Local build outputs are unsigned OCI archives or layouts for offline handoff.
Module distribution:
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
Generic artifacts transport bundle files, runtime files, and other content without module, instance, or deployment semantics:
timoni artifact push -f ./delivery -t 1.0.0 oci://registry.example.com/my-app
With Timoni, platform engineers can manage the lifecycle of Kubernetes
controllers, including the upgrade of CRDs. Module authors can
import CRD schemas
from YAML files and incorporate Kubernetes custom resources
in their app deployments.
App Lifecycle Management
With Timoni, users can manage the whole lifecycle of applications deployed on Kubernetes.
From highly customised installation to seamless upgrades,
end-to-end testing, safe rollback, and uninstallation.
With Timoni, users can bundle microservices and distributed monoliths into a deployable unit.
The Timoni Bundle offers a declarative way of managing
the app delivery across clusters, where secrets and other environment-specific config
values are dynamically loaded during installation or upgrades.
Bundle lifecycle:
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
AI Agents Integration
Timoni ships agent skills and a
docs MCP server so that AI agents
can operate Timoni end-to-end, from authoring modules and bundles to multi-cluster deployments.
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
See the AI Agents guide for more information
on how to configure Codex, Copilot, Cursor, OpenCode, and other agents.
License
Timoni is Apache 2.0 licensed and accepts contributions via GitHub pull requests.
Please see the contributing guide for more information.
When using AI coding agents to contribute to Timoni, please point the agents to AGENTS.md.