> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Concepts
> How packages, dependencies, products, and installations fit together
Akua turns your application into per-customer installs 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
```mermaid theme={null}
%%{init: {'flowchart': {'nodeSpacing': 60, 'rankSpacing': 70, 'curve': 'basis'}}}%%
flowchart TB
subgraph WATCH["Dependencies — packaged content"]
direction LR
HW["Helm chart"]
DI["Container image"]
end
AUTHORED["Author a Package directly"]
PKG["Package
akua.toml + package.k
+ input schema"]
WATCH -. supplies deps .-> PKG
AUTHORED --> PKG
PKG --> P["Product"]
PKG --> SI["Direct install"]
P --> OFFER["Offer
short URL + terms"]
OFFER -- customer purchases --> INS["Installation"]
SI -- creates --> INS
INS -- materializes --> REPO[("Per-install
repository")]
REPO --> K8S["Cluster syncs
rendered manifests"]
```
A Package is the versioned install contract. You can author one directly, then declare supported dependencies such as Helm charts, container images, or other Packages. Products wrap a Package for sale; Offers carry the concrete customer path, terms, access rules, and short URL. 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 versioned install contract, and the canonical primitive. A Package describes how to turn customer inputs and upstream dependencies into Kubernetes resources for an installation. 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.
### Dependencies
Upstream content that a Package vendors or references. What the version represents depends on the dependency type:
* **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.
* **Container image**: A reference to an OCI image used by the Package's Kubernetes resources. Changing the tag is an input or Package-version change, depending on how the Package author exposes it.
* **Package**: A reusable dependency imported by another Package.
Dependencies are wiring, not the install contract. The install contract lives in the Package's `akua.toml` and `package.k`; dependencies are the upstream content the Package renders from. The simple flow is: author a Package, declare dependencies, then ship it.
### Product
A sellable wrapper around a Package: marketplace metadata, selected Package version, and default inputs. Products can appear in the marketplace or stay private behind Offers.
Use a Product when you want to sell software. For internal tools, use a Direct install instead.
### Offer
A customer-facing sales path for a Product or Package version. An Offer owns the short URL, access rules, pre-filled field values, expiry, and commercial terms for a specific customer or reusable link.
Use an Offer when you want to send a customer directly into the generated install wizard.
### Direct install
An installation that uses a Package version without Product wrapping. No pricing, not listed in the marketplace. Same Package model, just used internally.
### Installation
A specific running installation in a workspace. Two flavors:
* **Product-based installation**: created when a customer purchases a Product; inherits the selected Package version's defaults and supports per-install overrides on top.
* **Direct installation**: created directly without a Product; selects a Package version and 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 from the selected Package version |
| `package.k` | Composition logic from the selected Package version |
| `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 accepted repository changes all edit the same repository. Re-rendering is pure: identical inputs always produce identical manifests, so equivalent edits don't churn installs.
See [Installation repositories →](/installs/repositories) for the full model.
## How updates flow to customers
An update reaches an installation when you select a new Package version or accept a repository change request against that installation. Package versions are immutable release units: creating one doesn't change existing installations by itself.
Once you choose a rollout path, Akua updates each installation independently:
1. **Version selected**: the Product, Offer, direct install, or repository change request points at the Package version that should run.
2. **Per-install re-render**: each affected installation gets a fresh render of that Package version against its own `inputs.yaml`, written to its own repository.
3. **Customer overrides preserved**: install-specific overrides on top of Package version defaults survive the re-render.
4. **Independent rollout**: each install advances on its own commit history; a failed render on one customer's install doesn't block the others.
To the seller, updating customers is a deliberate release decision: publish the Package version, then choose which installations should move to it. Every selected installation re-renders and converges on its own schedule.
## What builds on what
| Layer | What it owns | Per-customer? |
| ---------------------------- | ----------------------------------------------------------------- | -------------------------- |
| **Dependencies** | Upstream content a Package vendors or references | No (shared) |
| **Package** | Composition logic, dependencies, input schema | No (shared) |
| **Product / Direct install** | Selected Package version + default inputs | No (shared) |
| **Offer** | Customer path, access rules, field values, and commercial terms | No (shared until redeemed) |
| **Installation** | A specific running installation 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 selected Package versions, 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](/akua/package-format#ui-annotations) the author added
* **CLI / API**: programmatic access to the same inputs
* **Repository change requests**: reviewed edits to the installation's repository
The wizard writes to `inputs.yaml`. Accepted repository changes update the same install state, and Akua re-renders after each accepted change. For edits the wizard doesn't expose (patching individual fields, adding sidecars, swapping image registries), see [Customize an installation via git →](/installs/install-repo).
Sellers control the wizard's presentation by writing docstrings and `@ui` annotations on their `Input` schema. The same schema drives shareable [Offers](/marketplace/offers) at `/i/`.
## Related topics
The per-install git repo: what's inside and why it's there.
The sellable wrapper with marketplace metadata.
Short customer URLs with selected inputs and terms.
Edit inputs, patch resources, and review repository changes.
Get your first product live in minutes.