Overview

The Forge provider manages policies, Resources, Resource Gateways, credentials, and policy-adjacent routing. Identities, integrations, products, models, MCP servers, and skills stay server-owned and are referenced by readable names. The public provider is published in the Terraform Registry as a37ai/forge. The v0.3 release line includes signed checksums and provider packages for Darwin, Linux, and Windows on amd64 and arm64.

Configure the provider

terraform {
  required_version = ">= 1.8.0"

  required_providers {
    forge = {
      source  = "a37ai/forge"
      version = "~> 0.3.0"
    }
  }
}

provider "forge" {
  organization_id  = "org.example"
  manager_id       = "policy-repository"
  manager_instance = "production"
}

Set FORGE_API_TOKEN to a Forge service-account token with policies:read and policies:write. endpoint defaults to https://api.forge.ai and can be supplied with FORGE_ENDPOINT. Plain HTTP is accepted only for localhost development. manager_id identifies the durable policy manager, such as a repository. manager_instance distinguishes independent deployments, such as production and staging. Keep both stable; changing them makes existing authority checks fail. The server binds manager_id and manager_instance to the authenticated service-account principal that first claims or creates the policy. Matching headers from another credential cannot read, update, release, or delete that Terraform-owned policy. The values identify state ownership; they are not secrets and do not replace token authorization. The provider checks compatibility with Forge before planning a mutation. A connected plan validates readable references, policy structure, Rego, the current revision, and policy ownership. Apply rechecks the reviewed plan and fails before changing the policy if a relevant remote value changed. The provider refreshes short-lived validation automatically at apply while keeping the exact definition, references, revision, and manager binding unchanged.

Manage Policies End To End

Use this workflow when Forge policies are owned by a security repository, reviewed in pull requests, and applied by CI.

Create a Forge service account with the Terraform policy-management preset. The token must have policy read and write scopes.
Export the token only in the Terraform shell or CI secret store.
Configure the provider with the target organization URL key, a stable manager_id, and a stable manager_instance.
Write policy resources in HCL.
Run a connected saved plan, review it, and apply that exact plan.
Confirm the policy in Forge Console and run a final no-op plan.

export FORGE_API_TOKEN="paste-token-from-forge"
export FORGE_ENDPOINT="https://api.forge.ai"

terraform init
terraform fmt -check
terraform validate
terraform plan -out=reviewed.tfplan
terraform show reviewed.tfplan
terraform apply reviewed.tfplan
terraform plan -detailed-exitcode

The final terraform plan -detailed-exitcode should report no changes. In Forge Console, the policy should show Terraform authority with the configured manager values. Console editing is locked for Terraform-managed policies so operators cannot accidentally fork production policy state.

Example: Deploy direct Resource access

Terraform creates the Gateway and Resource assignment, but never receives a runtime deployment credential. After apply, open the Resource Gateway in Forge Console, create its Docker Compose files, and run them in the target network. The files are shown once; their deployment credential remains valid until it is rotated by creating fresh files.

resource "forge_resource_gateway" "production" {
  name     = "Production access"
  hostname = "resources.example.com"
}

resource "forge_resource" "production_database" {
  name                = "Production PostgreSQL"
  protocol            = "postgres"
  upstream_host       = "db.internal.example"
  upstream_port       = 5432
  upstream_tls        = true
  gateway_id          = forge_resource_gateway.production.id
  transparent_routing = true
}

This Resource supports direct access through the customer-deployed Gateway and automatic routing from managed devices. Keep gateway_id and set transparent_routing = false for direct-only access. Forge computes access_name for direct client instructions.

Example: Protect PostgreSQL end to end

This minimal configuration wires the Gateway, Resource, destination credential, and Resource Policy. Terraform 1.11 or newer keeps the password out of plan and state through a write-only ephemeral value.

variable "database_password" {
  type      = string
  sensitive = true
  ephemeral = true
}

resource "forge_resource_gateway" "production" {
  name     = "Production access"
  hostname = "resources.example.com"
}

resource "forge_resource" "production_database" {
  name                = "Production PostgreSQL"
  protocol            = "postgres"
  upstream_host       = "db.internal.example"
  upstream_port       = 5432
  upstream_tls        = true
  gateway_id          = forge_resource_gateway.production.id
  transparent_routing = true
}

resource "forge_resource_credential" "production_database" {
  resource_id    = forge_resource.production_database.id
  name           = "Application account"
  kind           = "username_password"
  username       = "forge_app"
  secret         = var.database_password
  secret_version = 1
  default        = true
}

