> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# 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](/basics/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](/cli/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.

```text
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:

```sh
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](/cli/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](/cli/auth/) or [API authentication](/api/auth/).

## What to read next

- [Projects](/basics/projects/) — contracts, specs, revisions, and OpenSpec changes
- [FAQ](/basics/faq/) — short answers to the questions these pages raise
- [CLI](/cli/) — install, authenticate, and operate from the command line
- [HTTP API](/api/) — call `/api/v1` directly, or generate a client from the OpenAPI document
- [Agents](/cli/agents/) — how a coding agent should read these docs (`llms.txt`, `search.json`)