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

# Quickstart

> Deploy a starter agent, or an existing agent defined for a supported harness, to Karta in under 10 minutes.

The goal of this page: **deploy an agent defined for a supported harness to
Karta in under 10 minutes.** If you already have a
[supported harness](/build/supported-harnesses) project, use that folder. If
not, scaffold a starter in the harness you want. Karta handles deploy, release
activation, the hosted chat page, and the consumer session API. You keep
authoring and evaluating the agent in your own repo, harness, and tooling.

Run this path first:

```bash theme={null}
npm install -g @karta.sh/cli
karta login                         # device flow, browser approve
karta create support-agent --harness claude-code  # scaffold a starter agent
cd support-agent
karta setup --enable                # configure delivery + flip on the deploy gate
karta deploy                        # push (git) or upload (folder)
karta open                          # open the live hosted chat page
```

Expected result: `karta open` opens the hosted chat page for a live release of
your agent.

<Note>
  This page is the shortest route to a deployed agent project. If you are choosing
  between widget, API, existing harness project, operations, or architecture
  review paths, start with [Choose your path](/journeys).
</Note>

## Deploy to Karta

<Steps>
  <Step title="Install the CLI">
    The Karta CLI ships on npm.

    ```bash theme={null}
    npm install -g @karta.sh/cli
    ```
  </Step>

  <Step title="Log in">
    ```bash theme={null}
    karta login
    ```

    `karta login` prints a one-time code and opens your browser; approve it
    while signed in to the [dashboard](https://karta.sh). The CLI receives a
    named, revocable credential - it shows up on your
    [API keys page](/platform/api-keys) like any other key - and installs the
    git credential helper, so `git push karta` never prompts.

    <Note>
      In CI, or anywhere a browser cannot open, set the `KARTA_API_KEY`
      environment variable - it overrides the stored config everywhere - or
      pipe a key: `echo $KARTA_API_KEY | karta login --with-token`.
    </Note>
  </Step>

  <Step title="Scaffold an agent">
    ```bash theme={null}
    karta create support-agent --harness claude-code
    cd support-agent
    ```

    `karta create` lays down a starter agent in the selected harness format:
    `CLAUDE.md` for Claude Code, or `AGENTS.md` plus the native marker folder
    for OpenCode, DeepAgents, Goose, or Codex CLI. It also writes
    [`karta.toml`](/build/karta-toml) (the deploy manifest - your agent's name
    and deploy gate, plus an `[env]` table for config it needs) and a
    `.gitignore`. It scaffolds with the deploy gate off.
    `--template faq-agent` starts from a worked support-agent example instead of
    the blank skeleton.

    Other harnesses use the same flow:

    ```bash theme={null}
    karta create support-deep --harness deepagents
    karta create ops-goose --harness goose
    karta create reviewer-codex --harness codex-cli
    karta create support-open --harness opencode
    ```

    Already have an agent folder from your normal harness workflow? Use that
    folder instead and run `karta setup --enable` there.

    Then configure delivery and turn on the deploy gate:

    ```bash theme={null}
    karta setup --enable
    ```

    `karta setup` configures the folder, initializes git when needed, and
    writes or updates `karta.toml`. `--enable` flips on the deploy gate
    (`deploy = true`) so the later `karta deploy` ships it. Without the gate,
    the agent remains local until you enable deploy.

    Make the agent yours: **replace the contents of the instruction file** with
    your own instructions. For this Claude Code walkthrough that file is
    `CLAUDE.md`; for OpenCode, DeepAgents, Goose, and Codex CLI it is `AGENTS.md`.
    Paste in a small support agent:

    ```markdown CLAUDE.md theme={null}
    # Beans - Karta Coffee Co. support agent

    You are Beans, the support agent for Karta Coffee Co.

    - Help with orders, shipping, roasts, returns, and brewing tips.
    - Keep replies to 1-3 sentences unless the user asks for detail.
    - If you do not know an order-specific fact, say so and offer a human handoff.
    ```

    The harness's native config directory (`.claude/`, `.opencode/`,
    `.deepagents/`, `.goose/`, or `.codex/`) is additive. See
    [Agent structure](/build/agent-structure).
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    git add -A && git commit -m "support agent v1"
    karta deploy
    ```

    `karta deploy` ships your agent. In a git repo, it creates or finds the
    hosted source repo, wires a `karta` git remote, pushes your committed `HEAD`,
    builds an immutable [release](/concepts/releases), activates it, and streams
    build progress back, including the live URL when the deploy finishes.
    Once the remote is wired, `git push karta main` is the exact equivalent.

    If you deploy an existing git repo with uncommitted changes, commit or stash
    them first. Karta deploys the committed `HEAD` for git-mode deploys.
  </Step>

  <Step title="See it live">
    ```bash theme={null}
    karta open
    ```

    Opens your agent's hosted chat page - the same widget your customers embed.
    `karta open console` opens the agent in the dashboard.
  </Step>
</Steps>

## Verify the deploy

| Check                   | Command              | Expected result                                                                 |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------- |
| CLI is authenticated    | `karta whoami`       | Prints the signed-in account and active organization.                           |
| The agent is configured | `karta status`       | Shows the agent resolved from `karta.toml` or the `karta` git remote.           |
| Hosted page opens       | `karta open`         | Opens the live agent page after the first active release.                       |
| Dashboard opens         | `karta open console` | Opens the agent dashboard page for release, logs, settings, and embed controls. |

## Exercise the Karta surface locally (optional)

You do not need this to ship, and it does not replace your harness's own local
workflow. Use `karta dev` when you want to exercise the **same session API**
production serves, on your machine, with hot reload.

```bash theme={null}
karta dev                                                  # chat REPL, hot reload
karta dev -m "Do you ship free?"                           # one-shot, then exit
```

Edits to the harness instruction file hot-reload. Tool approvals are prompted
the way an end user will see them. The local URL it prints is a real Karta
session API: point the [chat widget](/sdks/widget/quickstart) or your own
frontend at it.

<Note>
  Local dev runs the model on **your** machine, so it needs a model credential
  in your environment - either set `ANTHROPIC_API_KEY`, or run
  `claude setup-token` and export the resulting `CLAUDE_CODE_OAUTH_TOKEN`.
  Deployed agents use the model access configured for production.
  It also needs [uv](https://docs.astral.sh/uv/) installed; the pinned agent
  runtime bootstraps automatically on first run. `karta doctor` diagnoses the
  setup if anything is off.
</Note>

## Iterate

Deploying again is the same command. Edit `CLAUDE.md` or `AGENTS.md` (or add a
sub-agent or skill), commit, deploy. Karta builds a new release and flips the
agent to it.
The **API path never changes** (the slug is stable), and in-flight
conversations finish on the release they started on.

```bash theme={null}
# tweak CLAUDE.md or AGENTS.md, then:
git commit -am "shorter greeting"
karta deploy                           # builds v2, activates it under the same slug
```

Rolling back, pinning a release, and other release controls live in
[Releases & rollback](/deploy/releases-and-rollback).

## Embed it in your site

Your deployed agent now has one stable consumer surface. Choose the integration
path by who the user is, which credential can be exposed, and who owns the UI:

| Path                         | Use when                                                                                                            | Start here                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Anonymous hosted widget      | You want the fastest public-site chat. The page ships a publishable `pk_live_...` key fenced by allowed origins.    | [Chat widget quickstart](/sdks/widget/quickstart)                                               |
| Signed-in hosted widget      | Your app knows the user and should give the agent durable per-user memory.                                          | [Identity](/sdks/widget/identity), then [Authenticated agent](/sdks/widget/authenticated-agent) |
| Backend-minted session token | Your backend already holds a `kt_live_...` key and wants to hand the browser only a short-lived agent-scoped token. | [Session tokens](/security/session-tokens)                                                      |
| Custom backend or frontend   | You own the full UI and want to create sessions, send messages, and stream events.                                  | [API reference](/api-reference/introduction)                                                    |

For the backend-minted token path, your server calls the management endpoint
with its `kt_live_...` key:

```bash theme={null}
# Mint a session token server-side (holds your kt_live_ key):
curl -X POST https://karta.sh/api/agents/support-agent/session_tokens \
  -H "Authorization: Bearer $KARTA_API_KEY"
