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.

Deploying is creating a new release and activating it. Rolling back is flipping the active pointer to an earlier release. The headline way to deploy is git push karta — the push-to-deploy flow in the Quickstart. This page covers the explicit controls underneath it: deploying a specific commit, rolling back, wiring CI, and the raw API — available through the @karta/cli or over HTTP.

​
Deploy from the CLI

npm install -g @karta/cli
karta login                                   # stores your kt_live_ key

karta projects list                           # your projects
karta deploy my-app --commit 1a2b3c4          # enqueue a build (needs write scope)
karta projects releases my-app                # watch versions appear
A deploy enqueues a build for the given commit. On a successful production build, Karta allocates the next version and atomically activates it. This is exactly what git push karta does under the hood — it deploys the commit you pushed.

​
Roll back

karta rollback my-app --to v3                 # flip active pointer (needs admin scope)
Rollback is a pointer flip back to a prior release — instant, and the project 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. A minimal GitHub Actions shape:
.github/workflows/deploy.yml
name: Deploy harness app
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @karta/cli
      - run: karta deploy my-app --commit "${GITHUB_SHA}"
        env:
          KARTA_API_KEY: ${{ secrets.KARTA_API_KEY }}

​
Over the API

The deploy and rollback endpoints live on the control plane and are authenticated with a kt_live_… key: 
curl -X POST https://karta.sh/agent_projects/my-app/deploys \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commit_sha": "1a2b3c4"}'
# → 202 { "accepted": true, "project": "...", "commit_sha": "1a2b3c4" }

​
Scopes

ActionRequired key scope
List projects, releases, usage, logsread
Deploywrite
Roll backadmin
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
Today, deploys pull a tarball from a bound GitHub repo (via webhook or an explicit commit SHA). The token-authenticated publish-by-upload path — your CI pushing a pre-packaged artifact, no repo binding — is the target ingestion model. See the deploy loop’s status note.