Skip to main content

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.

Karta offers tenant isolation two different ways, deliberately matched to two different deployment realities. Pick the one that fits how you run.

​
Embedded SDK (KartaHub)

Each (tenant, user) pair gets a fully isolated filesystem workspace (overlayfs, clonefile, or copy, depending on platform) and its own Karta instance and harness. Strong process-and-filesystem isolation, heavier per-tenant overhead. Right for in-process applications. 
from karta import KartaHub

hub = KartaHub("/path/to/karta-root")

# Each (tenant, user) gets its own isolated workspace + Karta + harness:
session = hub.session("acme", "alice", metadata={"topic": "billing"})
response = session.send_sync("Help with invoice #789")

session_b = hub.session("globex", "bob")     # separate workspace entirely
The workspace is materialized from a template directory and torn down on eviction. In customer-facing language this isolated per-user view is called a shadow copy — one materialized, isolated view of a harness application per end user.

​
HTTP server — karta serve

A single shared Karta instance plus a SessionOwnerStore that durably records session_id → organization_id. Access is default-deny: an API key scoped to org A cannot touch org B’s sessions, even by guessing IDs. Lighter weight, right for a shared cloud service. 
  org A key ──▶ /v1/sessions/{id}   ┌─ SessionOwnerStore ─┐
                                    │  sess_1 → org A     │  ✅ A reaches sess_1
  org B key ──▶ /v1/sessions/sess_1 │  sess_2 → org B     │  ❌ 404 (not yours)
                                    └──────────────────────┘

​
Why two models

Embedded wants isolation

In-process apps run untrusted-ish per-user state side by side; filesystem isolation per (tenant, user) is worth the overhead.

Cloud wants efficiency

A shared service wants resource efficiency with auth-enforced scoping — one instance, many orgs, isolation by ownership records rather than by process.

​
The tenancy stack

In the hosted product, isolation nests at three levels, each with a different credential at its boundary: 
┌─ Karta (platform operator) — separate admin plane ───────────┐
│  ┌─ Organization (your org) ─────────────────────────────┐   │
│  │  members + roles; owns API keys, BYOK, budgets        │   │
│  │  ┌─ Shadow copy per (tenant_id, user_id) ──────────┐  │   │
│  │  │  one end user's isolated workspace + session    │  │   │
│  │  └──────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────┘
The org ↔ end-user boundary is enforced by the session token plus session ownership. The end user’s user_id is an opaque blob your backend supplies — Karta keys the shadow copy on it but never introspects it. Format and granularity are your contract. See Personas for the full credential matrix.

​
Persistence

Two distinct stores back all of this:
  • Harness session storage (source of truth) — owned entirely by the harness (e.g. Claude’s JSONL thread files). Karta reads through the harness; it never writes a second copy.
  • Karta metadata — instance and session-ownership records, via KARTA_SESSION_STORE_URL: SQLite (default), PostgreSQL, or S3.