```

You can also talk to your agent with an existing OpenAI or Anthropic client. See
[Consumer adapters](/api-reference/adapters/overview). Because `karta dev`
serves the same session API locally, a custom frontend can point at your local
Karta surface while you test integration.

## Next steps

<CardGroup cols={2}>
  <Card title="Choose your path" icon="signs-post" href="/journeys">
    Pick the right next doc for widgets, API integrations, operations, or
    architecture review.
  </Card>

  <Card title="Embed the widget" icon="window" href="/sdks/widget/quickstart">
    Add your deployed agent to a site with one async script tag.
  </Card>

  <Card title="Run a support bot locally" icon="mug-hot" href="/tutorials/support-bot">
    The full walkthrough: a local agent, a streaming chat widget, an end user.
  </Card>

  <Card title="Use the API" icon="code" href="/api-reference/introduction">
    Create sessions, send messages, stream events, or use a consumer adapter.
  </Card>

  <Card title="Define sub-agents" icon="users-gear" href="/build/defining-agents">
    Route between harness roles and hand off mid-conversation.
  </Card>

  <Card title="Production architecture review" icon="shield-halved" href="/security/architecture-review">
    Security, tenancy, credentials, spend gates, audit, and operations checklist.
  </Card>

  <Card title="Every CLI command" icon="terminal" href="/cli/overview">
    The full `karta` reference - auth, local parity, deploy, observe.
  </Card>
</CardGroup>