Releases & rollback

Deploying is creating a new release and activating it. Rolling back is flipping the active pointer to an earlier release. Deploy is karta deploy: a git repo pushes, a plain folder uploads, and the hosted agent is provisioned on first run. git push karta main is the transparent equivalent for a git repo. This page covers both, plus rolling back, wiring CI, and the raw API - available through the karta CLI or over HTTP.

Deploy

npm install -g @karta.sh/cli
karta login                            # sign in; installs the git credential helper

karta deploy my-app                    # first run: provision agent + `karta` remote, then ship
git push karta main                    # the transparent equivalent, once the remote is wired

karta agent show my-app                # watch versions appear

karta deploy streams build progress back in its output and prints the live URL on success. On a successful production build, Karta allocates the next version and atomically activates it. From a plain folder with no git repo, karta deploy uploads the directory as a tarball instead of pushing - the same activation, no git required:

karta deploy my-app --mode folder      # upload the current directory (needs releases:write)

Roll back

karta rollback my-app --to v3          # flip active pointer (needs releases:write)

Rollback is a pointer flip back to a prior release - instant, and the agent URL is unaffected. In-flight sessions are undisturbed; the next session runs the release you rolled back to.

Deploy from CI

Wire deploys into your pipeline so every push to your deploy branch ships a new release. Set KARTA_API_KEY - the CLI works headless with it, no stored login needed. A minimal GitHub Actions shape:

.github/workflows/deploy.yml

name: Deploy agent
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @karta.sh/cli
      - run: karta deploy my-app
        env:
          KARTA_API_KEY: ${{ secrets.KARTA_API_KEY }}

Over the API

The publish and rollback endpoints are authenticated with a kt_live_... key:

curl -X POST https://karta.sh/api/agents/my-app/publish \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -F "commit_sha=1a2b3c4" \
  -F "[email protected]"
# -> 201 { "accepted": true, "agent": {...}, "release": {...} }

curl -X POST https://karta.sh/api/agents/my-app/rollback \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 3}'
# -> 200 { "agent": "...", "release": {...}, "previous_release": {...} }

This is the raw form of karta deploy --mode folder; most callers should use the CLI or git push karta.

Scopes

Action	Required key scope
List agents, releases, usage, logs	`read`
Deploy (push or upload)	`write`
Roll back or activate an existing release	`releases:write`

See API keys to mint a scoped key.

Stream logs

karta logs my-app --tail              # follow via SSE
karta logs my-app --since 2026-06-01T00:00:00Z

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Releases & rollback

Deploy

Roll back

Deploy from CI

Over the API

Scopes

Stream logs

​Deploy

​Roll back

​Deploy from CI

​Over the API

​Scopes

​Stream logs

Deploy

Roll back

Deploy from CI

Over the API

Scopes

Stream logs