Core concepts

Karta has a small, consistent vocabulary. Learn these eight terms and every other page reads easily.

Agent harness

The agent runtime — Claude Code, OpenCode, deepagents. It owns tools, MCP, memory, context, and the agentic loop. Karta does not reinvent it.

Harness application

The deployable unit: a folder that configures a harness (.claude/ + CLAUDE.md, agents, skills). In code and the API it’s called a project.

Session

A lightweight orchestration handle — metadata, participants, current agent, pending approvals. It holds no messages; the harness does.

Participant

A human or AI actor in a session. Many can share one session; each message is attributed to its sender.

Agent

A thin wrapper over an agent definition discovered from the harness (.claude/agents/*.md). Sessions route between agents and hand off.

Gateway

Event ingestion and fan-out. Delivers messages to all participants — in-process, or across Karta instances over HTTP.

Release

An immutable, versioned snapshot of a harness application, materialized from a published artifact. Activation is a pointer flip.

The two planes

The data plane runs agent code; the control plane holds identity, money, and audit. Separated by a trust boundary.

How they fit together

   end user / SDK ─(kt_live_… key or session token)─▶  DATA PLANE (karta-python)
                                                          │  validates key, checks budget
                                                          │  resolves session + release
                                                          ▼
                                                       HARNESS  (Claude Code / OpenCode)
                                                          │  runs the agentic loop,
                                                          │  streams typed events
                                                          ▼
                                                       streamed back as SSE
                                                          ▲
                          CONTROL PLANE (karta-web) ──────┘  key validation · usage · BYOK
                          identity · budgets · billing · webhooks · audit

A request carries a key, the data plane validates it and checks the budget, resolves (or creates) a session, hands the turn to the harness, and relays the harness’s typed event stream back to the caller. Usage is metered to the control plane afterward. Walk through it in Architecture → request lifecycle.

The mental model that matters most

Karta delegates; it does not duplicate. The harness is the single source of truth for conversation history, persistence, resumption, and tool/MCP integration. Karta keeps no second copy — which is why there are no sync races and why an example from the harness’s own docs runs unchanged inside Karta. Everything else — sessions, participants, the gateway, multi-tenancy, releases — is the platform Karta wraps around that delegated core.

Architecture

The two planes, the trust boundary, and the request lifecycle.

Harness applications

What you actually ship, and how a harness is detected.

Sessions & participants

Multi-turn state, multi-party conversations, and attribution.

Streaming events

The typed event model every surface is built on.

Documentation Index