Skip to main content
Once your pack is published, a customer admin installs it into their Khal-OS instance. This page intentionally stays thin: the FDE’s job ends at publish; the customer’s job begins at install. What follows is the handoff contract.

​
What the customer needs from you

The install artifact

  • Helm chart OCI URL (for full-stack packs): oci://ghcr.io/khal-os/charts/pack-<name>
  • Version (the tag from your last release, e.g., v1.2.0)
  • npm package name (frontend-only packs): @khal-os/pack-<name>@<version>

​
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 injects env, starts the service pod, and loads the frontend npm package into the shell on next launch.

​
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.