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.

This is the end-to-end loop on one machine: an operator runs Karta, an app developer ships a support bot, and an end user chats with it through a browser widget — replies streaming token by token. No AWS, no account. It mirrors the runnable examples/support-bot-demo.

​
The cast

Operator

Runs karta serve — the platform host.

App developer

Authors and registers the support bot.

End user

Opens a chat widget in the browser and talks to the bot.
Browser ──HTTP──▶ web server (:5050) ──proxy──▶ karta serve (:8000) ──▶ Claude Code (the bot)

​
1. The harness application

Our bot is Beans, the support assistant for a fictional roaster. The whole app is two files.
app/CLAUDE.md
# Beans — Karta Coffee Co. support assistant

You are Beans, the friendly support assistant for Karta Coffee Co.

- Warm, concise, a little playful (one coffee pun per reply, max).
- Greet a brand-new conversation with a short hello.
- Help with orders & shipping (2–3 business days; free over $35),
  our roasts (Sunrise, Midnight, Decaf Dusk), returns (30 days, unopened),
  and brewing tips.
- If you don't know something order-specific (like a tracking number), say so
  honestly and offer a human.
- Keep replies to 1–3 sentences unless asked for detail.
app/app.py
from karta import Karta

# `karta serve` imports this `app` (see entry_point in karta.toml).
app = Karta()
app/karta.toml
entry_point = "app:app"
buildpack = "python"
That’s a complete, deployable harness app. CLAUDE.md is the agent; karta.toml tells Karta how to load it.

​
2. Operator: run Karta

karta serve --port 8000
This stands up the HTTP session API on :8000 — the uniform surface every Karta project speaks.

​
3. Developer: register the app

karta project add ./app support-bot
karta project list      # confirm "support-bot" is registered
The bot is now a named project the server can run. See Projects & sessions.

​
4. End user: a streaming chat widget

A tiny web server hosts the widget and proxies to Karta, so the browser only ever talks to your origin. The two calls it makes:
1

Open a session

// Create a session for this visitor:
const res = await fetch("/api/spawn", { method: "POST" });
const { session_id } = await res.json();
// → server-side: POST http://localhost:8000/v1/sessions { metadata: {...} }
2

Send & stream replies

const res = await fetch("/api/message", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ session_id, text: userText }),
});
// → server-side: POST /v1/sessions/{id}/messages { text, stream: true }

// Read the SSE stream and append text deltas to the reply bubble:
const reader = res.body.getReader();
const decoder = new TextDecoder();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  // parse `event: text` frames and append data.part.text
  bubble.textContent += extractText(decoder.decode(value));
}
The widget reads the SSE stream and grows the reply bubble token by token — exactly what the Messages endpoint emits with stream: true.

​
5. Try it

Open the widget in a browser. Beans greets you, and a conversation flows: 
You:   Hi! What roasts do you have?
Beans: Welcome! ☕ We've got Sunrise (light, citrusy), Midnight (dark,
       chocolatey), and Decaf Dusk (smooth, caffeine-free). Anything catch
       your eye?
You:   Do you ship free?
Beans: Orders over $35 ship free, and most arrive in 2–3 business days.
Multi-turn context holds because each message reuses the same session_id — and the history lives in the harness, not the widget.

​
What you just exercised

  • A harness application (CLAUDE.md + karta.toml) with zero Karta-specific agent code.
  • The operator → developer → end user persona split, locally.
  • The uniform session API and SSE streaming that a real frontend builds against.

​
Where to take it next

Add a specialist agent

Hand billing questions to a dedicated agent.

Add a skill

Give Beans real order-lookup capability.

Deploy it for real

Publish a release behind a project URL.

Front it with the OpenAI SDK

Point an existing client at your project.