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.

A pack is a small repository with a fixed shape. Every file has one job. Learning the shape once means you can read any pack-* repo later and know exactly where to look.

​
The tree

This is the layout you get when you scaffold from the template: 
.
├── khal-app.json          # Manifest (validated by @khal-os/types)
├── package/               # Frontend bundle source
│   ├── src/index.tsx      # Default export: React component
│   ├── tsup.config.ts
│   └── package.json
├── service/               # (Optional) backend pod
│   ├── src/index.ts       # Bun HTTP server + NATS subscription
│   ├── Dockerfile
│   └── healthcheck.sh
├── helm/                  # Helm sub-chart for the service
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
└── .github/workflows/     # CI + release/build automation
Pack directory tree labeled with the runtime role of each file — manifest, frontend package, backend service, Helm chart, CI workflows.

​
What each directory does

The declarative contract between your pack and the KhalOS platform. It names the pack, lists permissions, declares services and windows, and points the shell at the frontend package to load. The schema is enforced by @khal-os/types at build time, so a broken manifest fails CI before it can be published.Every field — required and optional — lives in the khal-app.json reference.
The React surface of your pack. package/src/index.tsx default-exports a component; tsup.config.ts produces CJS + ESM + .d.ts bundles for the platform build/install path. The app identity is the git repo/ref plus khal-app.json, not a frontend npm package.
The long-running process for packs that need one — a Bun HTTP server, a NATS subscriber, a background worker. service/src/index.ts is the entry; Dockerfile is multi-stage; healthcheck.sh is a TCP probe used by Kubernetes. Delete the whole directory for frontend-only packs — CI will skip the Docker build automatically.
A packaged Helm chart that deploys your service/ image. Chart.yaml names the chart, values.yaml sets defaults (image repository, ports, resources), and templates/ renders the Kubernetes objects. You don’t hand-roll infrastructure — the chart is parameterized and the platform fills in the blanks.
Workflows handle everything from PR validation to release metadata and backend artifacts. Every push or tag triggers the right one automatically:
WorkflowTriggerWhat it does
ci.ymlPull requestLint, typecheck, build, test
release.ymlPush to main or tagTags/releases the reviewed git revision; backend image/chart publishing is repo-specific
docker-build.ymlPush to dev / mainBuilds and pushes the service image (:next / :latest)
helm-release.ymlTag v*Packages the chart and pushes it to oci://ghcr.io/khal-os/charts
Full release walk-through in Publish your pack.

​
The contract in one sentence

You declare the shape; the platform provides the runtime. You write the manifest, the component, and (optionally) the service. The platform handles NATS connections, secrets, networking, installation, and deployment. That boundary is what keeps packs portable and the platform upgradeable.

​
Next steps

khal-app.json reference

Every manifest field — required and optional — with examples pulled from real packs.

Publish your pack

The git-native path from commit to reviewed install source — branches, tags, dry-runs, and handoff.