Quickstart

The goal of this page: deploy an agent defined for a supported harness to Karta in under 10 minutes. If you already have a supported harness project, use that folder. If not, scaffold a starter in the harness you want. Karta handles deploy, release activation, the hosted chat page, and the consumer session API. You keep authoring and evaluating the agent in your own repo, harness, and tooling. Run this path first:

npm install -g @karta.sh/cli
karta login                         # device flow, browser approve
karta create support-agent --harness claude-code  # scaffold a starter agent
cd support-agent
karta setup --enable                # configure delivery + flip on the deploy gate
karta deploy                        # push (git) or upload (folder)
karta open                          # open the live hosted chat page

Expected result: karta open opens the hosted chat page for a live release of your agent.

This page is the shortest route to a deployed agent project. If you are choosing between widget, API, existing harness project, operations, or architecture review paths, start with Choose your path.

Deploy to Karta

Install the CLI

The Karta CLI ships on npm.

npm install -g @karta.sh/cli

karta login

karta login prints a one-time code and opens your browser; approve it while signed in to the dashboard. The CLI receives a named, revocable credential - it shows up on your API keys page like any other key - and installs the git credential helper, so git push karta never prompts.

In CI, or anywhere a browser cannot open, set the KARTA_API_KEY environment variable - it overrides the stored config everywhere - or pipe a key: echo $KARTA_API_KEY | karta login --with-token.

Scaffold an agent

karta create support-agent --harness claude-code
cd support-agent

karta create lays down a starter agent in the selected harness format: CLAUDE.md for Claude Code, or AGENTS.md plus the native marker folder for OpenCode, DeepAgents, Goose, or Codex CLI. It also writes karta.toml (the deploy manifest - your agent’s name and deploy gate, plus an [env] table for config it needs) and a .gitignore. It scaffolds with the deploy gate off. --template faq-agent starts from a worked support-agent example instead of the blank skeleton.Other harnesses use the same flow:

karta create support-deep --harness deepagents
karta create ops-goose --harness goose
karta create reviewer-codex --harness codex-cli
karta create support-open --harness opencode

Already have an agent folder from your normal harness workflow? Use that folder instead and run karta setup --enable there.Then configure delivery and turn on the deploy gate:

karta setup --enable

karta setup configures the folder, initializes git when needed, and writes or updates karta.toml. --enable flips on the deploy gate (deploy = true) so the later karta deploy ships it. Without the gate, the agent remains local until you enable deploy.Make the agent yours: replace the contents of the instruction file with your own instructions. For this Claude Code walkthrough that file is CLAUDE.md; for OpenCode, DeepAgents, Goose, and Codex CLI it is AGENTS.md. Paste in a small support agent:

CLAUDE.md

# Beans - Karta Coffee Co. support agent

You are Beans, the support agent for Karta Coffee Co.

- Help with orders, shipping, roasts, returns, and brewing tips.
- Keep replies to 1-3 sentences unless the user asks for detail.
- If you do not know an order-specific fact, say so and offer a human handoff.

The harness’s native config directory (.claude/, .opencode/, .deepagents/, .goose/, or .codex/) is additive. See Agent structure.

Deploy

git add -A && git commit -m "support agent v1"
karta deploy

karta deploy ships your agent. In a git repo, it creates or finds the hosted source repo, wires a karta git remote, pushes your committed HEAD, builds an immutable release, activates it, and streams build progress back, including the live URL when the deploy finishes. Once the remote is wired, git push karta main is the exact equivalent.If you deploy an existing git repo with uncommitted changes, commit or stash them first. Karta deploys the committed HEAD for git-mode deploys.

See it live

karta open

Opens your agent’s hosted chat page - the same widget your customers embed. karta open console opens the agent in the dashboard.

Verify the deploy

