Install the Terraform Provider

The provider ships source-only in v1 — install via go install and a Terraform dev override. Public Terraform Registry publishing is on the roadmap.

Prerequisites

• Go 1.23 or newer — go install builds the binary from source.
• Terraform 1.5 or newer.
• A reachable Agentcy backend (AGENTCY_ENDPOINT) and an API key from Settings → API Keys (or via POST /api/v1/api-keys).

Build and install

# Clone the agentcy repo and install from the provider subdir.
git clone https://github.com/agentcylabs/agentcy.git
cd agentcy/backend/terraform-provider-agentcy
go install .

Verify the binary landed:

ls -la "$(go env GOPATH)/bin/terraform-provider-agentcy"

Add the dev override

Terraform finds providers via either the registry or a dev override. Until v1 is in the registry, add this to ~/.terraformrc:

provider_installation {
  dev_overrides {
    "agentcy/agentcy" = "/Users/you/go/bin"   # replace with your $GOPATH/bin
  }
  direct {}
}

With a dev override active, don't run terraform init for this provider — it would error trying to download from the registry. terraform plan and terraform apply work directly.

First HCL file

terraform {
  required_providers {
    agentcy = { source = "agentcy/agentcy" }
  }
}

provider "agentcy" {
  endpoint = "http://localhost:18080"
  api_key  = var.agentcy_api_key
}

variable "agentcy_api_key" {
  type      = string
  sensitive = true
}

export TF_VAR_agentcy_api_key="$(curl -s -X POST http://localhost:18080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@localhost","password":"admin"}' | jq -r .token)"

terraform plan

A successful plan with no resources defined produces "No changes." Once that prints, you're ready to add resources — start with the end-to-end example.

Running the test suite

The provider ships with a full acceptance test suite that drives real terraform apply/update/import/destroy cycles against a live backend.

cd backend/terraform-provider-agentcy

# Unit tests — no backend needed.
make test

# Acceptance tests — requires AGENTCY_ENDPOINT and AGENTCY_API_KEY pointing
# at a backend you're OK mutating (the tests create realms, agents, etc.).
export AGENTCY_ENDPOINT=http://localhost:18080
export AGENTCY_API_KEY="$(curl -s -X POST $AGENTCY_ENDPOINT/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@localhost","password":"admin"}' | jq -r .token)"
make testacc

CI runs the full suite via .github/workflows/terraform-provider.yml. Acceptance tests are gated on the acceptance-tests label for PRs (so fork PRs don't fail without secret access) and run unconditionally on pushes to main.

Upgrading

go install always pulls the latest source from your repo checkout. To upgrade, git pull and re-run go install ..

When the provider is published to the registry, you'll switch from the dev override to a version = "..." constraint and run terraform init like any other provider.