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.

The goal of this page: go from zero to a deployed agent in under 10 minutes. You’ll author a harness application, git push it to Karta, and watch it come alive at a hosted URL with a chat widget — no servers to run, no infra to wire.
Preview. The hosted push-to-deploy experience below — git push karta, a per-project URL, and the embedded chat widget — is Karta’s north-star UX and is rolling out. If you hit a gap, the Develop locally path further down works end-to-end today. See the deploy loop status for specifics.

​
Deploy to Karta

1

Install the CLI

The Karta CLI ships on npm.
npm install -g @karta/cli
2

Create a harness application

A harness application is just a folder. The minimum is a CLAUDE.md that gives your agent its instructions.
mkdir support-bot && cd support-bot
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).
- Help with orders, shipping, our roasts, returns, and brewing tips.
- If you don't know something order-specific, say so and offer a human.
- Keep replies to 1–3 sentences unless asked for more.
That’s a complete, deployable app. The .claude/ directory (sub-agents, skills, settings) and an optional karta.toml are additive — see Project structure.
3

Commit it

Karta deploys what you commit, so put it under git.
git init
git add .
git commit -m "Beans: the support bot"
4

Initialize the project

karta init sets up everything in one step: it signs you in (creating an account if you don’t have one), creates the project, and adds a karta git remote pointed at it.
karta init
# → opens your browser to authenticate / create an account
# → creates project "support-bot"
# → adds git remote 'karta' → https://git.karta.app/<org>/support-bot
5

Push to deploy

Push your commit to the karta remote. Karta packages the app, builds an immutable release, activates it, and assigns the project a stable URL.
git push karta main

Packaging harness application… done
Building release v1 (commit 1a2b3c4)… done
Activating v1… live ✅

Your agent is live:
  https://support-bot.karta.app
6

See it live

Open the project URL — Karta hosts a chat widget on it — or launch it from the CLI:
karta open        # opens https://support-bot.karta.app in your browser
Say hello to Beans. You just went from an empty folder to a hosted, streaming agent. 🎉

​
Iterate

Deploying again is the same git push. Edit CLAUDE.md (or add a sub-agent or skill), commit, and push — Karta builds a new release and flips the project to it. The URL never changes, and in-flight conversations finish on the release they started on. 
# tweak CLAUDE.md, then:
git commit -am "Beans now knows about gift subscriptions"
git push karta main          # → builds v2, activates it behind the same URL
Need to undo a deploy? Rollback is a pointer flip back: 
karta rollback support-bot --to v1
See Releases & rollback.

​
Embed it in your site

The project URL speaks a uniform session API, so your own frontend can drive it. Your backend mints a short-lived, project-scoped session token for each end user, and your widget opens a session with it — your end users never hold an API key. 
# Mint a session token server-side (holds your kt_live_ key):
curl -X POST https://karta.sh/agent_projects/support-bot/session_tokens \
  -H "Authorization: Bearer $KARTA_API_KEY"
You can also talk to your project with an existing OpenAI or Anthropic client — see Consumer adapters.

​
Develop locally

Prefer to iterate before you deploy? Run the harness on your machine with the Python SDK and the karta CLI — no account needed.
1

Install the SDK and a harness

Karta runs on top of a harness, so install one alongside the SDK.
pip install karta-python
npm install -g @anthropic-ai/claude-code   # the harness Karta drives
Prefer OpenCode? Install it (curl -fsSL https://opencode.ai/install | bash) and lay out a .opencode/ directory — Karta auto-detects the harness from your folder.
2

Stream a response

Point Karta at the same folder. Three lines:
app.py
from karta import Karta

app = Karta()                                  # detects CLAUDE.md here
print(app.send_sync("Hi! What roasts do you have?").text)
Or stream events as they arrive:
stream.py
import asyncio
from karta import Karta

async def main():
    app = Karta()
    async for event in app.stream("Hi! What roasts do you have?"):
        if event.type == "text":
            print(event.text, end="", flush=True)

asyncio.run(main())
3

Or skip the code — use the CLI

karta dev gives you a hot-reloading REPL against the current folder, with streaming and approval prompts rendered for you.
karta dev .
karta dev . --message "What roasts do you have?"   # one-shot

​
Add a session

A single send is stateless. Open a session for multi-turn context, tagged with metadata you can look it up by later. 
session = app.session(metadata={"customer_id": "abc123"})
session.send_sync("I need help with my order")
session.send_sync("It's order #12345")        # remembers the thread
Conversation history lives in the harness, not in Karta — so resuming is just looking the session up again. See Sessions & participants.

​
Serve it over HTTP

Wrap the app in a server and you have the same uniform session API your hosted project speaks: 
karta serve --port 8000

curl -N http://localhost:8000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"customer_id": "abc123"}}'
See the API reference and the streaming model for the SSE event shapes.

​
Next steps

Build a support bot

The full walkthrough: operator → developer → end user, with a chat widget.

Define multiple agents

Route between specialists and hand off mid-conversation.

Understand the deploy loop

Ship → serve → consume, releases, and rollback in depth.

Talk to it like OpenAI

Hit your project with the OpenAI or Anthropic SDK, unchanged.