---
title: Terraform Provider
description: ChatBotKit Terraform Provider allows you to manage your AI chatbot infrastructure as code. Learn how to install, configure, and use the provider to deploy bots, datasets, skillsets, and integrations.
tags:
  - ChatBotKit
  - terraform
  - infrastructure as code
  - devops
  - IaC
  - automation
  - deployment
category: Developers
---
The ChatBotKit Terraform Provider enables you to manage your AI chatbot infrastructure using Terraform. Define bots, datasets, skillsets, integrations, and more through declarative configuration files, enabling version control, automated deployments, and infrastructure consistency across environments.

## Features

The ChatBotKit Terraform Provider offers several powerful features for infrastructure management:

| Feature | Description |
|---------|-------------|
| Infrastructure as Code | Manage ChatBotKit resources declaratively |
| Full Resource Coverage | Support for bots, datasets, skillsets, integrations, and more |
| Data Sources | Read existing resources for reference in configurations |
| Import Support | Bring existing resources under Terraform management |
| State Management | Track resource changes and drift detection |
| CI/CD Integration | Automate deployments through pipelines |

## Installation

Add the provider to your Terraform configuration:

```hcl
terraform {
  required_providers {
    chatbotkit = {
      source  = "chatbotkit/chatbotkit"
      version = "~> 1.0"
    }
  }
}

provider "chatbotkit" {
  # API key can be set here or via CHATBOTKIT_API_KEY env var
}
```

Then initialize Terraform:

```shell
terraform init
```

## Requirements

To use the ChatBotKit Terraform Provider, you need:

