clone-workspace.mdx

title	Clone the workspace
description	How to fetch KHAL source from the right remote: private app/platform repos in Gitea, public docs/app-kit/desktop exceptions on GitHub.

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.

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

Use the internal Gitea credentials or SSH key from onboarding. For CLI checks:

```bash
tea login list
tea whoami
```

For SSH remotes, register your public key in the internal Gitea UI before cloning.

```bash git clone cd ```

Use GitHub only for the public docs repo and the GitHub-hosted app-kit/desktop exceptions.

```bash ./init.sh ```

If the repo ships an `init.sh`, run it after cloning. Private app repos may instead use the generated app workflow from [FDE CLI quickstart](/dev/fde-cli-quickstart): `bun install`, `bun run build`, `bun run typecheck`, then `khal install ... --dry-run`.

<Callout type="tip">
  Run `./init.sh --help` to see the available options, including `--dry-run` (preview actions) and `--verbose` (extra debug output).
</Callout>


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.

Which package manager to use where — `pnpm` vs `bun` — and how to get the whole workspace compiling. Scaffold from the template, rename, edit, build — you'll have a running pack by the end of the page.

Troubleshooting

Confirm your internal Gitea account, SSH key, or credential helper. Run `tea login list`, `tea whoami`, and `git ls-remote ` without pasting tokens into logs. Upgrade to git 2.30 or newer. Older git versions don't honor the submodule flags `init.sh` relies on. Use the SSH clone URL from the internal Gitea UI, then verify:

```bash
git remote -v
git ls-remote origin
```

What's next

pnpm + bun + the node versions your workspace actually needs. Scaffold an app with `khal new` and run the local proof loop.