---
name: vr-template-config
description: Manage VoiceRun agent configuration through templates, values files, and rendering. Create reusable templates, configure environments, and preview deployment specs.
---

# Manage VoiceRun Templates and Configuration

You are helping the user manage their agent's configuration using templates, values files, and the rendering system. This enables environment-specific configuration without code changes. Follow this guide:

## Project Configuration Structure

A VoiceRun project's configuration lives in the `.voicerun/` directory:

```
.voicerun/
├── agent.yaml            # Agent metadata (name, description, dependencies)
├── agent.lock            # Created after vr push (agent/function IDs, checksum)
├── values.yaml           # Default values for template rendering
└── templates/
    └── deployment.yaml   # Deployment spec template (STT, VAD, sessions, etc.)
```

### agent.yaml

Defines agent metadata:

```yaml
apiVersion: voicerun/v1
name: my-agent
description: "My voice agent description"
```

### values.yaml

Provides default values for template rendering:

```yaml
environment: development
sttModel: deepgram-flux
```

You can create environment-specific values files:

```
.voicerun/
├── values.yaml                  # Base defaults
├── values.development.yaml      # Development overrides
├── values.staging.yaml          # Staging overrides
└── values.production.yaml       # Production overrides
```

### templates/deployment.yaml

The deployment spec template uses Helm-style templating. It defines runtime configuration for the agent environment (STT model, VAD settings, error handling, audio processing, etc.).

## Rendering Templates (`vr render`)

Preview how templates will be rendered with current values:

```bash
vr render
```

### Render options

| Option | Description |
|--------|-------------|
| `--values`, `-f` | Custom values file path |
| `--set`, `-s` | Override specific values (repeatable) |
| `--output`, `-o` | Output format: `yaml` (default) or `json` |
| `--quiet`, `-q` | Only output templates, no validation messages |

```bash
# Render with default values
vr render

# Render with specific values file
vr render -f .voicerun/values.production.yaml

# Override specific values
vr render --set stt.model=nova-3 --set environment=production

# Output as JSON
vr render -o json

# Quiet mode (templates only)
vr render -q
```

### Common configuration values

Values you can set in values files or override with `--set`:

| Value | Description | Example |
|-------|-------------|---------|
| `environment` | Target environment | `development`, `production` |
| `sttModel` | Speech-to-text model | `deepgram-flux`, `nova-3` |

## Validating Configuration (`vr validate`)

Validate the project structure and configuration:

```bash
vr validate
```

### Validation options

| Option | Description |
|--------|-------------|
| `--environment`, `-e` | Environment to render templates for |
| `--quiet`, `-q` | Only output errors |

```bash
# Validate with specific environment
vr validate -e production

# Errors only
vr validate -q
```

### What gets validated

- `handler.py` exists and contains `async def handler()`
- `.voicerun/` directory structure is correct
- `agent.yaml` is valid YAML with required `name` field
- All template YAML files have valid syntax
- Deployment spec contains only allowed fields

## Creating Reusable Templates (`vr create template`)

Turn your current project into a reusable template that others can initialize from:

```bash
vr create template <NAME>
```

### Template options

| Option | Description |
|--------|-------------|
| `--description`, `-d` | Template description |
| `--category`, `-c` | Template category |
| `--public/--private` | Make public or private to your org (default: public) |

```bash
# Create a public template
vr create template customer-support

# Create a private template with metadata
vr create template customer-support --private \
  -d "Customer support agent with LLM and tool calling" \
  -c "support"
```

All text files in the project directory are collected and uploaded. Binary files are skipped. Files matching `.vrignore` patterns are excluded.

### Using templates

Initialize a new project from a template:

```bash
# List available templates
vr get templates

# Initialize from a template
vr init my-agent --template customer-support

# With template variables
vr init my-agent --template customer-support --var greeting="Hello" --var language="en"
```

## .vrignore — Controlling Uploads

Create a `.vrignore` file in your project root to exclude files from `vr push` and `vr create template`:

```
# Ignore log files
*.log

# Ignore data directory
data/

# Ignore build artifacts
build/**

# Ignore a specific file at root only
/config.local.yaml

# Ignore all CSV files
*.csv
```

Supported patterns:

| Pattern | Description |
|---------|-------------|
| `*.log` | Glob — matches any `.log` file at any depth |
| `secret.txt` | Exact name — matches in any directory |
| `data/` | Trailing `/` — matches directories only |
| `/config.yaml` | Leading `/` — anchored to project root |
| `build/**` | Globstar — matches everything under `build/` |
| `**/test.py` | Globstar prefix — matches at any depth |
| `# comment` | Lines starting with `#` are ignored |

The following are always excluded regardless of `.vrignore`: `.venv`, `__pycache__`, `.git`.

## Common Workflows

### Set up environment-specific configuration

1. Create values files for each environment:

```bash
# .voicerun/values.development.yaml
environment: development
sttModel: deepgram-flux

# .voicerun/values.production.yaml
environment: production
sttModel: nova-3
```

2. Preview each environment's configuration:

```bash
vr render -f .voicerun/values.development.yaml
vr render -f .voicerun/values.production.yaml
```

3. Validate for each environment:

```bash
vr validate -e development
vr validate -e production
```

### Share your agent as a template

1. Ensure your project is clean and working:

```bash
vr validate
vr test
```

2. Review what will be included:

```bash
# Check .vrignore is set up correctly
cat .vrignore
```

3. Create the template:

```bash
vr create template my-agent-template -d "Description of what this agent does" -c "category"
```

4. Verify it's available:

```bash
vr get templates
```

### Quick configuration check

```bash
# See rendered deployment spec
vr render -q

# Validate everything
vr validate

# Check what environment is configured
vr render -q -o json | head -20
```

## Troubleshooting

- **"Template rendering failed"** — Check YAML syntax in template files. Run `vr validate` for specific errors.
- **"agent.yaml missing required field"** — Ensure `agent.yaml` has at least a `name` field.
- **"Helm not found"** — Run `vr setup` to install Helm for template rendering.
- **Values not applying** — Ensure the values file path is correct. Use `vr render -f <path>` to preview.
- **Template creation includes unwanted files** — Add patterns to `.vrignore` and retry.

Guide the user through configuring their agent for their specific deployment needs.
