> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Deployments

> Operate a live agent day to day: manage versions, update secrets, inspect sessions, and read logs.

Once your agent is [deployed](/deployments/deploy-an-agent), these commands let you operate
it. Run them from inside your project folder so the CLI can read IDs from `zrt.yaml`; most
flags are optional because of that.

If you don't have the CLI yet, install it with pip (Python 3.11+):

```bash theme={null}
pip install zrt
```

## Versions

Every `zrt up` creates a new immutable **version**. You keep the one you want live, and can
roll back by reactivating an older one.

```bash theme={null}
zrt version list                          # all versions, with the active one marked
zrt version status                        # rollout state of the latest version
zrt version describe -v <version-id>      # full details for one version
```

Activate or deactivate a specific version:

```bash theme={null}
zrt version activate -v <version-id>
zrt version deactivate -v <version-id>
zrt version deactivate -v <version-id> --force   # even if it has active sessions
```

<Note>
  `zrt down` is the quick way to deactivate **all** active versions at once. Use
  `zrt version deactivate` when you want to target a single version.
</Note>

## Secrets

Secrets are environment variables (provider keys, tokens) injected into your running agent.
The simplest way to set them is at deploy time:

```bash theme={null}
zrt up --env .env
```

This uploads the keys from your `.env` file and applies them to the deployment. You can also
manage secret sets directly:

```bash theme={null}
zrt secrets list                  # all secret sets
zrt secrets create my-secrets -f .env
zrt secrets describe my-secrets   # keys in the set (values are hidden)
zrt secrets add my-secrets        # add keys interactively
zrt secrets remove my-secrets     # remove keys interactively
zrt secrets delete my-secrets     # delete the whole set
```

<Warning>
  Changing secrets affects new sessions. Redeploy with `zrt up` to roll the change out to
  running workers.
</Warning>

## Sessions

A session is one live conversation handled by your agent. Start the agent with `zrt invoke`,
then list and stop sessions with `zrt session`:

```bash theme={null}
zrt invoke                              # start the agent in a room
zrt invoke --console                    # start it, then talk in your terminal
zrt session list                        # list sessions for this agent
zrt session list --room-id <room-id>    # only sessions in a specific room
zrt session stop --room-id <room-id>    # stop a session by room
```

`zrt invoke` prints a playground link and the room ID it joined. Stop a session by room with
`--room-id`, or by session ID with `--session-id`.

## Logs

Stream console output from your running agent. Filter by count, direction, and time window:

```bash theme={null}
zrt logs                          # most recent 50 lines, newest first
zrt logs --limit 200 --sort 1     # 200 lines, oldest first
zrt logs --since 1h               # last hour
zrt logs --since 30m --until 5m   # a specific window
```

| Flag                  | Description                                   | Default                    |
| --------------------- | --------------------------------------------- | -------------------------- |
| `--limit` / `-n`      | Number of log lines (`1` to `1000`).          | `50`                       |
| `--sort`              | `-1` newest first, `1` oldest first.          | `-1`                       |
| `--since`             | Start of the window (e.g. `30m`, `2h`, `1d`). | none                       |
| `--until`             | End of the window.                            | now                        |
| `--version-id` / `-v` | Logs for a specific version.                  | latest                     |
| `--agent-id`          | Agent to read logs for.                       | `agent.id` from `zrt.yaml` |

## Tearing down

Deactivate all active versions for the deployment:

```bash theme={null}
zrt down              # confirms first
zrt down --yes        # skip confirmation
zrt down --force      # deactivate even with active sessions
```

## What's next

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="book" href="/deployments/cli-reference">
    Every command and flag in one place.
  </Card>

  <Card title="Deploy an Agent" icon="rocket" href="/deployments/deploy-an-agent">
    Revisit the end-to-end walkthrough.
  </Card>
</CardGroup>