# Kapable

> Kapable is an AI-native application platform: organizations sign up, create apps, push code to a built-in Git remote, and the platform builds and hosts them at `{app}.{org}.kapable.run`. Around that core it exposes a REST API for dynamic tenant data tables, object storage, project boards, agent communications (channels/rooms/mailboxes), AI colleagues and their runs, published artifacts, a knowledge substrate, workspaces, per-org secrets, AI provider proxying, wikis, licensing/entitlements, and billing — all scoped per organization, with typed TypeScript and Rust SDKs in two trust tiers.

## LLM Usage Notes

- Base URL: `https://api.kapable.ai`
- Auth header depends on credential type:
  - API keys (`sk_live_*` / `sk_test_*` / `sk_org_*`) → `x-api-key: sk_live_...`
  - Session tokens (`kses_*`) and RS256 JWTs → `Authorization: Bearer ...`
- All API paths are versioned under `/v1/`. IDs are UUIDs.
- List responses: `{ "data": T[], "total": number }` — paginate with `limit` + `offset` query params.
- Errors are JSON with a non-2xx status. Common shape: `{ "error": { "code": "UNAUTHORIZED", "message": "..." } }`. Some services use a flat variant (`{ "code": 401, "error": "unauthorized", "detail": "..." }`) — always branch on HTTP status, then read the error body.
- Rate limits (per minute, subject to change): auth endpoints 30, write endpoints 120, read endpoints 500.
- Kapable is in closed beta: request an invite at https://beta.kapable.run/ first; the sign-up below then creates your organization.
- Getting a credential (easiest — CLI device flow): install the CLI, run `kapable login`, approve the printed code from any browser (sign in or sign up), done — the session persists locally. Raw API alternative: sign up at https://join.kapable.ai/auth/signup-new-org (creates a new organization), then mint an API key with your session: `POST /v1/auth/api-keys` (SDK: `client.auth.createApiKey(...)`). Device-flow endpoints: `POST /v1/auth/device/code` → user_code + verification_uri, poll `POST /v1/auth/device/token`.
- Full endpoint reference: https://kapable.ai/llms-full.txt · capability summary (JSON): https://kapable.ai/api/features · developer guides (getting started, apps, CLI, runners, conductor, artifacts): https://docs.kapable.ai/llms.txt

## SDKs

Two trust tiers, each in TypeScript and Rust. Pick by the class of credential you hold.

| Package | Language | Credentials | Use |
|---|---|---|---|
| `@kapable/sdk` | TypeScript | `sk_live_`/`sk_test_`/`sk_org_`, `kses_` session, JWT | Customer tier — build apps, call platform capabilities |
| `kapable-sdk` | Rust | same | Same surface, native Rust |
| `@kapable/ops-sdk` | TypeScript | `st_*` service tokens, `sk_admin_`, staff session | Operator tier — platform operations. Rejects customer keys at construction |
| `kapable-ops-sdk` | Rust | same | Same operator surface |

Packages are on the Forgejo registries at `git.kapable.dev` — anonymous read, no token needed:

- npm: add `@kapable:registry=https://git.kapable.dev/api/packages/kapable/npm/` to `.npmrc`, then `bun add @kapable/sdk` (v0.21.1; operator tier: `@kapable/ops-sdk` v0.1.2).
- cargo: add registry `kapable = { index = "sparse+https://git.kapable.dev/api/packages/kapable/cargo/" }` to `.cargo/config.toml`, then depend on `kapable-sdk = { version = "0.18.1", registry = "kapable" }` (operator: `kapable-ops-sdk` 0.1.2). The two SDKs version independently; the colleague/run methods below are TypeScript-only today.

```ts
import { KapableClient } from '@kapable/sdk';
// Session token recommended for your first calls (from signup/login).
const client = new KapableClient({ baseUrl: 'https://api.kapable.ai', token: 'kses_...' }); // `token` = Bearer auth (kses_ session or JWT); use `apiKey` for sk_live_ keys
const me = await client.auth.me();
const stories = await client.board.listStories({ limit: 20 });
```

> ✅ Data API self-service ready (2026-06-10): the `data` module (`/v1/tables`, `/v1/{table}`) is fully reachable with a bare `sk_live_` API key — `read` scope covers GET/SSE, `write` covers row DML + table DDL. A default project is auto-provisioned at signup and auto-resolved, so no `X-Project-Id` header is needed. `GET /v1/projects` lists your projects; pass `project_id` to `POST /v1/auth/api-keys` to mint a key bound to one project. SDKs ≥ 0.3.0 (`@kapable/sdk`, `kapable-sdk`) ship `client.projects.*` alongside `client.data.*`. Note: `board` is still route-mixed for API keys — `/v1/board/plans` works with a key; stories/products need a session.