resource "forge_resource_policy" "block_deletes" {
  id          = "block-production-deletes"
  name        = "Block production database deletes"
  resources   = [forge_resource.production_database.id]
  enforcement = "enforce"
  action      = "block"
  severity    = "high"
  message     = "Use the approved data-retention workflow."

  conditions = {
    field = "request.postgres.command"
    op    = "eq"
    value = "DELETE"
  }
}

After apply, deploy the Gateway from the Console, test the credential and connection, run one allowed query and one DELETE in a non-production test database, and verify both outcomes under Live → Resources.

Example: Block an AI API destination

This Access policy blocks direct endpoint-route traffic to an unapproved AI API domain. It uses the native condition language, so it can be reviewed directly in Terraform plans and in the Forge policy editor.

resource "forge_access_policy" "unapproved_ai_api" {
  id                      = "unapproved-ai-api"
  name                    = "Block unapproved AI API destination"
  description             = "Block direct endpoint access to an unapproved AI API."
  action                  = "block"
  severity                = "high"
  acknowledge_broad_scope = true
  enforcement_surfaces    = ["endpoint_route"]

  conditions = {
    field = "destination.domain"
    op    = "eq"
    value = "api.deepseek.com"
  }
}

After apply, validate the user-visible workflow:

Open Policies in Forge Console.
Search for Block unapproved AI API destination.
Confirm the row says it is managed by Terraform.
Open the policy and confirm the action is Block, the surface is Endpoint route, and the condition is Destination domain equals api.deepseek.com.
From a protected endpoint, run a simple request such as:

curl -I --connect-timeout 8 https://api.deepseek.com

The request should be blocked once the endpoint has received the current policy bundle. A normal HTTP response from the destination indicates the endpoint did not enforce this policy on that traffic path.

Example: Block sensitive tool use

This Content policy blocks a high-risk tool call for one group at the pre_tool checkpoint.

resource "forge_content_policy" "customer_export" {
  id          = "customer-export"
  name        = "Protect customer exports"
  groups      = ["Finance"]
  evaluate_on = ["pre_tool"]
  action      = "block"

  module = <<-REGO
    package forge.content

    match := {
      "matched": input.tool.id == "customer.export",
      "reasonCode": "customer_export",
    }
  REGO
}

Use native conditions for straightforward comparisons and module for policy-as-code logic that needs branching, normalization, or multiple facts. Forge compiles and validates Rego on the server before mutation.

Example: Monitor production database writes

Resource Policies are separate from AI product Access Policies and agent session Content Policies. This example records PostgreSQL write attempts without blocking them during rollout: Resource is nevertheless a full policy family over the same condition, outcome, exception, revision, Rego, backtest, validation, and ownership infrastructure. Only its scope, protocol fields, monitoring mode, and capability-gated actions differ.

resource "forge_resource_policy" "production_writes" {
  id          = "production-writes"
  name        = "Protect production database writes"
  resources   = [forge_resource.production_database.id]
  enforcement = "monitor"
  action      = "block"
  message     = "Use the approved change workflow for production writes."

  conditions = {
    field = "request.postgres.command"
    op    = "in"
    value = ["INSERT", "UPDATE", "DELETE", "TRUNCATE"]
  }
}

Review the matches under Live → Resources, then change enforcement to enforce when the scope is ready. If Terraform already tracks this rule as forge_access_policy, change the HCL type and move the existing state address before planning:

terraform state mv \
  forge_access_policy.production_writes \
  forge_resource_policy.production_writes

Do not remove and recreate the policy. The state move preserves its server identity, revision history, exceptions, evaluations, and ownership.

What Terraform sends to Forge

The provider uses the headless Forge API. Terraform users usually should not call these endpoints directly for policy lifecycle management because the provider handles schema conversion, readable reference resolution, retries, idempotency, validation tokens, and state. The API sequence is:

Step	Forge API path	Purpose
Identify caller	`GET /api/headless/v1/whoami`	Confirms the token audience, principal type, organization access, and scopes.
Discover authorization	`GET /api/headless/v1/organizations/{organizationId}/capabilities`	Confirms which headless capabilities the token can use.
Negotiate policy contract	`GET /api/headless/v1/organizations/{organizationId}/policy-contracts/capabilities`	Confirms compatible policy schema, Rego version, Terraform protocol, and ownership binding.
Validate plan	`POST /api/headless/v1/organizations/{organizationId}/policy-plans/validate`	Binds the desired definition, references, expected revision, manager, and service-account principal into a short-lived validation token.
Apply policy	`POST` or `PUT` under `/content-policies`, `/access-policies`, or `/resource-policies`	Creates or updates the immutable policy revision with Terraform authority.
Verify state	`GET /api/headless/v1/organizations/{organizationId}/{family}-policies/{policyId}`	Reads the exact definition, current revision, digest, manager, and authority mode.

