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

## Versions

Every `zeroruntime 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}
zeroruntime version list                          # all versions, with the active one marked
zeroruntime version status                        # rollout state of the latest version
zeroruntime version describe -v <version-id>      # full details for one version
```

Activate or deactivate a specific version:

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

<Note>
  `zeroruntime down` is the quick way to deactivate **all** active versions at once. Use
  `zeroruntime 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}
zeroruntime 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}
zeroruntime secrets list                  # all secret sets
zeroruntime secrets create my-secrets -f .env
zeroruntime secrets describe my-secrets   # keys in the set (values are hidden)
zeroruntime secrets add my-secrets        # add keys interactively
zeroruntime secrets remove my-secrets     # remove keys interactively
zeroruntime secrets delete my-secrets     # delete the whole set
```

<Warning>
  Changing secrets affects new sessions. Redeploy with `zeroruntime 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 `zeroruntime invoke`,
then list and stop sessions with `zeroruntime session`:

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

`zeroruntime 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}
zeroruntime logs                          # most recent 50 lines, newest first
zeroruntime logs --limit 200 --sort 1     # 200 lines, oldest first
zeroruntime logs --since 1h               # last hour
zeroruntime 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 `zeroruntime.yaml` |

## Tearing down

Deactivate all active versions for the deployment:

```bash theme={null}
zeroruntime down              # confirms first
zeroruntime down --yes        # skip confirmation
zeroruntime 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>