KHAL source now follows the split in Source control for KHAL teams: private app/platform repos live in internal KHAL Gitea; public docs, app-kit, and desktop remain on GitHub because of their public docs/SaaS/cloud integration path. For most FDE app work, start from the private Gitea repo URL you received during onboarding, not a GitHub workspace clone.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.
Before you start
You need these installed and signed in before running
init.sh. The bootstrap script exits early with a clear message if anything is missing.| Requirement | Why | Check |
|---|---|---|
git ≥ 2.30 | Submodule features required by init.sh | git --version |
| Gitea access | Required for private app/platform repos | tea login list or your configured SSH key |
| Node 20+ | @khal-os/* packages target modern Node | node --version |
pnpm | Workspace package manager for the SDK | pnpm --version |
bun | Runtime + package manager for generated app/service/workflow repos | bun --version |
Clone and bootstrap
Authenticate with KHAL Gitea
Use the internal Gitea credentials or SSH key from onboarding. For CLI checks:For SSH remotes, register your public key in the internal Gitea UI before cloning.
Clone the repo you are working on
Bootstrap the workspace
init.sh, run it after cloning. Private app repos may instead use the generated app workflow from FDE CLI quickstart: bun install, bun run build, bun run typecheck, then khal install ... --dry-run.Run
./init.sh --help to see the available options, including --dry-run (preview actions) and --verbose (extra debug output).
What you get
After cloning, keep the repo on its authoritative remote. For private app/platform work that is KHAL Gitea. For docs/app-kit/desktop exceptions that may still be GitHub. Do not publish private repo URLs, tokens, credential-helper output, or internal host details in public docs/issues.Install dependencies
Which package manager to use where —
pnpm vs bun — and how to get the whole workspace compiling.Build your first pack
Scaffold from the template, rename, edit, build — you’ll have a running pack by the end of the page.
Troubleshooting
Gitea clone fails
Gitea clone fails
Confirm your internal Gitea account, SSH key, or credential helper. Run
tea login list, tea whoami, and git ls-remote <private-khal-gitea-repo-url> without pasting tokens into logs.`init.sh` aborts on git version
`init.sh` aborts on git version
Upgrade to git 2.30 or newer. Older git versions don’t honor the submodule flags
init.sh relies on.I prefer SSH remotes over HTTPS
I prefer SSH remotes over HTTPS
Use the SSH clone URL from the internal Gitea UI, then verify:
What’s next
Install dependencies
pnpm + bun + the node versions your workspace actually needs.
Your first pack
Scaffold an app with
khal new and run the local proof loop.