Every mutating Terraform API request includes:

Header	Purpose
`Authorization: Bearer <token>`	Authenticates the service account.
`X-Forge-Terraform-Manager`	Binds the change to the configured `manager_id`.
`X-Forge-Terraform-Instance`	Binds the change to the configured `manager_instance`.
`Idempotency-Key`	Makes retries safe for the same logical mutation.
`X-Forge-Reason`	Records the automation reason in audit evidence.
`X-Forge-Confirm: true`	Confirms a guarded write.

Resources

Resource	Purpose
`forge_content_policy`	Content policy with either native conditions or `forge.rego.v1` match logic, typed scope, stages, action, approval, redaction, and filtering
`forge_access_policy`	Access policy with either native conditions or `forge.rego.v1` match logic, typed scope, action, approval, and remediation
`forge_resource_policy`	Resource Policy with Resource and identity scope, HTTP, PostgreSQL, MySQL, and Redis fields, enforce or monitor mode, supported transformations, approval, messages, and exceptions
`forge_resource`	HTTP, HTTPS, PostgreSQL, MySQL, or Redis destination, verified transport, enabled state, and optional automatic routing
`forge_resource_gateway`	Customer-deployed runtime for direct and automatic Resource access; runtime health remains operational Console data
`forge_resource_credential`	Independently managed, write-only destination credential with default or identity assignments
`forge_llm_gateway_access_profile`	Native gateway access profile, model selectors, and atomic provider route plan used by the production gateway runtime; gateway keys assign callers
`forge_mcp_acl`	Readable MCP server/tool ACL compiled to a Content policy
`forge_skill_acl`	Readable skill grant or block
`forge_policy_authority`	Explicitly claim/release an existing Forge-managed policy at an expected revision

Typed data sources resolve one exact customer-visible selector through the same organization-scoped resolver used by connected plans:

Data source	Resolves
`forge_user`, `forge_group`	Active directory subjects; optional qualifier disambiguates duplicate labels
`forge_agent`, `forge_ai_product`	Inventory targets with actual Content-policy applicability
`forge_integration`	Connected integration or supported enforcement connection
`forge_mcp_server`, `forge_mcp_tool`, `forge_skill`	Approved registry objects; MCP tools require a resolved parent server
`forge_gateway_provider`	Configured LLM Gateway provider
`forge_rego_test`	Compiles and evaluates a module against native HCL input and asserts the expected match during `terraform test`

Missing and ambiguous references fail rather than selecting the first result.

Supported automation use cases

Use case	Resource or API	What to show
Content policy-as-code	`forge_content_policy`	Manage prompt, tool, response, redaction, approval, filter, and Rego policies from a reviewed repository.
Access policy-as-code	`forge_access_policy`	Manage endpoint-route, inline-hook, or provider-enforced Access policies such as destination-domain blocks.
Resource policy-as-code	`forge_resource_policy`	Manage Resource connections, HTTP JSON controls, PostgreSQL/MySQL commands and results, Redis commands, approval, and Rego.
Resource access	`forge_resource`, `forge_resource_gateway`, `forge_resource_credential`	Configure direct or automatic routing and broker destination credentials without storing secrets in Terraform state.
MCP access control	`forge_mcp_acl`	Grant or block exact MCP servers and tools for users or groups while retaining Terraform ownership.
Skill access control	`forge_skill_acl`	Grant or block exact registered skills for users, groups, or everyone.
LLM Gateway routing	`forge_llm_gateway_access_profile`	Manage gateway access profiles, model patterns, provider routes, limits, and policy behavior.
Gateway service accounts	`forge_llm_gateway_service_account`	Create and disable runtime Gateway callers from code.
Managed developer overrides	`forge_llm_gateway_managed_access_override`	Codify managed access exceptions for a user, group, or service account.
Device Gateway identity	`forge_device_gateway_identity_assignment`	Assign or clear the Gateway identity used by a managed device.
Existing policy adoption	`forge_policy_authority`	Claim a console-authored policy at an exact reviewed revision before importing it into Terraform.

Production validation

