FAQ

Short answers. If a page and khotan help disagree, trust the CLI.

What is Khotan?

An agent-native workspace for apps, pipelines, files, context, integrations, and databases. It packages that infrastructure on one platform so using a tool — and sharing it — is as easy as making it. See Basics.

Do I need the CLI?

No. The public CLI, @khotan/cli, is a thin adapter over /api/v1. Anything the CLI can do, you can do over HTTP. Use the CLI from a terminal or an agent; call the HTTP API directly when you want raw HTTP.

What is first-class in a workspace?

Apps and pipelines are the principal deployables. Then files, context, integrations, and databases. See Concepts.

How is the repo laid out?

One GitHub monorepo per organization (Bun workspaces and Turborepo). Creating an app, pipeline, or database writes into that repo. Apps live under apps/deployments/, pipelines under apps/pipelines/, shared code under packages/ — including packages/databases/<alias>/. The root holds the workspace manifest, lockfile, and shared agent skills.

How do I get the code?

khotan apps get <appId> or khotan pipelines get <pipelineId>. The record includes repo.clone (HTTPS, SSH, GitHub CLI) and repo.subdirectory. Databases live in the same repo — there is no clone URL on khotan databases get. khotan apps source / khotan pipelines source download the subdirectory as files, without git. See Concepts.

How do I authenticate?

An organization-scoped API key, not a session cookie. Never commit a key. See CLI auth or API authentication.

How do I know which organization I am talking to?

khotan whoami, or GET /api/v1/me. If a listing returns unfamiliar names, stop. See errors.

Is there a per-workspace API host?

No. The API base URL is the same for every account. The key carries the organization. A workspace subdomain in a browser is browser tenancy.

How do I tell Khotan something is missing?

Run khotan feedback submit, or call POST /api/v1/feedback. Use it for a feature request, a product direction, a docs gap, or a bug. Any API key can send feedback, including a read-only one, and it changes nothing in your workspace. See Send feedback to Khotan.

How should an agent read these docs?

Fetch llms.txt instead of scraping HTML. Use search.json to look something up. See agents.