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

# Deploy an Agent

> Go from an empty folder to a live agent you can talk to: create a project, test it locally, deploy it to Zero Runtime Cloud with one command, then invoke it.

This guide takes you from nothing to a live agent in a handful of commands. Run them in
order; each one builds on the last.

First, install the Zero Runtime CLI with pip (Python 3.11+), and make sure **Docker is
running** (needed for `zrt up`):

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

See [CLI Setup](/deployments/cli-setup) for more detail.

<Note>
  Run every `zrt` command from **inside your project folder**. The CLI reads and writes a
  `zrt.yaml` file there to remember your agent, image, and version, so most commands need
  no flags at all.
</Note>

<Steps>
  <Step title="Sign in">
    Authenticate the CLI with your Zero Runtime account. This opens your browser to confirm the
    login, then stores your token on this machine:

    ```bash theme={null}
    zrt auth login
    ```

    You only need to do this once per machine. To sign out later, run `zrt auth logout`.
  </Step>

  <Step title="Create a project">
    The fastest way to get a working agent is `zrt quickstart`. It downloads a ready-made
    example into a new folder and runs it locally so you can talk to it right away.

    ```bash theme={null}
    zrt quickstart
    ```

    You'll be asked to pick an example, or skip the picker by naming one (replace
    `<example-id>` with the example you want):

    ```bash theme={null}
    zrt quickstart --template <example-id>
    ```

    This creates a `./<example-id>/` folder with everything you need:

    | File               | Purpose                                     |
    | ------------------ | ------------------------------------------- |
    | `main.py`          | Your agent's entrypoint and pipeline.       |
    | `requirements.txt` | Python dependencies.                        |
    | `.env`             | Provider API keys and secrets (kept local). |
    | `config.json`      | Local run metadata.                         |

    <Tip>
      Already have an agent project? You can skip this step. Just make sure it has an entrypoint
      named `main.py`, `agent.py`, or `app.py`. `zrt init` (below) generates the `Dockerfile`
      and `zrt.yaml` for you.
    </Tip>
  </Step>

  <Step title="Add your provider keys">
    Move into the project folder (the one quickstart just created) and open `.env`. Fill in the
    API keys for the STT, LLM, and TTS providers your agent uses:

    ```bash theme={null}
    cd <example-id>
    ```

    ```bash .env theme={null}
    ZRT_AUTH_TOKEN=...        # added for you by quickstart
    DEEPGRAM_API_KEY=...      # your provider keys
    GOOGLE_API_KEY=...
    CARTESIA_API_KEY=...
    ```

    <Note>
      `zrt run` and your deployed agent both read keys from this `.env` file. Never commit it or
      bake keys into the Docker image.
    </Note>
  </Step>

  <Step title="Test it locally">
    Run the agent on your own machine to confirm it works before deploying. This creates a
    virtual environment, installs the requirements, and starts the agent in the **playground**
    so you can talk to it in your browser:

    ```bash theme={null}
    zrt run . --open
    ```

    ```text Expected output theme={null}
    Running project '<example-id>'...
    Playground ready: https://playground.zeroruntime.ai/...
    Opening the playground in your browser...
    ```

    <Tip>
      Prefer your terminal over the browser? Run in **console mode** instead:

      ```bash theme={null}
      zrt run . --console
      ```

      You can also run a single file directly: `zrt run main.py --console`.
    </Tip>

    This runs entirely on your machine; no cloud resources are used yet.
  </Step>

  <Step title="Initialize the deployment">
    Register the agent with Zero Runtime Cloud. This creates the IDs your later commands need,
    writes them to `zrt.yaml`, and generates a `Dockerfile` if your project doesn't have one:

    ```bash theme={null}
    zrt init --name my-agent
    ```

    After it runs, `zrt.yaml` holds your `agent.id` and `deploy.id`:

    ```yaml zrt.yaml theme={null}
    version: "1.0"
    agent:
      id: ag_xxxxxxxx
      name: my-agent
    deploy:
      id: dep_xxxxxxxx
    ```

    <Note>
      You won't edit `zrt.yaml` by hand. Each command fills in the values it produces (image
      name, version ID, secrets), so the commands that follow run with no flags.
    </Note>
  </Step>

  <Step title="Deploy it">
    `zrt up` deploys your agent to Zero Runtime Cloud in a single command. Pass `--env .env` to
    also upload your provider keys so the deployed agent can use them:

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

    ```text Expected output theme={null}
    ✓ Agent is up!
      Version ID: vr_xxxxxxxx
    ```

    That's it. Your agent is now running on Zero Runtime Cloud. The new `version.id` is saved
    to `zrt.yaml`.

    <Note>
      `zrt up` deploys with sensible defaults, so there's nothing else to configure.
    </Note>

    <Warning>
      This step needs Docker running. If you see `'docker' command not found`, make sure Docker is
      installed and running, then try again.
    </Warning>
  </Step>

  <Step title="Confirm it's live">
    Check that the version deployed and is healthy:

    ```bash theme={null}
    zrt version list      # every version, with the active one marked
    zrt version status    # rollout state of the latest version
    ```
  </Step>

  <Step title="Talk to your agent">
    **Invoke** your agent to start it in a room. The CLI prints a playground link you can open
    to talk to it:

    ```bash theme={null}
    zrt invoke
    ```

    ```text Expected output theme={null}
    ✓ Agent invoked successfully
      Room ID: <room-id>

    Interact with your agent here:
      https://playground.zeroruntime.ai?token=...&meetingId=<room-id>
    ```

    <Tip>
      Want to talk to it right in your terminal? Add `--console`:

      ```bash theme={null}
      zrt invoke --console
      ```
    </Tip>

    List and stop live sessions when you're done:

    ```bash theme={null}
    zrt session list
    zrt session stop --room-id <room-id>
    ```
  </Step>

  <Step title="Watch the logs">
    Stream your agent's console output to see what it's doing in production:

    ```bash theme={null}
    zrt logs                        # most recent 50 lines
    zrt logs --limit 100 --sort 1   # 100 lines, oldest first
    ```

    See [Managing Deployments](/deployments/managing-deployments#logs) for time filters.
  </Step>
</Steps>

## Ship an update

Changed your code? Redeploy with the same command; it creates a new version:

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

## Take it down

When you're finished, stop the running version(s) so they stop using resources:

```bash theme={null}
zrt down
```

This lists the active versions and asks you to confirm. Add `--yes` to skip the prompt, or
`--force` if a version still has active sessions.

## What's next

<CardGroup cols={2}>
  <Card title="Managing Deployments" icon="sliders" href="/deployments/managing-deployments">
    Versions, secrets, sessions, and logs for a live agent.
  </Card>

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