Qualify each resource against your target Forge environment before production rollout. Use the same provider version, service-account scopes, organization, manager identity, and remote state backend that you will use in production.

Resource	Required pre-production lifecycle checks
`forge_content_policy`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy.
`forge_access_policy`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy.
`forge_resource_policy`	Create, refresh/no-op, update, every supported action/data target, monitor/enforce transition, approval, import, drift recovery, ownership rejection, and destroy.
`forge_resource`	Create, connection test, route update, refresh/no-op, import, ownership rejection, and destroy.
`forge_resource_gateway`	Create, deploy through Console, status refresh, assignment update, import, ownership rejection, and destroy.
`forge_resource_credential`	Create with an ephemeral secret, refresh with no secret in state, rotate by version, assignment update, import, and destroy.
`forge_llm_gateway_access_profile`	Create, refresh/no-op, route-plan update, import, exclusive-ownership rejection, and destroy; verify the resulting live gateway route.
`forge_mcp_acl`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy; verify the resulting live MCP decision.
`forge_skill_acl`	Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy; verify the resulting live skill decision.
`forge_policy_authority`	Claim at the reviewed revision, reject stale revisions and other managers, import the matching policy, release, and confirm the policy remains.

For every row, confirm that failed validation or ownership checks leave the remote resource unchanged, the final no-op plan is empty, and the Forge audit trail identifies the expected service account and manager.

Import IDs

Every resource imports by its stable Forge identifier:

Resource	Import value
`forge_content_policy`	Policy `id`
`forge_access_policy`	Policy `id`
`forge_resource_policy`	Policy `id`
`forge_resource`	Resource `id`
`forge_resource_gateway`	Resource Gateway `id`
`forge_resource_credential`	`<resource-id>/<credential-id>`
`forge_llm_gateway_access_profile`	Profile `id`
`forge_mcp_acl`	ACL `id`
`forge_skill_acl`	ACL `id`
`forge_policy_authority`	Existing policy `id`, loaded into `policy_id`

Import reads state; it never bypasses or implicitly claims policy authority.

Provider arguments

Argument	Required	Description
`organization_id`	Yes	Forge organization to manage
`manager_id`	Yes	Stable durable manager/repository identity
`manager_instance`	Yes	Stable deployment/state identity
`api_token`	No	Sensitive token; prefer `FORGE_API_TOKEN`
`endpoint`	No	Control-plane URL; defaults to `FORGE_ENDPOINT` then the hosted API

Reference

Policy Resources

Access, Content, and Resource schemas, native conditions, actions, examples, and readable references.

Gateway Profile

LLM gateway access-profile and route-plan attributes with a complete example.

Registry ACLs

MCP and skill ACL resources, parameter descriptions, and examples.

Conditions

Policy field types, exact meanings, operators, and history-aware matching.

Authority

Attribute	Requirement and type	Exact meaning
`policy_id`	Required string; forces replacement	Existing Forge-managed durable policy ID to claim.
`expected_revision`	Required integer; forces replacement	Revision reviewed by the operator. The claim fails atomically if the remote revision differs.
`id`	Computed string	Provider state identity for the authority binding.
`current_revision`	Computed integer	Revision present when the binding is read.
`management_mode`	Computed string	Must be `terraform` after a successful claim.
`manager_id` / `manager_instance`	Computed strings	Server-confirmed exclusive manager binding; must equal provider configuration.

Replacement or destroy releases the claim; it does not disable, delete, or tombstone the underlying policy.

Ownership, adoption, and import

New resources are atomically created as Terraform-managed. To adopt an existing Forge-managed policy:

resource "forge_policy_authority" "customer_export" {
  policy_id         = "customer-export"
  expected_revision = 7
}

Read the policy’s current revision and review its definition.
Apply forge_policy_authority; the claim fails if the revision changed.
Keep the authority resource in state.
Add the corresponding policy resource with the exact remote definition.
Import it, for example:

terraform import forge_content_policy.customer_export customer-export

Import never claims authority implicitly. Importing before a claim, using a different manager binding, or removing the authority resource while the policy remains in state produces an authority error. Destroying the authority resource releases ownership back to Forge; destroying a policy resource disables and tombstones the policy.

Emergency Break glass

An organization owner can use Break glass on the console’s read-only policy view during an active incident:

Open Policies from the side navigation.
Open the Terraform-managed policy.
Confirm the review panel says Managed by Terraform. Console editing is locked.
Select Break glass.
Enter a 10–1,024 character incident reason.
Select Detach Terraform.

