git push, or your
CI - and the result is a stable agent endpoint something can talk to, at
agent.karta.sh/<org>/<agent>. Each session through that endpoint resolves to
the right durable karta: one per user, one or more virtual employees, one per
backend job, or another id you choose.
What “deploy” means here
A deploy does two things: it publishes a new, immutable, versioned release of your agent - the skills, tools, sub-agents, and context files - and it makes that release available to the durable kartas behind the agent’s path. The harness (Claude Code, OpenCode, DeepAgents, Goose, Codex CLI, or another supported runtime) is the runtime inside each isolated run environment; the release is what it loads. “Going live” is pointing the agent’s active marker at the new release so the next session starts on it. That framing drives the properties you want:Immutable, versioned
Every publish produces
v1, v2, and so on, tied to a commit SHA. The published
artifact for a version is never overwritten.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 records its own ephemeral, auto-expiring preview release.
Native harness layout
The package is the harness’s own layout; the only Karta-specific file is an
optional
karta.toml for build hints.Stable agent path
The first publish assigns a durable slug. New releases change the code behind
agent.karta.sh/<org>/<agent> - never the slug.Choose a deploy mode
In a multi-agent repo, Karta builds each folder whose
karta.toml has
deploy = true.
The end-to-end loop
1
Prepare the agent
Author and test the agent in your own repo, harness, model setup, and
evaluation loop. Use
karta dev when you want to exercise
the same session API and approval surface Karta serves in production.2
Deploy
Run
karta deploy - on first run it provisions the agent, assigns its
slug, and wires the karta git remote; thereafter git push karta main is
the transparent equivalent. Build progress streams back in the output. A
plain folder uploads instead of pushing. If the repo holds
multiple agents, one
deploy builds every agent whose karta.toml sets deploy = true, each
from its own subdirectory. See the
CI example.3
Karta builds
Karta allocates the next version and materializes the artifact, building it
from your
karta.toml - a Dockerfile, a buildpack
runtime, or the file tree run directly - without translating the project out
of the harness’s native format.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 agent path speaks the session API - create a
session, send, stream. The caller supplies or derives the karta id, Karta
resumes that durable workspace, attaches an isolated runtime for the turn, and
streams the harness events back through the same agent UX.
6
Roll back if needed
Flip
current_release back to a prior release; the next session reverts.
The path is unaffected. See Releases & rollback.