Terraform Provider

Beta access

The Runlayer Terraform provider is currently in beta. If you need help — private network access when your Runlayer API is not public, or the right base URL for your environment:

Reach out to us in Slack
Or email support@runlayer.com

What you need

Terraform CLI 1.0 or later (OpenTofu works too)
Network access to your Runlayer API
A Runlayer user API key

The provider installs from Runlayer’s registry at downloads.runlayer.com with a plain terraform init — no credentials, no manual downloads.

Setup

Get private access first

If your Runlayer API is only reachable over VPN or another private network, make sure that is working before you start Terraform.

Declare the provider

terraform {
  required_providers {
    runlayer = {
      source  = "downloads.runlayer.com/runlayer/runlayer"
      version = "~> 1.0"
    }
  }
}

provider "runlayer" {}

Export your Runlayer credentials

export RUNLAYER_API_KEY="rl_..."
export RUNLAYER_BASE_URL="https://your-runlayer-base-url"

Use a user API key here.Organization API keys are not sufficient for Terraform resource management endpoints such as policy creation.

RUNLAYER_BASE_URL should be the API base URL for your environment. If you are not sure which URL to use, ask us.

Optional: set the base URL in the provider block

If you prefer explicit provider configuration instead of environment variables, use the provider’s base_url and api_key arguments:

variable "runlayer_base_url" {
  type = string
}

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

provider "runlayer" {
  base_url = var.runlayer_base_url
  api_key  = var.runlayer_api_key
}

If you use this form, the variable name can be runlayer_base_url, but the provider argument itself is base_url.

Run Terraform

terraform init
terraform plan

terraform init downloads the provider from the Runlayer registry and verifies its checksum and GPG signature.

Verify the setup

A good first check is:

terraform init installs the provider and writes it to .terraform.lock.hcl
once you add a real resource, terraform plan reaches the Runlayer API instead of failing on auth, host, or network setup

Using variables for users, groups, and roles

If you want stable references in Terraform, declare variables like this:

variable "users" {
  type = map(string)
}

variable "groups" {
  type = map(string)
}

variable "roles" {
  type = map(string)
}

Then use them in resources:

principal = {
  type = "group"
  ids  = [var.groups.engineers]
}

How the CLI can help

The CLI includes uvx runlayer terraform export to generate a tfvars file with stable names for users, groups, and roles. Example:

uvx runlayer terraform export --output runlayer.auto.tfvars

Example output:

users = {
  marcin_at_runlayer_com = "11111111-1111-1111-1111-111111111111"
}

groups = {
  engineers = "22222222-2222-2222-2222-222222222222"
}

roles = {
  admin = "33333333-3333-3333-3333-333333333333"
}

That file can be loaded by Terraform and referenced like:

var.users.marcin_at_runlayer_com
var.groups.engineers
var.roles.admin

This is useful when one person refreshes IDs occasionally and the rest of the Terraform code stays readable.

Resources

Provider 1.0 manages the full Runlayer surface:

Resource	Manages
`runlayer_server`	MCP server registrations (transport, auth fields)
`runlayer_policy`	Access policies (principals, scope, conditions)
`runlayer_server_security_setting`	Per-server scanner/violation settings
`runlayer_deployment`	Hosted MCP deployments, authored as YAML
`runlayer_agent_account`	Machine accounts with a one-time client secret
`runlayer_role_assignment`	Manual role grants (IdP-synced grants stay with the IdP)

Data sources: runlayer_server, runlayer_policy, runlayer_server_security_setting, runlayer_deployment, runlayer_agent_account, runlayer_group, runlayer_role, runlayer_user.

Deployment example

resource "runlayer_deployment" "internal_tools" {
  name         = "internal-tools"
  yaml_content = templatefile("${path.module}/runlayer.yaml.tftpl", {
    image_digest = var.image_digest
  })
}

The YAML has the same shape as runlayer.yaml. Build and push the image in CI, then stamp the digest into the YAML.

Agent account example

resource "runlayer_agent_account" "ci_bot" {
  name        = "ci-bot"
  description = "Runs the nightly evals"
}

output "ci_bot_secret" {
  value     = runlayer_agent_account.ci_bot.client_secret
  sensitive = true
}

client_secret is returned once, on create, and can never be read again. It stays in Terraform state (treat state as a secret); an account imported after creation has no secret — rotate credentials in the app if you need one.

Upgrading from 0.10

Provider 1.0 is a breaking release:

Policy value fields must be valid JSON. Wrap plain strings with jsonencode: value = "delete" becomes value = jsonencode("delete"). Existing policy states need a re-import: terraform state rm the policy, update the config, then terraform import.
Minimum backend version: 2026-08-19. Ask us if you are unsure what your environment runs.
Registering a deployment’s connector on first apply requires a user API key (organization keys cannot register connectors yet).

Policy examples

These examples are based on the provider e2e coverage and show common policy shapes.

Allow one group full access to one server

resource "runlayer_policy" "allow_engineers_linear" {
  action = "allow"

  principal = {
    type = "group"
    ids  = [var.groups.engineers]
  }

  scope = {
    servers   = [runlayer_server.linear.id]
    tools     = ["*"]
    resources = ["*"]
  }

  description = "Engineers: full Linear access"
}

