KhotanalphaMarkdown

Concepts

The terms that hold across Khotan, whichever way you operate it.

A workspace holds apps, pipelines, files, context, integrations, and databases. Apps and pipelines are the principal deployables. Organization, keys, and the CLI/API relationship are how that workspace is scoped and addressed.

Alongside those runnable things sits the project: one contract, and the spec that says what delivering it means. See Projects.

Organization

Work happens inside an organization. A key is bound to one organization and one role. No request names an organization, and no request can widen its own scope.

Confirm which organization you are talking to before you change anything: khotan whoami on the CLI, or GET /api/v1/me over HTTP. If a listing returns unfamiliar names, stop. See errors.

Workspace

A Khotan workspace is a monorepo: one GitHub repo per organization, using Bun workspaces and Turborepo. Apps and pipelines each ship independently; they share the repo, the lockfile, and packages.

acme
|-- apps
|   |-- deployments              # apps
|   |   `-- spend-dashboard
|   `-- pipelines                # pipelines
|       `-- sync-odoo
|-- packages
|   `-- databases                # shared Drizzle packages
|       `-- orders
|-- package.json
|-- bun.lock
|-- turbo.json
`-- AGENTS.md

Creating an app, pipeline, or database writes those assets into this repo. Apps land under apps/deployments/<slug>/. Pipelines land under apps/pipelines/<slug>/. Each database is a workspace package at packages/databases/<alias>/ (@repo/<alias>-db). The root holds the workspace manifest, the lockfile, Turborepo, and shared agent skills.

To clone the repo, get an app or a pipeline:

khotan apps get <appId>
khotan pipelines get <pipelineId>

The record includes repo.clone — HTTPS, SSH, and gh repo clone — plus repo.subdirectory, which locates that resource in the shared repo. Databases live in the same repo; khotan databases get does not return a clone URL. khotan apps source and khotan pipelines source download the subdirectory as a file listing, without git. khotan status maps every subdirectory to its resource. See workspace.

Files, context, and integrations are first-class in the workspace — they are not extra top-level packages.

CLI and HTTP API

The public CLI, @khotan/cli, is a thin adapter over the Khotan /api/v1 HTTP API. It adds nothing the API cannot do — it makes the same operations ergonomic for humans and agents. Anything the CLI can do, you can do over HTTP.

The API base URL is the same for every account and every workspace. There is no per-workspace API host: the key carries its organization, and no operation reads the request host. A workspace subdomain in a browser is browser tenancy — it is not how the API is addressed.

Authentication is an API key, not a session cookie. Never commit a key. See CLI auth or API authentication.