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’s north star is that shipping a harness application feels like shipping a web app to Heroku — and, like Heroku, the result of a deploy is a live URL something can talk to. 
  SHIP                                                 SERVE & CONSUME
  ─────────────────────────────────────────────       ───────────────────────────

  ┌────────────┐  push    ┌──────────┐  publish   ┌──────────────────────────┐
  │ local repo │ ───────▶ │  CI/CD   │ ─────────▶ │          KARTA            │
  │ (harness   │          │ packages │  artifact  │ version · build · activate│
  │  app)      │          │ the app  │  + token   │ assign project URL        │
  └────────────┘          └──────────┘            └────────────┬─────────────┘
                                                               │ exposes
                                                               ▼
                                              https://<project>.karta.app
                                              ┌──────────────────────────┐
                                              │  session API:             │
                                              │  create · send · stream   │
                                              └────────────┬─────────────┘
                                                           │ connect
                                                           ▼
                                              ┌──────────────────────────┐
                                              │  frontend / chat widget   │
                                              │  on the now-active release│
                                              └──────────────────────────┘

​
What “deploy” means here

A deploy does two things: it publishes a new, immutable, versioned release of your harness app — the skills, tools, sub-agents, and context files — and it runs that release in an isolated sandbox behind the project’s URL. The harness (Claude Code, OpenCode) is the runtime inside the sandbox; the release is what it loads. “Going live” is pointing the project’s active marker at the new release so the next session runs against it. That framing drives the properties you want:

Immutable, versioned

Every push produces v1, v2, … tied to a commit SHA. Never mutated in place.

Atomic activation

Going live is a current_release pointer flip — so rollback is a flip back.

Zero-interruption cutover

In-flight sessions finish on their release; the next session gets the new one. No forced disconnects, no Karta redeploy.

Preview per PR

A pull request gets its own ephemeral, auto-expiring release — a review app for agents.

Harness-native artifact

The package is the harness’s own layout; the only Karta-specific file is an optional karta.toml for build hints.

Stable per-project URL

The first publish assigns a durable URL. New releases change the code behind it — never the URL.

​
The end-to-end loop

1

Develop locally

Edit your harness app — add a skill, tweak CLAUDE.md, define a sub-agent. Iterate with karta dev.
2

Push & publish

git push karta to deploy (the remote karta init set up), or open a PR for a preview. Karta packages the repo and publishes it with an auth token; the first publish creates the project and assigns its URL, later publishes add versions. You can also drive this from your own pipeline — see the CI example.
3

Karta builds

Karta allocates the next version and materializes the artifact, classifying it as dockerfile, buildpack, or file_copy from your karta.toml.
4

Activate

On a successful production build, Karta flips current_release atomically and records an audit event. A PR build becomes a time-boxed preview instead.
5

Serve & consume

The project URL speaks the session API — create a session, send, stream — the same shape a local Claude Code / OpenCode session uses. A frontend (e.g. an embedded chat widget) opens a session and drives it through agent UX.
6

Roll back if needed

Flip current_release back to a prior release; the next session reverts. The URL is unaffected. See Releases & rollback.

​
Why a fixed session protocol

A web app exposes whatever routes its developer invents; every Karta project exposes the same session protocol. That’s deliberate — a fixed API is why one chat widget can talk to any Karta project, and why a hosted project and a local harness session are interchangeable from a client’s point of view. What a harness app ships is agent behavior, not custom endpoints.

​
Honest status

Substantial parts of this loop exist today: push → release row (via GitHub webhook), the versioned release model and active pointer, build orchestration and atomic activation, forward-deploy and rollback endpoints, and release materialization on the data plane. Two linchpins are still being closed:
  • git push karta & publish-by-upload — karta init/karta open and a karta git remote are the rolling-out UX; today deploys pull a tarball from a repo-linked project (GitHub webhook or karta deploy --commit).
  • Release resolution at session time — new sessions don’t yet load the active release; the server runs a fixed path. Until this lands, “the next session runs the new code” isn’t true for hosted projects.
  • Per-project URLs — projects have a slug today, not a routable URL (<project>.karta.app); session APIs live on a shared host (api.karta.sh/v1/projects/{ref}) scoped by API key or session token.
The sandbox substrate is decided: a per-session AWS Bedrock AgentCore microVM. Image builds (kaniko) and selectable VM sizes are tracked as a dedicated milestone. Treat the hosted serve/consume half as target UX; the works-today path is the Quickstart’s Develop locally section and karta serve.