Check	Command	Expected result
CLI is authenticated	`karta whoami`	Prints the signed-in account and active organization.
The agent is configured	`karta status`	Shows the agent resolved from `karta.toml` or the `karta` git remote.
Hosted page opens	`karta open`	Opens the live agent page after the first active release.
Dashboard opens	`karta open console`	Opens the agent dashboard page for release, logs, settings, and embed controls.

Exercise the Karta surface locally (optional)

You do not need this to ship, and it does not replace your harness’s own local workflow. Use karta dev when you want to exercise the same session API production serves, on your machine, with hot reload.

karta dev                                                  # chat REPL, hot reload
karta dev -m "Do you ship free?"                           # one-shot, then exit

Edits to the harness instruction file hot-reload. Tool approvals are prompted the way an end user will see them. The local URL it prints is a real Karta session API: point the chat widget or your own frontend at it.

Local dev runs the model on your machine, so it needs a model credential in your environment - either set ANTHROPIC_API_KEY, or run claude setup-token and export the resulting CLAUDE_CODE_OAUTH_TOKEN. Deployed agents use the model access configured for production. It also needs uv installed; the pinned agent runtime bootstraps automatically on first run. karta doctor diagnoses the setup if anything is off.

Iterate

Deploying again is the same command. Edit CLAUDE.md or AGENTS.md (or add a sub-agent or skill), commit, deploy. Karta builds a new release and flips the agent to it. The API path never changes (the slug is stable), and in-flight conversations finish on the release they started on.

# tweak CLAUDE.md or AGENTS.md, then:
git commit -am "shorter greeting"
karta deploy                           # builds v2, activates it under the same slug

Rolling back, pinning a release, and other release controls live in Releases & rollback.

Embed it in your site

Your deployed agent now has one stable consumer surface. Choose the integration path by who the user is, which credential can be exposed, and who owns the UI:

Path	Use when	Start here
Anonymous hosted widget	You want the fastest public-site chat. The page ships a publishable `pk_live_...` key fenced by allowed origins.	Chat widget quickstart
Signed-in hosted widget	Your app knows the user and should give the agent durable per-user memory.	Identity, then Authenticated agent
Backend-minted session token	Your backend already holds a `kt_live_...` key and wants to hand the browser only a short-lived agent-scoped token.	Session tokens
Custom backend or frontend	You own the full UI and want to create sessions, send messages, and stream events.	API reference

For the backend-minted token path, your server calls the management endpoint with its kt_live_... key:

# Mint a session token server-side (holds your kt_live_ key):
curl -X POST https://karta.sh/api/agents/support-agent/session_tokens \
  -H "Authorization: Bearer $KARTA_API_KEY"

You can also talk to your agent with an existing OpenAI or Anthropic client. See Consumer adapters. Because karta dev serves the same session API locally, a custom frontend can point at your local Karta surface while you test integration.

Next steps

Choose your path

Pick the right next doc for widgets, API integrations, operations, or architecture review.

Embed the widget

Add your deployed agent to a site with one async script tag.

Run a support bot locally

The full walkthrough: a local agent, a streaming chat widget, an end user.

Use the API

Create sessions, send messages, stream events, or use a consumer adapter.

Define sub-agents

Route between harness roles and hand off mid-conversation.

Production architecture review

Security, tenancy, credentials, spend gates, audit, and operations checklist.

Every CLI command

The full karta reference - auth, local parity, deploy, observe.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Deploy to Karta

Verify the deploy

Exercise the Karta surface locally (optional)

Iterate

Embed it in your site

Next steps

Choose your path

Embed the widget

Run a support bot locally

Use the API

Define sub-agents

Production architecture review

Every CLI command

​Deploy to Karta

​Verify the deploy

​Exercise the Karta surface locally (optional)

​Iterate

​Embed it in your site

​Next steps

Choose your path

Embed the widget

Run a support bot locally

Use the API

Define sub-agents

Production architecture review

Every CLI command

Deploy to Karta

Verify the deploy

Exercise the Karta surface locally (optional)

Iterate

Embed it in your site

Next steps