> ✅ Headless app deploys ready (2026-07-14, IMP-2131): an `sk_org_` org API key can trigger and observe deploys of EXISTING apps — no browser session needed. `POST /v1/apps/{app_id}/deploy` requires the key to carry the dedicated `deploy` scope (an org admin mints one via console → org → API keys, or `POST /v1/orgs/{org_id}/api-keys` with `scopes: ["read","deploy"]`; default `read`/`write` keys deliberately cannot trigger deploys). `GET /v1/apps/{app_id}/deployments` and `GET /v1/apps/{app_id}/deployments/{deployment_id}` need only the `read` scope, so any org key — including the `KAPABLE_ORG_KEY` auto-injected into every deployed app's environment — can poll deploy status. Send the key as `x-api-key: sk_org_...` or `Authorization: Bearer sk_org_...`; the org is resolved from the key (never send `X-Org-Id` with an org key). Poll deployments until status `live` (not `succeeded`); a deploy of code goes: push to your app's Forgejo remote (auto-deploys via webhook) or `POST .../deploy` to redeploy the current tip. App CREATION still requires a `kses_` session.

```rust
use kapable_sdk::KapableClient;
let client = KapableClient::new("https://api.kapable.ai").api_key("sk_live_...").build();
```

## Domains

- `kapable.ai` — marketing site + these docs (`/llms.txt`, `/llms-full.txt`, `/api/features`)
- `docs.kapable.ai` — developer guides (its own `/llms.txt` + `/llms-full.txt`)
- `beta.kapable.run` — closed-beta invite request
- `api.kapable.ai` — customer API base (all `/v1/*` paths)
- `join.kapable.ai` — sign-up (new organization)
- `{org}.kapable.ai` — your org workspace (console at `/console`, wiki at `/wiki`, board at `/board`, chat at `/chat`)
- `{app}.{org}.kapable.run` — your deployed apps (always `.kapable.run`, never `.kapable.ai`)
- `releases.kapable.ai` — release artifact downloads + license activate/validate
- `cli.kapable.ai` — public installer host for the `kapable` CLI
- `git.kapable.dev` — Forgejo: app git remotes + npm/cargo package registries
- `drop.kapable.ai` — burn-after-read drops (API + claim pages)
- `radio.kapable.ai/{slug}` — radio channel listen URLs

**Common mistake:** customer apps live at `.kapable.run`; `.kapable.ai` hosts are platform services.

## On-prem (self-hosted Kapable)

Kapable can be installed on a customer's own server. The documentation is public; the platform
binaries and license are what's gated — an AI assistant can drive the whole install from these
pages, given a license from the Kapable team:

- https://docs.kapable.ai/onprem-overview — what you get, box spec, DNS prerequisites (apex + `*.base` + `*.*.base` wildcards)
- https://docs.kapable.ai/onprem-install — the one-command bootstrap and its 10-node install DAG
- https://docs.kapable.ai/onprem-license — how licensing works (you never handle signing keys)
- https://docs.kapable.ai/onprem-verify — `--seal-check`: your own machine-verifiable proof of a correct install
- https://docs.kapable.ai/onprem-operate — day-2: the idempotent re-run heal, upgrades, backups

Install errors are written to be actionable by AI agents: each names its cause and the corrective action — trust the error text.

## CLI

There is a native command-line client — you do not have to write HTTP calls or use an SDK to work with Kapable from a terminal or an agent shell.

```bash
curl -fsSL https://cli.kapable.ai/install.sh | sh   # installs to ~/.local/bin/kapable, no sudo
kapable auth login --email you@example.com --password '...'
kapable auth me
kapable board stories list --status active
```

- Single binary (linux-amd64, darwin-arm64), rides `kapable-sdk` — same capability surface as the Rust SDK.
- Credential precedence: `--api-key` flag > `KAPABLE_API_KEY` env > stored `[api]`/`[session]` config. For headless agents, set `KAPABLE_API_KEY=sk_org_...` and skip `auth login` entirely.
- `kapable self-update --check` / `kapable self-update` — checks/installs the latest published build without re-running the installer.
- Full command tree + auth details: https://docs.kapable.ai/cli

## Designer on your own Claude subscription (conductor)

Kapable's designer can run its AI turns on your own Mac, inside your own Claude subscription and rate limits. A small daemon takes those turns over an outbound tunnel: `claude-conductor` 0.9.28, on the same public release registry as the CLI, SHA-256 checked on download. The designer's tools still run on Kapable's side, so no repository write credential reaches your machine. Kapable records what a turn cost. Platform AI spend caps do not gate these turns.

```bash
curl -fsSL https://claude.ai/install.sh | bash
curl -fsSL https://cli.kapable.ai/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile   # NOT ~/.zshrc — a non-interactive shell never reads .zshrc, so an agent's later commands fail
claude auth login --claudeai   # your own subscription; a human finishes this one in a browser
kapable login                  # device code — prints a URL + code, opens no browser, safe under an agent
kapable conductor install      # download + SHA-256 check + per-user LaunchAgent + platform registration
kapable conductor status       # want a recent heartbeat AND a reachable daemon
```

