Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.khal.ai/llms.txt

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

Once your app has a reviewed git revision, a customer admin installs it into their Khal-OS instance. This page intentionally stays thin: the FDE’s job ends at a reviewed git handoff; the customer’s job begins at install. What follows is the handoff contract.

​
What the customer needs from you

The install source

  • Git repository URL for the app repo.
  • Branch, tag, or commit that was reviewed and released.
  • Manifest path if it is not the repository root khal-app.json.
  • Backend image/chart references only if the app declares a backend service.
Do not hand off a pack npm package name. App repos are installed from git; @khal-os/sdk, @khal-os/ui, @khal-os/types, and @khal-os/app-kit are framework/CLI dependencies, not customer install artifacts.

​
CLI equivalent

The customer/admin UI and CLI are two views of the same install contract. The FDE dry-run shape is: 
khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared --dry-run --json
A real authorized install omits --dry-run: 
khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared
See FDE CLI quickstart for login and troubleshooting.

​
What the customer needs to configure

If your pack declares env[] entries in khal-app.json, the customer admin supplies values at install time: 
{
  "env": [
    {
      "key": "MY_EXTERNAL_API_KEY",
      "description": "API key for the third-party analytics service",
      "required": true,
      "type": "secret"
    },
    {
      "key": "FEATURE_BETA_UI",
      "description": "Enable the beta UI variant",
      "required": false,
      "default": "false",
      "type": "boolean"
    }
  ]
}
  • Entries with type: "secret" go into the platform’s secret store — the customer pastes a value once, and the platform injects it into your service at runtime.
  • Entries with other types become plain config — readable from the admin UI.
Never hardcode customer-specific values (URLs, tokens, org identifiers) in your pack source. Declare them in env[] so each customer supplies their own.

​
What the customer’s workflow looks like (summary)

An FDE doesn’t run this — but it’s useful to understand what happens on the other side so you can hand off cleanly.
  1. Admin picks your pack from their platform’s install UI (or runs the equivalent CLI command).
  2. Platform pulls the Helm chart from OCI, applies it alongside the shell.
  3. Admin fills in the env[] values the pack declared.
  4. Platform builds or locates the frontend bundle, deploys any declared backend service/chart, injects env, and registers the app for the shell.

​
Versioning and updates

  • Bumping the pack version on main triggers a new chart (see Publish your pack).
  • Customers opt into upgrades through their platform’s upgrade flow — not automatic.
  • If you break the env[] contract (renaming keys, adding required fields), document it in your release notes. Customers need to know before they upgrade.

​
What is NOT your problem

  • How the customer’s platform deploys the chart.
  • How secrets physically land in the container.
  • Pod scheduling, resource quotas, ingress routing.
  • Cross-pack coordination at the cluster level.
Those are platform concerns, not pack concerns. Stay on your side of the line.

​
What’s next

khal-app.json reference

The full manifest schema, including the env[] shape.

Example packs

See reference packs for how to shape env declarations cleanly.