Concepts

How packages, sources, products, and installations fit together

Akua turns your application into per-customer deployments through a small set of primitives. This page lays them out so you can predict what happens at each stage, across any surface: dashboard, CLI, API, or git.

The flow at a glance

A Package is the deploy definition. You can author one directly, or attach Sources to supply its dependencies (GitHub repos add automatic image builds; Helm and Docker sources point at upstream content). Products wrap a Package with pricing for sale; Direct installs use a Package internally. When a customer installs, Akua materializes the Package into a per-installation git repository — the customer’s specific copy, with their inputs and rendered manifests.

The primitives

Package

The deploy definition, and the canonical primitive. A Package describes how to turn customer inputs and upstream dependencies into Kubernetes resources. It contains:

• akua.toml: package metadata and a list of upstream dependencies (Helm charts, container images, other Packages)
• package.k: composition logic in KCL that turns inputs into resources; can import declared dependencies and patch any field on rendered output
• An input schema: what customers can configure

A Package is portable on its own. Akua doesn’t need to know where the dependencies originally came from to render and deploy it. The akua.toml is the contract.

Source

An upstream connection that supplies content to a Package. What the version represents depends on the source type:

• GitHub repository: Railpack builds a container image on every push. The Package exposes an input field for the image tag, so picking up a fresh build is an input change.
• Helm chart: A reference to a chart on Artifact Hub, an OCI registry, or git. The Package’s akua.toml pins which chart version to vendor; bumping the chart is a Package-version change.
• Docker image: A reference to a public container image. The Package exposes an input field for the tag, so changing the tag is an input change (no Package re-version needed).

Sources are wiring, not content. The deploy definition lives in the Package’s akua.toml and package.k; Sources are how the upstream content gets attached. The simple flow is: pick sources → Akua composes a Package → ship it. Or skip Sources entirely and author the Package yourself.

Product

A sellable wrapper around a Package: pricing, marketplace metadata, and any product-level default inputs. Products appear in the marketplace once pricing is configured.

Use a Product when you want to sell software. For internal tools, use a Direct install instead.

Direct install

A deployment that uses a Package without product wrapping. No pricing, not listed in the marketplace. Same Package, just used internally.

Installation

A specific running deployment in a workspace. Two flavors:

• Product-based installation: created when a customer purchases a Product; inherits the Product’s defaults and supports per-install overrides on top.
• Standalone installation: created directly without a Product; owns its inputs 1:1.

Both flavors materialize the Package into a per-install repository.

Per-install repository

The materialized Package for one installation: a private git repository owned by the customer’s workspace.

File	What it holds
akua.toml	Package metadata and upstream dependencies (copied from the Package definition)
package.k	Composition logic (copied from the Package definition)
inputs.yaml	The customer’s configured inputs
upstream/	Vendored copies of the dependencies at provision time
manifests/	Rendered Kubernetes resources (your cluster syncs these)

The wizard, the CLI, and git push all edit the same repository. Re-rendering is pure: identical inputs always produce identical manifests, so equivalent edits don’t churn deploys.

See Installation repositories → for the full model.

How updates flow to customers

An update is any change to a Package: its inputs, its package.k composition, or its akua.toml pinned dependencies. The change might come from the seller editing a Product, the customer editing their install’s inputs, or an automated bump (a fresh GitHub-built image landing as a new tag, or a new Helm chart version pinned in akua.toml). All of them are Package-level edits.

Once a Package change happens, Akua propagates it:

1. Per-install re-render: each affected installation gets a fresh render of the new Package against its own inputs.yaml, written to its own repository.
2. Customer overrides preserved: install-specific overrides on top of product defaults survive the re-render; only what changed in the Package flows through.
3. Independent rollout: each install advances on its own commit history; a failed render on one customer’s install doesn’t block the others.
4. Pinning respected: if an install is pinned to an older Package version, the bump skips it until the customer (or seller) chooses to upgrade.

To the seller, updating customers is a single decision: edit the product’s defaults or composition and ship the new Package version. To the platform, it’s a fan-out. Every installation re-renders and converges on its own schedule.

What builds on what

Layer	What it owns	Per-customer?
Source	Upstream connection (auto-build, update watcher)	No (shared)
Package	Composition logic, dependencies, input schema	No (shared)
Product / Direct install	Selected Package + default inputs (+ pricing for Products)	No (shared)
Installation	A specific deployment in a workspace	Yes
Per-install repository	Materialized Package: vendored deps + inputs + rendered manifests	Yes

Customer A and Customer B can install the same Product and get isolated repositories with different inputs, different version pinning, and independent deploy histories. A change you make for Customer A stays scoped to their repository.

Customization surfaces

Three surfaces edit the same state:

• Dashboard wizard: a form view over the Package’s input schema, generated from the Input schema and any @ui annotations the author added
• CLI / API: programmatic access to the same inputs
• git push: direct edits to the installation’s repository

The wizard writes to inputs.yaml. A git push to that file is equivalent. Akua re-renders on every change. For edits the wizard doesn’t expose (patching individual fields, adding sidecars, swapping image registries), see Customize an installation via git →.

Sellers control the wizard’s presentation by writing docstrings and @ui annotations on their Input schema. The same schema drives shareable install links at /i/<slug>.

Related topics

Installation repositories

The per-install git repo: what’s inside and why it’s there.

Products

The sellable wrapper with pricing and marketplace metadata.

Customize via git

Edit inputs, patch resources, and push commits.

Quickstart

Get your first product live in minutes.