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.

KhalOS uses two package managers on purpose. The app-kit workspace (the @khal-os/* framework packages and the khal CLI) is a pnpm monorepo. Each generated app/service/workflow repo is a bun workspace. Knowing which tool runs where is the only setup detail that trips up first-time contributors.

​
TL;DR

pnpm

For the @khal-os/* SDK workspace. pnpm install, pnpm build, pnpm typecheck, pnpm lint.

bun

For generated app, service, and workflow repos. bun install, bun run build, bun run typecheck.

​
Node version and CLI channel

Install Node 20 or newer. The @khal-os/* packages target modern Node and bun itself installs cleanly on 20.x. If you use nvm, run nvm use inside any repo that ships an .nvmrc. The khal binary comes from @khal-os/app-kit on npmjs. Fresh FDE installs should use @latest; use @next only when a release owner explicitly asks you to validate an unreleased CLI fix. 
node --version   # v20.x or newer
pnpm --version   # any recent release
bun --version    # 1.x
npm install --global @khal-os/app-kit@latest
khal --version

​
The SDK workspace — pnpm

The SDK workspace ships the four framework packages your pack will depend on: @khal-os/sdk, @khal-os/ui, @khal-os/types, and @khal-os/app-kit (the khal CLI). It uses pnpm and Turbo under the hood. 
pnpm install        # install workspace deps
pnpm build          # turbo run build — build every package
pnpm typecheck      # turbo run typecheck across the workspace
pnpm lint           # biome check
pnpm lint:fix       # biome check --write .
You usually don’t need to run these yourself: the shared packages publish from CI to npmjs, and your pack consumes them as ordinary npm dependencies. Install them here only if you’re debugging an SDK issue or running a local snapshot of the SDK against your pack.

​
Pack repos — bun

Every generated app, service, or workflow repo uses bun as both its package manager and its runtime. bun install is fast, workspaces are first-class, and the bundled khal new templates already match the toolchain the app-kit expects. 
bun install         # install pack deps
bun run build       # build the frontend package
bun run typecheck   # type-check all workspaces
bun run lint        # biome lint
bun run test        # run tests (if present)
Don’t cross the streams. Running pnpm install inside a pack-* repo, or bun install inside the SDK workspace, will produce a lockfile the other tool ignores — and the next person on the repo will have to untangle it. When in doubt, check which lockfile is already committed.

​
Verifying your setup

After you’ve cloned the workspace, pick one of each and confirm both install cleanly:
1

SDK workspace

cd repos/app-kit
pnpm install && pnpm build
pnpm build should finish with every package green in the Turbo summary.
2

A generated app repo

khal new app hello-fde
cd hello-fde
bun install && bun run build && bun run typecheck
The generated repo should build cleanly, then pass khal install . --target dev --dry-run --json before any real target mutation.
Split terminal showing pnpm install in app-kit on the left and bun install in a generated app repo on the right, both finishing green.

​
Next steps

Build your first pack

Scaffold a new pack with khal new app <name> and get a “Hello FDE” component shipping.

Pack anatomy

A directory-level tour of everything inside a pack — manifest, frontend package, backend service, Helm chart, CI.