> ## 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.

# Releases & rollback

> Deploy a new release and roll back to a previous one - with a git push, from CI, and over the API.

Deploying is creating a new [release](/concepts/releases) 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](/cli/overview) or over HTTP.

## Deploy

```bash theme={null}
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:

```bash theme={null}
karta deploy my-app --mode folder      # upload the current directory (needs releases:write)
```

## Roll back

```bash theme={null}
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:

```yaml .github/workflows/deploy.yml theme={null}
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:

<CodeGroup>
  ```bash Publish (upload) theme={null}
  curl -X POST https://karta.sh/api/agents/my-app/publish \
    -H "Authorization: Bearer $KARTA_API_KEY" \
    -F "commit_sha=1a2b3c4" \
    -F "tarball=@my-app.tar.gz"
  # -> 201 { "accepted": true, "agent": {...}, "release": {...} }
  ```

  ```bash Rollback theme={null}
  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": {...} }
  ```
</CodeGroup>

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](/platform/api-keys) to mint a scoped key.

## Stream logs

```bash theme={null}
karta logs my-app --tail              # follow via SSE
karta logs my-app --since 2026-06-01T00:00:00Z
```