Manage Botyard with Terraform

Use the Botyard Terraform provider to declare bots, skills, MCP servers, and Runtime Vault secrets as code, with a runnable quickstart configuration.

The Botyard Terraform provider lets you declare a supported set of Botyard resources in Terraform and manage them with plan and apply, alongside the rest of your infrastructure. The source is on GitHub at Botyard-AI/terraform-provider-botyard.

Supported resources

The provider currently supports these resources. Features not listed here are managed in the Botyard app or through the API.

Resource	Manages	Concepts
`botyard_bot`	A bot's identity and configuration overrides	Getting started
`botyard_bot_credential_assignment`	Which organization credentials a bot uses, per scope	Provider credentials
`botyard_bot_skill_assignment`	Which skills are assigned to a bot
`botyard_bot_tool_assignment`	Which tools are assigned to a bot
`botyard_skill`	An organization skill and its files
`botyard_mcp_server`	An organization MCP server	MCP setup templates
`botyard_mcp_server_member`	One member of an MCP server's member list	MCP setup templates
`botyard_vault_secret`	A Runtime Vault secret and its access rules	Runtime Vault

Data sources look up bots, bot templates, credentials, MCP servers, skills, and tools. The Registry documentation has the argument reference for each one.

Authenticate

The provider uses an organization-scoped Botyard API key (byk_...) created by an organization owner (see API authentication). Set it, and the organization ID, through environment variables so the key never lands in Terraform configuration or state:

export BOTYARD_API_KEY="byk_..."
export BOTYARD_ORG_ID="00000000-0000-0000-0000-000000000000"

BOTYARD_ENDPOINT is optional and defaults to https://api.botyard.io.

Quickstart

This configuration creates a bot, a custom skill, assigns the skill to the bot, and stores a Runtime Vault value that only that bot may lease. It requires Terraform 1.11 or later, because secret_value is a write-only argument that is never stored in state.

main.tf

terraform {
  required_version = ">= 1.11"

  required_providers {
    botyard = {
      source  = "Botyard-AI/botyard"
      version = "~> 0.4"
    }
  }
}

provider "botyard" {}

# The bot. Creating it triggers provisioning; the slug is derived from the name.
resource "botyard_bot" "assistant" {
  name        = "Terraform Quickstart Assistant"
  description = "Created by the terraform-provider-botyard quickstart."
}

# A custom skill: instructions the bot loads on demand.
resource "botyard_skill" "release_checklist" {
  name    = "Release Checklist"
  summary = "Steps to follow before announcing a release."

  files = [
    {
      filename = "SKILL.md"
      content  = <<-EOT
        # Release Checklist

        1. Confirm CI is green on the release commit.
        2. Check the changelog covers every user-facing change.
        3. Announce the release with a link to the changelog.
      EOT
    },
  ]
}

# Give the bot that skill. This resource owns the bot's full skill set.
resource "botyard_bot_skill_assignment" "assistant" {
  bot_slug  = botyard_bot.assistant.slug
  skill_ids = [botyard_skill.release_checklist.id]
}

# A Runtime Vault entry only this bot may lease at runtime.
resource "botyard_vault_secret" "status_page_url" {
  key_path     = "quickstart.status_page_url"
  display_name = "Status page URL"
  sensitivity  = "plain"
  secret_value = "https://status.example.com"
  bot_ids      = [botyard_bot.assistant.id]
}

output "bot_slug" {
  value = botyard_bot.assistant.slug
}

Run it in an organization you can experiment in:

terraform init
terraform apply

After the apply, the bot appears in the Botyard app with the Release Checklist skill assigned. A second terraform plan reports no changes. terraform destroy removes the bot, the skill, the assignment, and the vault secret.

Manage Botyard with Terraform

Supported resources

Authenticate

Quickstart

Related docs

On this page