Allow one group read-only access to a server

resource "runlayer_policy" "allow_contractors_deepwiki_readonly" {
  action = "allow"

  principal = {
    type = "group"
    ids  = [var.groups.contractors]
  }

  scope = {
    servers   = [runlayer_server.deepwiki.id]
    tools     = ["search_documentation", "get_library_docs", "resolve_library_id"]
    resources = ["*"]
  }

  description = "Contractors: read-only DeepWiki"
}

Deny one group access to one server

resource "runlayer_policy" "deny_contractors_linear" {
  action = "deny"

  principal = {
    type = "group"
    ids  = [var.groups.contractors]
  }

  scope = {
    servers   = [runlayer_server.linear.id]
    tools     = ["*"]
    resources = ["*"]
  }

  description = "Contractors: no Linear access"
}

Deny tools by name prefix

resource "runlayer_policy" "deny_destructive_tools" {
  action = "deny"

  principal = {
    type = "any"
  }

  scope = {
    servers   = [runlayer_server.linear.id]
    tools     = ["*"]
    resources = ["*"]
  }

  conditions = [{
    rules = [{
      field      = "tool_name"
      operator   = "begins_with"
      value      = jsonencode("delete")
      report_raw = false
    }]
  }]

  description = "Deny any tool starting with delete"
}

Deny access outside a private IP range

resource "runlayer_policy" "deny_internal_outside_vpn" {
  action = "deny"

  principal = {
    type = "any"
  }

  scope = {
    servers   = [runlayer_server.internal_tools.id]
    tools     = ["*"]
    resources = ["*"]
  }

  conditions = [{
    rules = [{
      field      = "meta.request.ip"
      operator   = "not_ip_range"
      value      = jsonencode("10.0.0.0/8")
      report_raw = true
    }]
  }]

  description = "Deny internal tools access from outside VPN"
}

Deny agent accounts without a production attribute

resource "runlayer_policy" "deny_nonprod_agents" {
  action = "deny"

  principal = {
    type = "any"
  }

  scope = {
    servers   = ["*"]
    tools     = ["*"]
    resources = ["*"]
  }

  # Rules within a group are ANDed: the subject.type guard scopes the
  # negative attribute rule to agent traffic only.
  conditions = [{
    rules = [
      {
        field      = "meta.subject.type"
        operator   = "equals"
        value      = jsonencode("agent")
        report_raw = false
      },
      {
        field      = "meta.actor.attributes.environment"
        operator   = "not_equals"
        value      = jsonencode("production")
        report_raw = false
      }
    ]
  }]

  description = "Global: agent accounts must carry environment=production"
}

Deny everything except a small read-only tool set

resource "runlayer_policy" "deny_contractors_internal_writes" {
  action = "deny"

  principal = {
    type = "group"
    ids  = [var.groups.contractors]
  }

  scope = {
    servers   = [runlayer_server.internal_tools.id]
    tools     = ["*"]
    resources = ["*"]
  }

  conditions = [{
    rules = [
      {
        field      = "tool_name"
        operator   = "not_equals"
        value      = jsonencode("read_data")
        report_raw = false
      },
      {
        field      = "tool_name"
        operator   = "not_equals"
        value      = jsonencode("list_items")
        report_raw = false
      },
    ]
  }]

  description = "Contractors: deny internal tools except read_data and list_items"
}

Troubleshooting

terraform init cannot find the provider: check the source is exactly downloads.runlayer.com/runlayer/runlayer and that outbound HTTPS to downloads.runlayer.com is allowed
Terraform still uses an old manual install: remove any dev_overrides block for the provider from your Terraform CLI config (~/.terraformrc or TF_CLI_CONFIG_FILE), then re-run terraform init
terraform apply returns 403 Forbidden: make sure you are using a user API key, not an organization API key
API calls fail: verify RUNLAYER_API_KEY
API calls hit the wrong environment: verify RUNLAYER_BASE_URL
Requests time out or refuse to connect: confirm private network access first

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Terraform Provider

Beta access

What you need

Setup

Using variables for users, groups, and roles

How the CLI can help

Resources

Deployment example

Agent account example

Upgrading from 0.10

Policy examples

Allow one group full access to one server

Allow one group read-only access to a server

Deny one group access to one server

Deny tools by name prefix

Deny access outside a private IP range

Deny agent accounts without a production attribute

Deny everything except a small read-only tool set

Troubleshooting

​Beta access

​What you need

​Setup

​Using variables for users, groups, and roles

​How the CLI can help

​Resources

​Deployment example

​Agent account example

​Upgrading from 0.10

​Policy examples

​Allow one group full access to one server

​Allow one group read-only access to a server

​Deny one group access to one server

​Deny tools by name prefix

​Deny access outside a private IP range

​Deny agent accounts without a production attribute

​Deny everything except a small read-only tool set

​Troubleshooting

Beta access

What you need

Setup

Using variables for users, groups, and roles

How the CLI can help

Resources

Deployment example

Agent account example

Upgrading from 0.10

Policy examples

Allow one group full access to one server

Allow one group read-only access to a server

Deny one group access to one server

Deny tools by name prefix

Deny access outside a private IP range

Deny agent accounts without a production attribute

Deny everything except a small read-only tool set

Troubleshooting