> ## 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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/akua-0b861dc6/o-ywDlh24ZayP_tj/images/heros/concepts-light.svg?fit=max&auto=format&n=o-ywDlh24ZayP_tj&q=85&s=ad32b1c2b2d9684678b4edfe3322b9a1" alt="Diagram of Akua's core concepts as a chain: a central Package contract card — holding akua.toml, package.k, and an input schema — connects to its two wrappers, a Product card and an Offer card, which converge into a single running Installation." width="1536" height="864" data-path="images/heros/concepts-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/akua-0b861dc6/o-ywDlh24ZayP_tj/images/heros/concepts-dark.svg?fit=max&auto=format&n=o-ywDlh24ZayP_tj&q=85&s=2fd0f454124cb63de22dda06459f90c3" alt="Diagram of Akua's core concepts as a chain: a central Package contract card — holding akua.toml, package.k, and an input schema — connects to its two wrappers, a Product card and an Offer card, which converge into a single running Installation." width="1536" height="864" data-path="images/heros/concepts-dark.svg" />
</Frame>

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["<b>Package</b><br/>akua.toml + package.k<br/>+ input schema"]

    WATCH -. supplies deps .-> PKG
    AUTHORED --> PKG

    PKG --> P["<b>Product</b>"]
    PKG --> SI["<b>Direct install</b>"]

    P --> OFFER["<b>Offer</b><br/>short URL + terms"]
    OFFER -- customer purchases --> INS["<b>Installation</b>"]
    SI -- creates --> INS

    INS -- materializes --> REPO[("Per-install<br/>repository")]
    REPO --> K8S["Cluster syncs<br/>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/<hash>`.

## Related topics

<CardGroup cols={2}>
  <Card title="Installation repositories" icon="folder-tree" href="/installs/repositories">
    The per-install git repo: what's inside and why it's there.
  </Card>

  <Card title="Products" icon="box" href="/products">
    The sellable wrapper with marketplace metadata.
  </Card>

  <Card title="Offers" icon="link" href="/marketplace/offers">
    Short customer URLs with selected inputs and terms.
  </Card>

  <Card title="Customize via git" icon="code-branch" href="/installs/install-repo">
    Edit inputs, patch resources, and review repository changes.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first product live in minutes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.