- macOS on Apple silicon (`darwin-arm64`) only today. No Linux build and no Intel build exist.
- No `sudo` at any step. The daemon runs as a per-user LaunchAgent (`~/Library/LaunchAgents/dev.kapable.conductor.plist`) and starts at login.
- Judge liveness by heartbeat age. An `online` label can outlive the daemon it describes.
- The `kapable conductor install|setup|status|uninstall` verbs are new. Nobody drove them end to end on a clean Mac yet (2026-08-15), so treat them as the intended path. The daemon artifact is real: we downloaded it, matched its SHA-256, and ran it.
- Nothing here is self-serve yet. The Kapable team creates your org, and the Kapable team points a design session at your conductor. Ask in both directions.
- Remove it with `kapable conductor uninstall`. Your Claude login and the `kapable` CLI stay. Full page: https://docs.kapable.ai/conductor

## Customer API modules (21)

- `auth` (139 endpoints) — orgs, members, invitations, API keys, service tokens, sessions, device flow, apps (create/deploy/logs/env/lanes), custom domains, conductor instances, launchpad
- `workspaces` (17) — sub-org collaboration containers: per-workspace roles, single-use invitations, credential binding (session flows)
- `data` (22) — dynamic tenant tables: DDL + row CRUD, bulk ops, batch, record shares, CSV import/export, SSE row changes
- `projects` (4) — the per-org Postgres schemas the Data API runs inside (default project auto-resolved)
- `store` (9) — object storage: buckets + objects, presigned up/download
- `board` (52) — products, stories, sprints, plans, comments, claims, story event feeds
- `comms` (57) — agents + agent keys, channels, rooms, messages, mailboxes, email, Telegram bridges, todos, SSE feeds — plus the AI-colleague surface: `colleagues` (profiles), `runs` (wake / list / approve / decline; runners poll, claim, report), `runners` (declare, self-register, heartbeat). TypeScript SDK 0.19+ only.
- `knowledge` (46) — knowledge substrate: claims, entities, evidence, edges, pages + casts, search
- `artifacts` (32) — publish self-contained HTML documents, list/read, share links + bundles, annotations, panel ballots + verdicts, brand kit
- `canon` (11) — hosted system of record for human judgment: corpora, gaps, ratification (adopt/seal/supersede are session-only; API keys get 403 by design). Served at `{org}.kapable.ai/canon`.
- `notify` (6) — one-line status sends (`POST /v1/notify/send`) + the unread feed behind the console bell
- `radio` (14) — broadcast channels (Icecast mounts) + persona-rendered, TTS-synthesized announcements; listen at `radio.kapable.ai/{slug}`
- `ai` (9) — AI provider catalog + completion proxy, TTS, org BYO-key settings
- `secrets` (7) — per-org secrets (create/rotate/audit)
- `billing` (5) — billing reads, public plan catalog, checkout/portal
- `wiki` (31) — wiki collections + pages
- `harbor` (12) — releases + licensing (activate/validate, downloads)
- `warrant` (48) — licensing/entitlements: products, plans, APP_ID slot licensing, trials/previews, seller-side customer licenses — canonical base `https://{org}.kapable.ai/warrant/*`; api.kapable.ai also serves the buyer+shop surface (`/v1/shop`, `/v1/my`, `/v1/warrant/*` alias)
- `herald` (6) — the event bus: publish, list/get events, catalog, SSE stream with durable resume
- `tickets` (1) — external ticket intake with no member identity (`POST {org}.kapable.ai/tickets/internal/intake`, `sk_org_` Bearer only)
- `drops` (3) — zero-knowledge burn-after-read secret sharing: hand a credential/secret to a person or agent once. Create encrypts client-side (AES-256-GCM, key on the URL `#fragment` — never reaches the server); claim is public + atomic-burn; status is creator-only. Base host is `https://drop.kapable.ai` (NOT api.kapable.ai). SDK `client.drops.create/claim/status`. Docs: https://docs.kapable.ai/drops

Plus `security` (typed token-tier descriptors) and SSE streaming helpers in both languages. Every route, with its wrapping method and auth requirement, is in https://kapable.ai/llms-full.txt.

## Token tiers

| Token | Prefix | Reaches |
|---|---|---|
| Session | `kses_` | customer tier (operator too if platform staff) |
| Agent key | `ak_` | an AI colleague's own credential: runner offers/claim/report, self-registration, heartbeat |
| Customer API key | `sk_live_` / `sk_test_` / `sk_org_` | customer tier only, scope-gated (`read`/`write`/`admin`) |
| Service token | `st_*` | operator tier (CI/deploy/webhook automation) |
| Admin key | `sk_admin_` | operator tier (platform staff) |
| RS256 JWT | — | customer tier (app SSO consumers) |

## Provenance

Regenerated 2026-09-08 from the Kapable SDK coverage manifest (rebuilt against SDK 0.21.1 source and the verified route inventory; 0 phantom endpoints) plus the published SDK source for the AI-colleague run routes. The customer SDK wraps 527 of 610 SDK-eligible customer endpoints (86.4%); /llms-full.txt documents the wrapped surface.