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.

A release is a versioned, validated snapshot of your harness application’s code — the agents, skills, tools, and context files at one commit. Releases are the unit the deploy loop produces and serves.

​
Properties

  • Immutable and versioned. Every publish produces a new release (v1, v2, …) tied to a commit SHA. Releases are never mutated in place.
  • Activation is a pointer flip. “Going live” moves a current_release pointer atomically. Rollback is just a flip back to a previous release.
  • Tenant-isolated. Each org runs its own active release in its own isolated workspace.
  • Zero-interruption cutover. In-flight sessions finish on the release they started on; the next session picks up the new active release.
  • Harness-native artifact. The packaged artifact is the harness’s own native layout — no Karta-specific manifest beyond an optional karta.toml for build hints.

​
How a release is built

1

Publish

Your CI packages the harness app and publishes the artifact to Karta with an auth token. The first publish creates the project; later publishes add versions.
2

Materialize

The data plane streams the tarball, validates karta.toml, guards against oversized and path-traversal (“zip-slip”) archives, and atomically extracts it under a per-version release root. Idempotent per version.
3

Detect build kind

The builder classifies the release as dockerfile, buildpack (synthesizes a minimal Dockerfile from a karta.toml key), or file_copy (run the tree directly).
4

Activate

On a successful production build, the control plane flips current_release atomically, marks the prior release superseded, and records an audit event. Re-activation is idempotent.

​
Preview releases

A pull request gets its own ephemeral, auto-expiring preview release — the agent equivalent of a Heroku review app — so changes can be exercised before they reach production.

​
What’s real vs. stubbed today

Build-kind detection, Dockerfile synthesis, and the deterministic image_ref computation are real. The actual image build (kaniko spawn + registry push) is currently a stub gated behind a flag; image releases fall back to file-copy execution until it’s wired. Session-time release resolution and per-project URLs — what makes “the next session runs the new code” true for hosted projects — are the linchpins still being closed. See the deploy loop for the honest gap map.

The deploy loop

Ship → serve → consume, end to end.

Releases & rollback

Deploy and roll back with the CLI and API.