What is Khal OS?

Khal OS is a browser-based, macOS-inspired operating shell where packs — self-contained apps — run side-by-side for humans and agents. You author packs against the @khal-os/* SDK, wire them over NATS, and ship them into customer organisations through a release pipeline and catalog you’ll meet below.

Pack architecture: frontend package + optional Bun service + Helm chart, consumed by the khal-os shell

A pack is the unit of everything

Every pack is the same three things — a frontend package, an optional Bun service, and a Helm chart — declared together in khal-app.json and consumed by the shell at runtime. Some packs use only the frontend. Others wire up a full backend. A few bundle several frontends under one manifest.

Frontend-only (pack-settings)
Full-stack (pack-terminal)
Bundle (pack-hello)

khal-app.json

{
  "$schema": "https://raw.githubusercontent.com/khal-os/app-kit/dev/packages/types/src/khal-app-schema.json",
  "id": "settings",
  "name": "Settings",
  "version": "1.0.0",
  "description": "Desktop settings — appearance, services, SSH keys, keyboard shortcuts, system configuration.",
  "author": "Namastex",
  "permissions": ["nats:subscribe", "nats:publish", "system:clipboard"],
  "kind": "app",
  "requires": {}
}

No backend block. Scaffolds UI only. Installs from the reviewed git repo/ref.

khal-app.json

{
  "$schema": "https://raw.githubusercontent.com/khal-os/app-kit/dev/packages/types/src/khal-app-schema.json",
  "id": "terminal",
  "name": "Terminal",
  "version": "1.0.0",
  "description": "PTY terminal emulator for KhalOS with NATS-bridged stdin/stdout",
  "permissions": ["pty:spawn", "nats:publish", "nats:subscribe"],
  "kind": "app",
  "backend": {
    "image": "ghcr.io/khal-os/pack-terminal-service",
    "helmChart": "oci://ghcr.io/khal-os/charts/pack-terminal",
    "env": { "KHAL_PTY_SHELL": "/bin/bash", "KHAL_NATS_URL": "nats://nats.khal-system.svc:4222" },
    "ports": [8002]
  }
}

Frontend useNats() subscribes to PTY output; the service owns the PTY and publishes stdout.

khal-app.json

{
  "$schema": "https://raw.githubusercontent.com/khal-os/app-kit/dev/packages/types/src/khal-app-schema.json",
  "id": "hello",
  "name": "Hello Bundle",
  "version": "1.0.0",
  "description": "KhalOS Hello demo bundle — 4 frontend apps + voice engine",
  "apps": [
    { "id": "hello-console",        "name": "Hello Console",       "kind": "app" },
    { "id": "hello-agent-manager",  "name": "Hello Agent Manager", "kind": "app" },
    { "id": "hello-flow-designer",  "name": "Hello Flow Designer", "kind": "app" },
    { "id": "hello-sac",            "name": "Hello SAC",           "kind": "app" }
  ],
  "backend": {
    "image": "ghcr.io/khal-os/pack-hello-voice-engine",
    "helmChart": "oci://ghcr.io/khal-os/charts/pack-hello",
    "env": { "NATS_URL": "nats://nats.khal-system.svc:4222", "HELLO_VOICE_PORT": "8000" }
  }
}

A single manifest declares four frontends plus one shared service. Ship a suite as one pack.

See Example packs for the full reference list, and khal-app.json schema for every field.

The platform contracts

Every pack consumes a handful of platform contracts. You don’t build them — you call them.

Capability	Your surface
Auth	`useKhalAuth()` returns `{userId, orgId, role, permissions, loading}`
Window management	The shell launches, sizes, persists, and restores your pack’s windows
NATS	`useNats()` gives you a bridged client; subjects are scoped to your pack’s namespace
Services	`useService()` calls into your own backend service over NATS
Secrets and config	Declare `env[]` entries in `khal-app.json`; the platform injects values at install time
Multi-tenant isolation	Every pack runs inside its org’s boundary — permissions, data, NATS subjects

Agents are peers

Every pack exposes the same SDK to agents and humans. An agent can open your pack, drive its UI, and call its services — no separate API surface.

Packs are composable

Packs can publish to NATS subjects other packs subscribe to. A notes pack that emits changes is readable by a search pack, a voice pack, a summarizer pack — without coordination.

The release pipeline

From git push to a shipped artifact, the pipeline is the same for every pack:

PR to `dev` or `main`

ci.yml runs typecheck, lint, test, helm lint, and validates khal-app.json against the schema. All four gates must be green before merge.

Merge to `main`

release.yml reads the version from package/package.json, tags v${VERSION}, and cuts a GitHub Release with auto-generated notes. This is the publish trigger.

Release source is reviewed

App source: reviewed git repo/ref plus khal-app.json.
Service (if declared): CI may publish a Docker image such as ghcr.io/khal-os/pack-<name>-service:<version>.
Chart (if declared): CI may publish an OCI chart such as oci://ghcr.io/khal-os/charts/pack-<name>:<version>.

See Publish your pack for the CI workflow map and failure modes.

The catalog

Reviewed app sources are indexed by the platform’s catalog — the component that turns a git repo/ref and manifest into a one-click install for customer admins. From the platform side:

Every app is registered with its manifest, version, and permissions after review/release.
Customers browse the catalog per-organisation, see the packs they’re entitled to, and install them with one action.
Cross-org distribution is the catalog’s problem, not the FDE’s. You publish; the catalog routes.

On the FDE side, this means: do a good job on khal-app.json (accurate permissions, clear env[], real description), prove khal install ... --dry-run, and your app can land cleanly in the target catalog. See Customer install for the customer-side handoff contract — what you hand over after review/release.

Where the automagik toolchain fits

Khal OS is where packs run. The automagik toolchain is how you build them faster:

genie

Wishes in, PRs out — autonomous agent teams that scaffold and iterate on packs against the template.

omni

Omnichannel messaging. Agents inside your packs speak Slack, WhatsApp, Discord, email — one SDK.

rlmx

A research-grade reasoning loop for packs whose agents need to think before they act.

Automagik is how you build. Khal OS is where it runs. Every pack you’ve seen on this page was scaffolded, iterated, or refactored with the automagik tools.

Clone the workspace

Get the khal-os workspace onto your machine.

Your first pack

Scaffold, run, and ship a pack end-to-end.

Documentation Index

​A pack is the unit of everything

​The platform contracts

Agents are peers

Packs are composable

​The release pipeline

​The catalog

​Where the automagik toolchain fits

genie

omni

rlmx

​Next

Clone the workspace

Your first pack

A pack is the unit of everything

The platform contracts

The release pipeline

The catalog

Where the automagik toolchain fits

Next