Forge creates a new immutable Forge-managed revision from the definition shown in the editor, records policy_family.break_glass in the organization audit log with the owner and reason, clears the Terraform manager binding, closes the Break glass dialog, and unlocks console editing. The policy record changes from Authority: Terraform to Authority: Forge. The old Terraform state cannot silently revert the emergency revision. A subsequent Terraform refresh or plan fails with an authority conflict similar to policy is managed by forge; explicitly claim it with forge_policy_authority before import. Recovery requires a reviewed Terraform claim or transfer.

Drift, retries, and state

Updates use the last observed immutable revision for optimistic concurrency.
Refresh verifies the exact Terraform manager and restores readable selectors.
Remote 404 removes the resource from Terraform state.
Destroy records a forward-only tombstone. The same authenticated manager_id + manager_instance can recreate that resource from the same state after destroy; the server assigns the next revision and preserves the complete history. A different manager cannot reuse the tombstoned ID.
Reads, updates, and deletes have bounded retries for 429 and 5xx errors.

Use lifecycle { prevent_destroy = true } for policies that need a separate retirement review. Terraform state contains policy configuration, sensitive match values, and an expiring signed plan-binding token; store it in an encrypted backend with narrow access. Never put API tokens or secret material in Rego source, selector names, descriptions, or filter values. Terraform applies resources independently. A multi-resource plan is not an atomic policy bundle: earlier resources can commit while a later reference, validation, authority, or network error fails the apply. Use one remote state writer, preserve the saved plan, and run a refresh plus policy-impact review after any partial failure. This guide assumes state created with a v0.3.x provider. Review the release notes and a saved plan before upgrading earlier state. The provider rejects an incompatible Forge deployment before planning a mutation. Rego modules and readable references are validated by the target Forge server during planning. terraform validate and an offline terraform plan -refresh=false prove only HCL/provider schema validity. A connected saved plan validates references, policy semantics, revision, and manager compatibility. Apply refreshes the short-lived signature and fails without mutation if any validated fact changed.

CI workflow

terraform fmt -check
terraform init
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

Pin the provider to a reviewed compatible minor line and commit the dependency lock file. Upgrade by changing the version constraint, running terraform init -upgrade, reviewing provider checksums and the complete plan, and applying a saved plan. Do not combine a provider upgrade with unrelated policy scope or action changes. Run plans with one writer per state backend. Review policy deletions, authority changes, scope expansion, stronger consequences, Rego source changes, and gateway limits as security-sensitive changes.

Troubleshooting

Error	What to check
Reference not found or ambiguous	Exact spelling, organization, directory qualification, and duplicates
Authority conflict	Claim resource, stable manager values, correct API organization, and current state
Revision conflict	Refresh and review the remote change before replanning
Rego validation failed	Package, fixed entrypoint, input fields, forbidden built-ins, and output schema
Destroy rejected	Current revision, authority binding, `prevent_destroy`, and API permission

Guides

REST API

Configure the provider

Manage Policies End To End

Example: Deploy direct Resource access

Example: Protect PostgreSQL end to end

Example: Block an AI API destination

Example: Block sensitive tool use

Example: Monitor production database writes

What Terraform sends to Forge

Resources

Supported automation use cases

Production validation

Import IDs

Provider arguments

Reference

Policy Resources

Gateway Profile

Registry ACLs

Conditions

Authority

Ownership, adoption, and import

Emergency Break glass

Drift, retries, and state

CI workflow

Troubleshooting

​Configure the provider

​Manage Policies End To End

​Example: Deploy direct Resource access

​Example: Protect PostgreSQL end to end

​Example: Block an AI API destination

​Example: Block sensitive tool use

​Example: Monitor production database writes

​What Terraform sends to Forge

​Resources

​Supported automation use cases

​Production validation

​Import IDs

​Provider arguments

​Reference

Policy Resources

Gateway Profile

Registry ACLs

Conditions

​Authority

​Ownership, adoption, and import

​Emergency Break glass

​Drift, retries, and state

​CI workflow

​Troubleshooting

Configure the provider

Manage Policies End To End

Example: Deploy direct Resource access

Example: Protect PostgreSQL end to end

Example: Block an AI API destination

Example: Block sensitive tool use

Example: Monitor production database writes

What Terraform sends to Forge

Resources

Supported automation use cases

Production validation

Import IDs

Provider arguments

Reference

Authority

Ownership, adoption, and import

Emergency Break glass

Drift, retries, and state

CI workflow

Troubleshooting