- Terraform 1.0 or higher
- A ChatBotKit API key from the [Dashboard](https://chatbotkit.com/tokens)

## Authentication

Configure authentication using either method:

**Environment Variable (Recommended):**

```shell
export CHATBOTKIT_API_KEY="your-api-key"
```

**Provider Configuration:**

```hcl
provider "chatbotkit" {
  api_key = var.chatbotkit_api_key
}

variable "chatbotkit_api_key" {
  type      = string
  sensitive = true
}
```

When both are set, the provider configuration takes precedence over the environment variable.

## Quick Start

Here's a complete example that creates a knowledge-based support bot:

```hcl
terraform {
  required_providers {
    chatbotkit = {
      source  = "chatbotkit/chatbotkit"
      version = "~> 1.0"
    }
  }
}

provider "chatbotkit" {}

# Create a knowledge base
resource "chatbotkit_dataset" "knowledge" {
  name        = "Product Knowledge Base"
  description = "Contains product documentation and FAQs"
}

# Create a skillset for tools
resource "chatbotkit_skillset" "tools" {
  name        = "Support Tools"
  description = "Tools for customer support operations"
}

# Create the bot
resource "chatbotkit_bot" "support" {
  name        = "Customer Support Bot"
  description = "Handles customer inquiries"
  backstory   = "You are a helpful customer support agent."
  model       = "glm-5.2"
  
  dataset_id  = chatbotkit_dataset.knowledge.id
  skillset_id = chatbotkit_skillset.tools.id
}

# Output the bot ID
output "bot_id" {
  value = chatbotkit_bot.support.id
}
```

Deploy with:

```shell
terraform plan    # Preview changes
terraform apply   # Apply changes
```

## Resources

The provider supports the following resources:

### Core Resources

| Resource | Description |
|----------|-------------|
| `chatbotkit_bot` | AI chatbot agents with configurable models and behaviors |
| `chatbotkit_dataset` | Knowledge bases for retrieval-augmented generation |
| `chatbotkit_skillset` | Collections of abilities (tools) for bots |
| `chatbotkit_skillset_ability` | Individual abilities within a skillset |
| `chatbotkit_blueprint` | Reusable templates for bot configurations |
| `chatbotkit_secret` | Secure credential storage |
| `chatbotkit_file` | File records for uploads used by datasets and abilities |
| `chatbotkit_file_content` | Uploads content (inline, local, or remote URL) to a file |
| `chatbotkit_space` | Isolated, persistent filesystem (workspace) for agents |
| `chatbotkit_space_storage_file` | A file stored at a path within a space |
| `chatbotkit_portal` | Customer-facing portal configurations |
| `chatbotkit_policy` | Data-retention and usage policies for bots and blueprints |

### Integrations

| Resource | Description |
|----------|-------------|
| `chatbotkit_widget_integration` | Embeddable website chat widget |
| `chatbotkit_slack_integration` | Slack workspace integration |
| `chatbotkit_discord_integration` | Discord bot deployment |
| `chatbotkit_microsoftteams_integration` | Microsoft Teams integration |
| `chatbotkit_googlechat_integration` | Google Chat integration |
| `chatbotkit_telegram_integration` | Telegram bot deployment |
| `chatbotkit_whatsapp_integration` | WhatsApp Business integration |
| `chatbotkit_messenger_integration` | Facebook Messenger integration |
| `chatbotkit_instagram_integration` | Instagram messaging integration |
| `chatbotkit_email_integration` | Email-based interactions |
| `chatbotkit_twilio_integration` | Twilio SMS/voice integration |
| `chatbotkit_support_integration` | Support/helpdesk integration |
| `chatbotkit_notion_integration` | Notion workspace sync |
| `chatbotkit_sitemap_integration` | Website content ingestion |
| `chatbotkit_extract_integration` | Structured data extraction from conversations |
| `chatbotkit_mcpserver_integration` | Model Context Protocol (MCP) server endpoint |
| `chatbotkit_trigger_integration` | Scheduled or event-driven bot triggers |

## Data Sources

Read existing resources without managing them:

```hcl
# Reference an existing bot
data "chatbotkit_bot" "existing" {
  id = "bot_abc123"
}

# Use its properties
output "existing_bot_name" {
  value = data.chatbotkit_bot.existing.name
}
```

Available data sources: `chatbotkit_bot`, `chatbotkit_dataset`, `chatbotkit_blueprint`, `chatbotkit_skillset`.

## Bot Resource Example

```hcl
resource "chatbotkit_bot" "advanced" {
  name        = "Enterprise Assistant"
  description = "Multi-purpose enterprise bot"
  backstory   = <<-EOT
    You are an enterprise assistant with access to company knowledge.
    Be professional, helpful, and always verify user identity for sensitive operations.
  EOT
  
  model       = "glm-5.2"
  dataset_id  = chatbotkit_dataset.knowledge.id
  skillset_id = chatbotkit_skillset.tools.id
  
  moderation = true
  privacy    = true
  
  meta = {
    environment = "production"
    team        = "customer-success"
  }
}
```

## MCP Server Integration Example

Expose a skillset as an MCP endpoint for AI clients like Claude Desktop or VSCode:

```hcl
resource "chatbotkit_mcpserver_integration" "dev_tools" {
  name        = "Developer Tools"
  description = "Exposes internal tooling as MCP tools"
  skillset_id = chatbotkit_skillset.tools.id
}
```

## Trigger Integration Example

Schedule a bot to run on a cron schedule:

```hcl
resource "chatbotkit_trigger_integration" "daily_report" {
  name             = "Daily Report"
  description      = "Sends a daily summary report"
  bot_id           = chatbotkit_bot.support.id
  schedule         = "0 9 * * *"
  authenticate     = false
}
```

## Extract Integration Example

Extract structured data from conversations:

```hcl
resource "chatbotkit_extract_integration" "lead_capture" {
  name        = "Lead Capture"
  description = "Extracts contact details from conversations"
  bot_id      = chatbotkit_bot.support.id
  request     = "Extract the user's name, email, and main question."

  schema = {
    name     = "string"
    email    = "string"
    question = "string"
  }
}
```

## Importing Resources

Bring existing resources under Terraform management:

```shell
# Import a bot
terraform import chatbotkit_bot.my_bot bot_abc123def456

# Import a dataset
terraform import chatbotkit_dataset.my_dataset dataset_xyz789
```

## Examples

A library of complete, runnable examples lives in the provider repository under [`examples/`](https://github.com/chatbotkit/terraform-provider-chatbotkit/tree/main/examples). Highlights:

- **[agent-framework](https://github.com/chatbotkit/terraform-provider-chatbotkit/tree/main/examples/agent-framework)** - an autonomous agent authored as a *project of files* (instructions, skills, heartbeat) and provisioned end to end: a bot whose backstory is read from `instructions.md`, ability packs (`pack/shell`, `pack/cbk/space/skills`), an isolated workspace with file-based skills uploaded under `.skills/`, a Slack channel, and both scheduled triggers and a heartbeat.
- **multi-tenant agents** - one agent per customer, each isolated in its own sub-account, in two flavors: [multi-tenant-agents-shared](https://github.com/chatbotkit/terraform-provider-chatbotkit/tree/main/examples/multi-tenant-agents-shared) (the same agent for all) and [multi-tenant-agents-per-customer](https://github.com/chatbotkit/terraform-provider-chatbotkit/tree/main/examples/multi-tenant-agents-per-customer) (a bespoke agent per customer). See Multi-Tenancy below.
- Focused references for datasets, skillsets, dynamic skills, MCP servers, multi-agent workflows, and more.

Each example is a self-contained directory with its own `README.md` - copy one as a starting point.

## Multi-Tenancy and Sub-Accounts

To give each customer their own isolated environment, ChatBotKit's partner API creates **sub-accounts** (partner users), each with its own bots, datasets, conversations, and settings. Operate on a sub-account with the provider's `run_as` attribute: you hold **one** partner/master token and select the sub-account by ID (it sends the `X-RunAs-UserId` header), so there are no per-customer tokens. This is the standard Terraform multi-account pattern - provider aliases, like the AWS provider's `assume_role`:

```hcl
provider "chatbotkit" {
  alias  = "acme"
  run_as = var.acme_account_id # api_key from CHATBOTKIT_API_KEY
}

module "acme" {
  source        = "./modules/agent"
  providers     = { chatbotkit = chatbotkit.acme }
  customer_name = "Acme Corporation"
}
```

Add a customer by adding a provider alias and a module call - no `for_each`. Account IDs are not secret; only the master token is. The provider cannot create sub-accounts itself (that is the partner REST API), so create them once in the dashboard or via `partner/user/create`. See the [multi-tenant-agents-shared](https://github.com/chatbotkit/terraform-provider-chatbotkit/tree/main/examples/multi-tenant-agents-shared) and [multi-tenant-agents-per-customer](https://github.com/chatbotkit/terraform-provider-chatbotkit/tree/main/examples/multi-tenant-agents-per-customer) examples.

## CI/CD Integration

Example GitHub Actions workflow for automated deployments:

```yaml
name: Deploy ChatBotKit Infrastructure

on:
  push:
    branches: [main]
    paths: ['terraform/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: hashicorp/setup-terraform@v3
      
      - name: Terraform Init
        run: terraform init
        working-directory: terraform
      
      - name: Terraform Apply
        run: terraform apply -auto-approve
        working-directory: terraform
        env:
          CHATBOTKIT_API_KEY: ${{ secrets.CHATBOTKIT_API_KEY }}
```

## Best Practices

1. **Use Variables**: Parameterize your configurations for reusability across environments
2. **Remote State**: Use remote backends (S3, Terraform Cloud) for team collaboration
3. **Workspaces**: Manage multiple environments (dev, staging, prod) with workspaces
4. **Lifecycle Rules**: Use `prevent_destroy` for critical production resources
5. **Metadata**: Tag resources with `meta` for organization and filtering

## Additional Resources

- [Terraform Provider Manual](/manuals/terraform-provider) - Comprehensive technical documentation
- [Terraform Registry](https://registry.terraform.io/providers/chatbotkit/chatbotkit) - Official provider page
- [GitHub Repository](https://github.com/chatbotkit/terraform-provider-chatbotkit) - Source code and issues
- [API Documentation](/docs/api) - ChatBotKit API reference

## Related SDKs

- **Node.js SDK**: [@chatbotkit/sdk](https://github.com/chatbotkit/node-sdk) - Official Node.js SDK
- **Go SDK**: [github.com/chatbotkit/go-sdk](https://github.com/chatbotkit/go-sdk) - Official Go SDK