Packages

Package dependencies composed into a readable Package version card with field, type, and default rows, reused by Product, Offer, and Direct install

A Package is the reusable install definition behind an Akua install. It owns the composition logic, dependencies, version history, and input schema that the dashboard, API, and offer wizard use. Products and Offers build on Packages. A Product is the sellable wrapper customers discover or buy. An Offer is the shareable sales path for a Product or Package version. The Package is the technical contract both of them point at.

Package first, deployment second

Akua starts from an explicit Package, not from automatic framework detection. Before a Product, Offer, or direct installation can run, the Package must describe what gets rendered, which inputs customers can set, and which cluster capabilities the install needs. This model keeps customer installs repeatable. Each Package version becomes a stable deployment contract that can be installed, audited, and reused across marketplace listings, private Offers, and internal installs. Installations created from that version can roll back through their repository history. If you’re bringing an existing application to Akua, choose the authoring path that matches the source you already have:

Starting point	Best next step
An existing Helm chart	Import or author a Package that depends on the chart and exposes the values customers should edit.
A Docker Compose app	Use the Compose converter to create Kubernetes or Helm starting points, then author the Package contract around the generated resources.
A custom Kubernetes app	Author `package.k` directly and define the customer-facing `Input` schema.
An Akua Package published to OCI	Register the Package with `POST /packages:import` and add immutable versions as you publish them.

Akua does not infer production settings from package.json, a Dockerfile, or a Git branch. Put those choices into the Package, then wrap the Package in a Product or Offer when you’re ready to sell it.

What a Package owns

Surface	Owned by Package
Source	Authored `package.k`, Package metadata, and supported sources such as chart dependencies or container images
Versions	Immutable Package versions with provenance and renderable inputs
Input schema	The customer-facing fields exported from the Package version
Defaults	Safe default inputs used by products, offers, and direct installs
Compatibility	The install shape a workspace must satisfy before using the Package

Packages do not own pricing, customer targeting, payment collection, or marketplace visibility. Those belong to Products and Offers.

Package, Product, Offer

Package version
  Input schema
  Product
    Marketplace listing or Offer
      Order draft
        Installation
  Package Offer
    Order draft
      Installation
  Direct install
    Installation

Use this split when you design your catalog:

Create or import a Package when you need a reusable install definition.
Create a Product when that Package should become a sellable catalog item.
Create an Offer when you want to send a customer a short URL with selected inputs, access rules, and commercial terms.
Use a Direct install when the Package should run internally without Product or Offer wrapping.

Input schemas

Akua exports each Package version’s Input schema to drive generated forms. Docstrings become help text. @ui(...) annotations control grouping, ordering, widget hints, placeholders, and numeric bounds. For authoring details, see Package format. For the customer-facing generated form, see Offers.

API workflows

Use the Packages API when your automation needs to create or maintain Package records outside the dashboard.

Goal	Endpoint	Result
Create a hosted Package from a supported source such as a Helm chart	`POST /packages`	Starts Package creation and returns an operation
Register an already-published OCI-backed Package	`POST /packages:import`	Creates the Package and its first immutable version
Add another version to an existing OCI-backed Package	`POST /packages/{id}/versions`	Creates a new immutable Package version

POST /packages:import and POST /packages/{id}/versions are for Packages that have already been published to an OCI registry. Your workspace must have published Package import access to use either endpoint. The API still requires you to send the version, immutable content reference, and input schema. Akua inspects the published artifact and rejects the request if the artifact metadata doesn’t match the values you send. Public registries work without a saved credential. For private registries, add an active workspace registry credential that matches the registry or repository prefix before you import the Package.

Import a published Package

To import a published Package, your workspace must have published Package import access. Use Akua-Context when your token can access more than one workspace, and send an Idempotency-Key so the request is safe to retry.

curl https://api.akua.dev/v1/packages:import \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: ws_xxx" \
  -H "Idempotency-Key: import-codezero-1-2-3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "codezero",
    "description": "Codezero Package",
    "oci_ref": "oci://ghcr.io/example/packages/codezero",
    "version": {
      "semver": "1.2.3",
      "ref": "sha256:abc123...",
      "input_schema": {
        "type": "object",
        "properties": {
          "license_key": { "type": "string" }
        }
      }
    }
  }'

The response is the created Package. Store its id; you need it to add future versions, create Products, create Offers, or install the Package directly. If you retry with the same Idempotency-Key and the same body, Akua returns the same imported Package. If you reuse the key with different Package or version data, Akua returns a conflict so your automation doesn’t accidentally point one retry key at two different artifacts.

Add versions to an imported Package

After an OCI-backed Package exists, add later published versions with POST /packages/{id}/versions. This endpoint uses the same published Package import access as the initial import.

curl https://api.akua.dev/v1/packages/pkg_xxx/versions \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "semver": "1.2.4",
    "ref": "sha256:def456...",
    "input_schema": {
      "type": "object",
      "properties": {
        "license_key": { "type": "string" }
      }
    }
  }'

Direct version creation only applies to OCI-backed Packages. You still provide the immutable content reference and input_schema for each version, and Akua verifies both values against the published artifact before registering the version. Hosted Packages created through POST /packages publish versions through their Package creation flow.

API

Manage Packages programmatically from the generated API reference. To run a Package without wrapping it in a Product, create a direct installation from the Installs API.

Packages API

Create Packages, import published Packages, add versions, and fetch input schemas.

Import a published Package

Create a Package version

Add another immutable version to an existing OCI-backed Package.

Products API

Wrap a Package into a sellable product.

Offers API

Create private or reusable sales paths for a Product or Package version.

Installs API

Run a Package version as a direct installation.

Products

Turn a Package into a sellable catalog item.

Package format

Author package.k, Input, and @ui annotations.

Installation repositories

See how a Package version materializes for each install.

Offers

Send customers a short URL into the generated install wizard.

Installations

Package authoring

Repository delivery

Automation

Package first, deployment second

What a Package owns

Package, Product, Offer

Input schemas

API workflows

Import a published Package

Add versions to an imported Package

API

Packages API

Import a published Package

Create a Package version

Products API

Offers API

Installs API

Products

Package format

Installation repositories

Offers

​Package first, deployment second

​What a Package owns

​Package, Product, Offer

​Input schemas

​API workflows

​Import a published Package

​Add versions to an imported Package

​API

Packages API

Import a published Package

Create a Package version

Products API

Offers API

Installs API

​Related topics

Products

Package format

Installation repositories

Offers

Package first, deployment second

What a Package owns

Package, Product, Offer

Input schemas

API workflows

Import a published Package

Add versions to an imported Package

API

Related topics