> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# How Karta works

> What happens when a request reaches your agent on Karta - durable kartas, per-session isolation, the request path, and the separation between running agents and managing them.

Karta runs your [agent](/concepts/harness-applications) as durable kartas and
exposes it through one uniform API. You push an agent project; Karta builds an
immutable [release](/concepts/releases), serves it, routes each turn into the
right karta, runs that turn in a per-session isolated runtime environment,
streams the result back as [typed events](/concepts/streaming-events), and
meters what it costs. This page is the mental model for everything in between.

## The request path

<Steps>
  <Step title="Authenticate">
    A client calls the API with an `Authorization: Bearer` credential - a
    `kt_live_...` [API key](/platform/api-keys) from your backend, or a short-lived
    [session token](/security/session-tokens) from an end user's browser.
  </Step>

  <Step title="Check the budget">
    Karta validates the credential and checks your org's
    [budget](/platform/usage-and-budgets). If a cap is already exhausted it
    returns **402 Payment Required** before running anything - no surprise bills.
  </Step>

  <Step title="Resolve the session & release">
    Karta resolves the [session](/concepts/sessions-and-participants) (creating
    one if needed), resolves the durable karta it belongs to, confirms both are
    inside your organization boundary, and pins new sessions to the agent's
    currently active release.
  </Step>

  <Step title="Run the harness in isolation">
    Karta hands the turn to the harness running in a per-session isolated
    runtime environment. The harness runs the agent loop - tools, MCP, memory -
    and emits typed events.
  </Step>

  <Step title="Stream back">
    Karta relays those events to the caller as they happen (SSE), pausing for
    [approval prompts](/api-reference/inputs) when the agent needs permission to act.
  </Step>

  <Step title="Meter">
    When the turn completes, Karta records token and cost
    [usage](/platform/usage-and-budgets) against your budget.
  </Step>
</Steps>

## Per-session isolation

Every session runs in a **per-session isolated runtime environment**. One karta
cannot see another's filesystem, processes, or memory, and a misbehaving or
prompt-injected karta is confined to its own short-lived execution environment.
That environment is created for the session and torn down after it, while
durable workspace state is preserved only through the karta's own storage
boundary.

<Note>
  Embedding Karta in your own process instead? See the two isolation models in
  [Multi-tenancy](/concepts/multi-tenancy).
</Note>

## Running agents vs. managing them

Karta separates the agent runtime from account-management systems. Security and
platform teams should look for this boundary in anything that runs agent code:

<Columns cols={2}>
  <Card title="Agent runtime" icon="play">
    The request path: sessions, harness execution in isolated runtime
    environments, release serving, streaming, and request-time budget
    enforcement. This is where agent code actually runs.
  </Card>

  <Card title="Management systems" icon="shield-halved">
    The system of record: identity, team membership and roles, API keys, usage
    metering and budgets, billing, BYOK provider keys, outbound webhooks, and
    the audit log.
  </Card>
</Columns>

The two sides are separated by a trust boundary, so **the runtime that runs
agent code does not hold billing, identity, or account-management state.** A
compromise of a running agent - the highest-risk surface on any agent platform

* cannot by itself reach your billing, your team's credentials, or another
  tenant's data.

## The harness owns conversation state

The harness owns conversation history, persistence, resumption, and tool/MCP
integration. Karta's [session](/concepts/sessions-and-participants) is a
lightweight handle over it - metadata, participants, the current sub-agent, and
pending approvals. Karta can record transcripts for inspection and export, but
the session record itself is not the transcript store.

Because history lives in the harness, resuming a session continues where it
left off. Karta keeps the harness's own session model instead of converting
history into Karta session records.

## Streaming is the primitive

Every entry point is event-streamed. A non-streaming request accumulates the
same [typed events](/concepts/streaming-events) (text, tool use, reasoning,
approvals, errors) into one response. Build real-time UIs directly, or collect
the final result; it is the same underlying model.

## Read next

<CardGroup cols={2}>
  <Card title="Agents" icon="folder-tree" href="/concepts/harness-applications">
    What you actually ship, and how a harness is detected.
  </Card>

  <Card title="Releases" icon="box-archive" href="/concepts/releases">
    Immutable snapshots, atomic activation, and instant rollback.
  </Card>

  <Card title="Multi-tenancy" icon="users" href="/concepts/multi-tenancy">
    Isolation models for embedded and hosted deployments.
  </Card>

  <Card title="Streaming events" icon="wave-pulse" href="/concepts/streaming-events">
    The typed event model every surface is built on.
  </Card>
</CardGroup>