Skip to main content

Documentation Index

Fetch the complete documentation index at: https://akua-1dce587a.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

An offer is a shareable URL (akua.dev/i/<hash>) that takes a customer straight into the install wizard for a product. The wizard is generated entirely from the product’s Akua Package: the input schema, docstrings, and any @ui(...) annotations you have added. The formal resource is called an Offer. The colloquial term “install link” still refers to the short hash URL a customer clicks. (CEP-0026)

​
The flow

When you publish a new Package version, Akua exports its input schema and caches the result. Every offer link reads from that cached schema, with no export round-trip on the hot path. (CEP-0026)

​
What the install wizard renders

The wizard is JSON-Schema-driven. Each property becomes a field; x-ui extensions control presentation:
  • order: numeric position in the form (lower = earlier)
  • group: section header the field is grouped under
  • widget: field renderer hint ("slider", "password", "textarea", "select")
  • placeholder: placeholder text for the input
  • min / max: numeric bounds, also used by sliders
A package.k schema like this: 
schema Input:
    @ui(order=10, group="Identity")
    appName: str
    """Application name. Lowercase, hyphen-separated."""

    @ui(order=20, group="Identity", placeholder="app.example.com")
    hostname: str
    """Public hostname. Must be a valid RFC 1123 DNS name."""

    @ui(order=30, group="Capacity", widget="slider", min=1, max=20)
    replicas: int = 3
    """Number of replicas."""
renders as a wizard with:
  • Identity section
    • Application name field with the docstring as help text
    • Public hostname field with app.example.com placeholder
  • Capacity section
    • Number of replicas slider, range 1–20, default 3
Field labels come from the property name (sentence-cased); help text comes from the KCL docstring.

​
Pre-filled and locked fields

Offers can carry pre-filled input values (field_values). Three independent properties apply to each field:
PropertySourceCustomer sees
Pre-filledfield_values present in the offerForm renders with the value populated
Lockedfield_values[k].locked: trueRead-only with a lock icon; customer cannot override
Sensitivex-ui.sensitive: true on the Package schemaValue visually masked (••••••) regardless of editability
A license key is typically pre-filled, locked, and sensitive. An Akua-approved tier is pre-filled, locked, and not sensitive. A customer-supplied API token is not pre-filled, not locked, and sensitive. field_values are validated against the pinned Package version’s input schema when the offer is created. An offer that would fail at install time cannot be created. (CEP-0026)

​
What an offer carries

A bare offer link points at a product: 
akua.dev/i/<product-slug>
The customer opens it, lands in the wizard, fills in inputs, picks a region, and submits. Akua creates the installation and provisions a package repository for it. Offer links can also pre-fill inputs via query string: 
akua.dev/i/<product-slug>?hostname=app.acme.com&tier=production
Pre-filled fields show up in the wizard already populated; the customer can review and adjust. This is useful for partner-driven flows and for marketplace listings that include a deep link with sensible defaults.

​
Offer access control

Offers support two access patterns:
PatternConfigurationUse case
Public, reusableNo allowed_emails, no max_usesWebsite or marketing link
Per-customer, single-useallowed_emails: [email], max_uses: 1Private customer onboarding
When allowed_emails is set, the customer must authenticate with a matching verified email before the offer resolves. Offers can also carry an expiry date and a maximum number of redemptions.

​
What authors control

The wizard’s quality is the schema’s quality. To make a great install experience:
  1. Write docstrings on every field: they become help text under each input.
  2. Group related fields: use @ui(group="...") consistently; without grouping, fields stack as a flat form.
  3. Order intentionally: use @ui(order=...) for the natural fill order. Required fields first, then optional; identity before capacity.
  4. Pick widgets with intent: a replicas: int field as a slider with min/max reads better than a number input.
  5. Use unions for choices: tier: "startup" | "production" renders as a dropdown automatically.
  6. Add check: blocks for cross-field validation; these produce wizard-side error messages on the customer’s inputs.

​
Updating inputs after install

Once installed, customers can edit their inputs in the wizard (Settings → Inputs), through the CLI, or by pushing to their installation’s git repository. All three update the same inputs.yaml. Akua re-renders on every change.

​
API

Offers API

Create, resolve, revoke, and manage offers.

Order Drafts API

Track customer order drafts and checkout sessions.

Package format

Authoring package.k and @ui annotations.

Marketplace

How products and offers surface to customers.

Customizing inputs

Wizard, CLI, or git push: three views of the same state.

Payments

Customer payment flow and Stripe Connect setup.