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

# Manage agents

> Deploy agents, inspect releases, roll back, and stream logs - karta.toml links your local project to its hosted agent.

An **agent** is the hosted unit behind a stable URL - what an
[agent project](/concepts/harness-applications) becomes when you deploy
it. The link between your local project and its hosted agent is the local
`karta.toml`: per-agent commands resolve an explicit `--agent` or slug first,
then the agent in this folder, the repo's sole local agent, and finally the
legacy `KARTA_PROJECT` alias. Deployment itself is folder-scoped even when
several agents share one git repository.

## Deploy

```bash theme={null}
karta deploy                         # ship the agent in this folder
karta deploy --dir agents/support    # ... or select its folder explicitly
```

`karta deploy` ships one agent project using the `deploy_method` in its local
`karta.toml`. On first git deploy it provisions the hosted source and wires the
repository's `karta` remote; folder deploy uploads only the selected folder.
For low-level git use, target the agent's reserved deploy ref explicitly:

```bash theme={null}
request_id="$(date +%s)-manual"
git push --atomic --push-option=karta.agent-path=agents/support karta \
  HEAD:refs/heads/main \
  +HEAD:refs/karta/agents/support-bot/requests/$request_id
```

Plain `git push karta main` is a compatibility convenience for a repository
with one enabled agent. It never fans out a multi-agent repository. See
[Releases & rollback](/deploy/releases-and-rollback) for the deploy flow in
depth, including plain folders and CI.

## Inspect

```bash theme={null}
karta status                       # agents in this repo + their live release
karta agent list                   # all active agents in your org
karta agent show support-bot       # header + recent releases
karta agent releases support-bot   # release history
```

| Command                 | Purpose                                                                  |
| ----------------------- | ------------------------------------------------------------------------ |
| `status`                | Agents in the current repo joined to their live release/version.         |
| `agent list`            | List your active agents.                                                 |
| `agent show [slug]`     | Agent header plus recent releases (the agent in this folder if no slug). |
| `agent releases [slug]` | Release history for one agent.                                           |

## Roll back

```bash theme={null}
karta rollback support-bot --to v3
karta agent activate v3 support-bot
```

Rollback flips the active release pointer back - instant, and the agent URL
is unaffected. In-flight sessions finish on the release they started on.

Use `karta rollback` when you mean "revert production." Use
`karta agent activate` when you want to activate a specific existing production
release as an explicit operation.

## Agent controls

| Command                                                              | Purpose                                                                            |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `karta agent serving on\|off [slug]`                                 | Resume or pause serving for an agent.                                              |
| `karta agent dashboard-edits on\|off [slug]`                         | Enable or disable browser-console edits; deploy remains the source update path.    |
| `karta agent model [slug] --source inherit\|platform [--model <id>]` | Clear the override or pin the platform connector.                                  |
| `karta agent model [slug] --connector-id <id> [--model <id>]`        | Pin a BYOK connector from `karta model-keys list`; do not combine with `--source`. |
| `karta agent workspace-inspectable on\|off [slug]`                   | Enable or disable read-only workspace export for the agent's kartas.               |
| `karta agent delete [slug]`                                          | Archive an agent.                                                                  |

## Logs

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

## Open

```bash theme={null}
karta open             # the hosted chat page (what customers embed)
karta open console     # the agent page in the dashboard
```

Run it inside the agent project directory and Karta reads the local
`karta.toml`; elsewhere, pass `--agent <slug>` or set `KARTA_PROJECT` in CI.

## Clone a karta's workspace

Each [karta](/concepts/instances-and-memory) is a durable computer, and
its files persist across sessions. With **workspace access** enabled, an org
admin can clone that workspace read-only over git to see what the agent has
accumulated for a karta.

Turn it on in the console first: on the agent's **Settings** tab, enable
**Workspace access**, or run:

```bash theme={null}
karta agent workspace-inspectable on support-bot
```

It's a sensitive change, so the product records the change and the console may
ask you to re-verify your identity. The agent page then shows a ready-to-run
clone command for each karta:

```bash theme={null}
git clone https://workspaces.karta.sh/git/<agent>/<karta-id>
```

`karta login` installs a git credential helper that authenticates the clone for
you - no token to copy or paste. Access is **read-only**: `clone` and `pull`
work, `push` does not.

## Where sessions fit

For local Karta parity, use **`karta dev`**: it runs your agent behind the
same session API on your machine, with hot reload and a REPL - see the
[CLI overview](/cli/overview#build--run-locally). In production, sessions are
driven through the [session API](/api-reference/sessions) by your frontend or
the [chat widget](/sdks/widget/quickstart); the hosted chat page (`karta open`)
is the quickest way to talk to a live deploy.