> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform Provider

> Define Coval test configuration in Terraform and use it from your application.

Use the [Coval Terraform provider](https://registry.terraform.io/providers/coval-ai/coval/latest/docs) to manage test configuration in version control. The [provider repository](https://github.com/coval-ai/terraform-provider-coval) contains the source and [resource examples](https://github.com/coval-ai/terraform-provider-coval/tree/main/examples).

## Install

Requires Terraform 1.12 or newer. Add the provider to your configuration:

```terraform theme={null}
terraform {
  required_version = ">= 1.12.0"

  required_providers {
    coval = {
      source  = "coval-ai/coval"
      version = "~> 2.1.0"
    }
  }
}

provider "coval" {}
```

Configure authentication with the `api_key` argument or `COVAL_API_KEY` environment variable. The provider uses `https://api.coval.dev/v1` by default; `api_base_url` selects another API root.

## Create a test set

This example creates a test set with one scenario. Its `workspace_id` variable selects the workspace that owns these resources.

```terraform theme={null}
variable "workspace_id" {
  type = string
}

resource "coval_test_set" "smoke" {
  workspace_id  = var.workspace_id
  display_name  = "Return policy"
  test_set_type = "SCENARIO"
}

resource "coval_test_case" "returns" {
  workspace_id = var.workspace_id
  test_set_id  = coval_test_set.smoke.id
  input_str    = "Ask whether an item purchased three weeks ago can be returned."
}

output "test_set_id" {
  value = coval_test_set.smoke.id
}
```

Initialize the provider, review the plan, and apply it:

```sh theme={null}
terraform init
terraform plan -out=tests.tfplan
terraform apply tests.tfplan
```

Commit `.terraform.lock.hcl` with your configuration. Keep state and saved plans in access-controlled storage.

## Use it with the Agent SDK

The `test_set_id` output contains the created test set's ID:

```sh theme={null}
terraform output -raw test_set_id
```

Pass that value as `RunConfig.test_set_id` in an [Agent SDK run](/sdks/agent-sdk.md#check-the-connection), with an SDK WebSocket agent and voice persona from the same workspace.

Terraform manages the test configuration; the SDK runs your voice pipeline. Use the returned run ID to review recordings, transcripts, evaluations, and traces in [Coval](https://app.coval.dev).

Keep changes to Terraform-managed configuration in code. Editing those fields in the platform creates drift that a later apply may overwrite.

## Reference

* [Resource and data-source schemas](https://registry.terraform.io/providers/coval-ai/coval/latest/docs)
* [Provider examples](https://github.com/coval-ai/terraform-provider-coval/tree/main/examples)
* [Source and issues](https://github.com/coval-ai/terraform-provider-coval)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.