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.

This page is the operating contract for FDE onboarding. The first rule is simple:
Test local first. A change is not ready for shared environments until the FDE can run it in the local loop, understand what is happening, and collect evidence from the CLI.
KhalOS has multiple environment rungs. Do not collapse them into one dev bucket. Each rung has a different purpose, mutation policy, and proof bar.

​
The ladder

StepTarget nameWho uses itRuntime shapePurposePromotion gate
1local / dev-localEvery FDE on their own machinePM2-native local loop from repos/deploy/dev-localBuild intuition, test quickly, debug without blocking anyone elseApp works locally, manifest/env contract is valid, logs explain failures
1amirrored dev-localAgents and maintainersSame PM2-native loop, mirrored on the remote code host over SSHKeep the agent/control server light while still dogfooding the same local loopSame as local, with explicit note that it is a mirror, not shared k8s
2shared devAll FDEs after local validationLocal Kind/k8s dev server from the deploy repoTrain in the shared cluster-like environment and catch integration issuesLocal proof exists; shared deploy succeeds; app is observable and reversible
3customer dev / HMLClient-facing validation, currently Hapvida pathsCustomer-scoped k3s or OCI/HML depending on targetValidate customer-specific settings, secrets, networking, and acceptance flowExplicit customer/stakeholder gate and redacted evidence
4productionOperators onlyOCI/OKE productionStable customer operationHML/stakeholder approval plus rollback plan

​
CLI checkpoint at each rung

Use the same CLI shape at every rung; only the target changes: 
khal context --target dev --text
khal doctor --target dev
khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared --dry-run --json
The FDE should not mutate a shared or customer target until the dry-run is clean and the target identity is obvious. For first-run install/login/scaffold commands, see FDE CLI quickstart.

​
Step 1 — local first

For human FDEs, local means their own workstation. The shape should mirror the deploy repo’s dev-local loop: 
cd repos/deploy
make dev-local
That target is the Tier-1 local loop. It bootstraps env, builds/stages packs, starts KhalOS processes under PM2, and wires local/Tailscale access where available. A good FDE local proof includes:
  • the app repo branch/ref being tested;
  • khal-app.json manifest validation;
  • declared env[] settings, without committed secret values;
  • build/typecheck output;
  • a running shell or app surface;
  • exact logs or status output if anything fails.
App repositories declare settings schema. Real values are supplied through KhalOS App Settings for the selected target. Do not commit customer secrets or concrete local credentials into app repos.

​
Step 1a — mirrored dev-local for agents

When an agent is acting as the FDE companion, it may not run the full local loop on the Hermes/control server. Instead, the agent mirrors the same dev-local behavior on the remote code host over SSH. This is still dev-local semantics: PM2, local state, fast iteration, and FDE-style logs. It is not the shared k8s dev environment. The mirror exists to avoid bloating the agent-only control server while allowing the agent to dogfood the same commands and collect evidence alongside the engineer.

​
Gitea mirror guardrails

The remote code host mirror may be backed by Gitea. Treat that mirror as a transport and execution surface for agents, not as a replacement source of truth for the public docs or app repositories. Do not detach the GitHub/Mintlify deployment path when using Gitea-hosted working copies; record which upstream ref was mirrored, which Gitea ref was exercised, and how to reproduce the same command on a human workstation. A good Gitea mirror proof includes:
  • authoritative Gitea repo and commit/ref;
  • any temporary mirror URL or remote name, without credentials;
  • agent host or SSH alias used to run the mirrored dev-local loop;
  • evidence that the mirrored run used the same manifest/env contract as local FDE work.

​
Step 2 — shared dev after local validation

After local validation, promote to the shared local k8s/Kind dev server. This is where all FDEs train against the cluster-like integration environment. From the deploy repo, the current shared dev path is represented by: 
cd repos/deploy
make dev
This path performs the k8s-oriented deploy flow: preflight, build, image load/import, Helm upgrade, and rollout status. It is intentionally a second step. Do not use shared dev to discover basic local errors.

​
Step 3 — customer dev / HML

Customer-specific environments are stronger gates. For Hapvida dev k3s, the deploy repo exposes a remote k3s path through the hapvida-dev SSH alias. HML/OCI paths may use different kubeconfigs and stronger access policy. At this rung, an FDE should be able to explain:
  • which client/customer is being touched;
  • which secrets/settings were supplied through App Settings or the platform secret store;
  • what changed versus shared dev;
  • who can approve the next promotion.

​
What khal deploy should make obvious

The CLI should behave like a Vercel-style deploy companion, but with explicit environment identity: 
khal deploy <private-khal-gitea-repo-url> --branch <branch> --target local
khal deploy <private-khal-gitea-repo-url> --branch <branch> --target dev
Before mutating anything, the CLI should print:
  • target name and resolved rung (local, mirrored dev-local, shared k8s dev, customer dev/HML, prod);
  • host or control plane it will contact;
  • runtime mechanism (PM2 local loop, Kind/k8s, k3s, OCI/OKE);
  • app manifest identity;
  • env/settings requirements;
  • mutation policy;
  • exact follow-up commands for logs, status, open, rollback, and evidence.
If the CLI cannot resolve those facts, it should stop and tell the FDE what to configure instead of guessing.

​
FDE pal responsibility

KhalDX owns this experience with the platform team: the CLI, docs, and examples must teach the FDE what to do next at every failure point. A great onboarding loop feels like pairing with an engineer who knows the environment ladder and can say:
  • where you are;
  • what is safe to mutate;
  • what evidence proves the step worked;
  • what command to run next;
  • when to ask for platform/operator help.
This page is the contract those tools and guides should converge on.