Managing Deployments

Once your agent is deployed, 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+):

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.

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:

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

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.

Secrets

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

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:

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

Changing secrets affects new sessions. Redeploy with zrt up to roll the change out to running workers.

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:

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:

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:

zrt down              # confirms first
zrt down --yes        # skip confirmation
zrt down --force      # deactivate even with active sessions

Get started

Operate

Reference

Versions

Secrets

Sessions

Logs

Tearing down

What’s next

CLI Reference

Deploy an Agent

​Versions

​Secrets

​Sessions

​Logs

​Tearing down

​What’s next

CLI Reference

Deploy an Agent

Versions

Secrets

Sessions

Logs

Tearing down

What’s next