---
name: vr-push-deploy
description: Push agent code and deploy to environments using the VoiceRun CLI. Covers the full push-deploy workflow, versioning, and environment management.
---

# Push and Deploy a VoiceRun Agent

You are helping the user push their agent code to the VoiceRun server and deploy it to an environment. Follow these steps:

## Step 1: Validate the project

Before pushing, validate the project structure:

```bash
vr validate
```

This checks:
- `handler.py` exists and contains `async def handler()`
- `.voicerun/` directory structure is correct
- `agent.yaml` is valid YAML with required fields
- Template YAML syntax is correct

Fix any validation errors before proceeding.

## Step 2: Push the code

Push your agent code to the VoiceRun server:

```bash
vr push
```

This will:
1. Validate the project
2. Package all code as a zip archive (excluding `.venv`, `__pycache__`, `.git`, and files matching `.vrignore`)
3. Create a new agent (first push) or update the existing function version (subsequent pushes)
4. Save `agent.lock` with agent ID, function ID, and code checksum

### Push options

| Option | Description |
|--------|-------------|
| `--yes`, `-y` | Skip confirmation prompts |
| `--name` | Name for the function version |
| `--new`, `-n` | Create a new function version instead of updating the existing one |

```bash
# Push without confirmation
vr push --yes

# Create a named version
vr push --new --name "v2.0"
```

### First push vs. subsequent pushes

- **First push**: Creates a new agent on the server. The agent ID and function ID are saved to `.voicerun/agent.lock`.
- **Subsequent pushes**: Updates the existing function version in-place. Use `--new` to create a separate version instead.

## Step 3: Deploy to an environment

After pushing, deploy the function to a target environment:

```bash
vr deploy <ENVIRONMENT>
```

The environment can be specified by name or ID. If omitted, you'll be prompted to select from available environments.

```bash
# Deploy to development
vr deploy development

# Deploy to production without confirmation
vr deploy production --yes

# Interactive selection
vr deploy
```

### What deploy does

1. Validates the project structure
2. Loads the agent ID and function ID from `agent.lock`
3. Resolves the target environment (by name or ID)
4. Deploys the function version to that environment

### Prerequisites

- `vr push` must be run first to create `agent.lock`
- The target environment must exist for the agent

## Step 4: Verify the deployment

After deploying, verify the environment is running your latest code:

```bash
# List environments and their status
vr get environments <AGENT>

# Describe the specific environment
vr describe environment <AGENT> <ENVIRONMENT>
```

You can also open the web UI to check:

```bash
vr open
```

## Common Workflows

### Development workflow (push + debug)

For rapid iteration, use `vr debug` which automatically pushes before launching the debugger:

```bash
vr debug
```

This pushes your code and opens the Pipeline Debugger for interactive testing. Use `--skip-push` if code hasn't changed:

```bash
vr debug --skip-push
```

### Multi-environment deployment

A typical setup has multiple environments with different configurations:

```bash
# Push the code once
vr push

# Deploy to development
vr deploy development

# Test in development, then promote to production
vr deploy production
```

### Version management

Create named versions for tracking releases:

```bash
# Create a new version
vr push --new --name "v1.0-stable"

# Later, create another version
vr push --new --name "v1.1-beta"
```

List all function versions:

```bash
vr get functions <AGENT>
```

### Checking for unpushed changes

The push command tracks a code checksum in `agent.lock`. If your local code differs from the last push, `vr deploy` will warn you about unpushed changes. Always push before deploying to ensure the latest code is active.

## Troubleshooting

- **"Validation failed"** — Fix the errors reported by `vr validate` before pushing.
- **"agent.lock not found"** — Run `vr push` first. The lock file is created on the first push.
- **"Environment not found"** — List available environments with `vr get environments <AGENT>`. The environment may not exist yet.
- **"Unpushed changes detected"** — Your local code differs from the last push. Run `vr push` before `vr deploy`.
- **"Authentication required"** — Run `vr signin` to authenticate.
- **Push seems stuck** — Check your network connection. Large projects with many files may take longer to upload.

Guide the user through each step, confirming the push succeeded before deploying.
