Manage Botyard with Terraform

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

Provider version 0.8.0 supports these resources. Features not listed here are managed in the Botyard app or through the API.

Data sources look up bots, bot schedules, bot templates, credentials, MCP servers, packs and pack versions, skills, and tools. The Registry documentation has the argument reference for each resource and data source.

botyard_bot_schedule and the botyard_bot_schedules data source need provider version 0.7.1 or later, and botyard_bot_soul needs 0.8.0 or later.

Authenticate

The provider uses an organization-scoped Botyard API key (byk_...) with the owner role (see API authentication). Creating bots, MCP servers and Runtime Vault secrets requires the owner role, so a member or viewer key fails with 403 Forbidden on those resources. Keys default to the member role, so choose owner when you create the key.

Set the key 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.

To find the organization ID, call GET /v1/me/orgs with the key; the response's org_id is the value to use.

Bots that Terraform creates are owned by the API key that created them. Any other API key, even an owner key, gets 403 Forbidden when it tries to update or destroy them. To rotate the key, revoke the old key before you run terraform apply with the new one. After the old key is revoked, an owner key can take over those bots, but only if they have no other owner. If a person was added as an owner of a bot, the new key keeps getting 403 Forbidden for that bot. See API authentication.

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.

terraform {
  required_version = ">= 1.11"

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

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.

Related docs

• Getting started
• Runtime Vault
• MCP setup templates