Demo Terraform Cloud Run Agents

In this guide, we’ll walk through setting up Terraform Cloud’s self-hosted agents—a Business tier feature that allows Terraform runs to execute within your private network. By using agents, you eliminate the need to expose sensitive endpoints publicly, making them ideal for on-premises data centers, private VPCs, or any environment where Terraform Cloud cannot directly reach your infrastructure.

Table of Contents

1. Prerequisites
2. Creating an Agent Pool and Token
3. Installing and Running an Agent on Linux
4. Running an Agent in Docker
5. Agent Auto-Update Behavior
6. Configuring a Workspace for Agent Execution
7. Running Terraform via the Agent
8. Scaling with Multiple Agents
9. Managing Pools and Tokens
10. References

Prerequisites

• A Terraform Cloud organization on the Business tier
• Permissions to manage Settings → Agents
• Outbound TCP/443 connectivity to app.terraform.io

Creating an Agent Pool and Token

An Agent Pool is a logical group of self-hosted agents. You scope pools to environments (e.g., development, production) and assign tokens for authentication.

1. Navigate to Settings → Agents in your Terraform Cloud organization.
2. Click New Agent Pool, name it (e.g., development), and save.
3. In the pool’s page, click Create token, scope it to your data center or environment (e.g., EastDC), and copy the value.

Installing and Running an Agent on Linux

Download and unzip the latest agent binary on any Linux host:

# Replace with the current stable version if newer
curl -Lo tfc-agent_1.3.1_linux_amd64.zip \
  https://releases.hashicorp.com/tfc-agent/1.3.1/tfc-agent_1.3.1_linux_amd64.zip
unzip tfc-agent_1.3.1_linux_amd64.zip

Set environment variables and start the agent:

export TFC_AGENT_TOKEN=<your_agent_pool_token>
export TFC_AGENT_NAME=east-dc-1
./tfc-agent

On launch, you’ll see a registration confirmation:

2022-10-05T12:14:31.806Z [INFO] core: Agent registered successfully with Terraform Cloud: agent.name=east-dc-1

Running an Agent in Docker

Alternatively, launch an agent as a Docker container:

export TFC_AGENT_TOKEN=<your_agent_pool_token>
export TFC_AGENT_NAME=east-dc-2
docker run -e TFC_AGENT_TOKEN -e TFC_AGENT_NAME hashicorp/tfc-agent:latest

This pulls the latest image, auto-updates its core if enabled, and registers to your specified pool.

Agent Auto-Update Behavior

Agents check for newer core versions by default. Sample logs:

2022-10-05T12:14:30.066Z [INFO] agent: Core update is available: version=1.4.0
2022-10-05T12:14:31.061Z [INFO] agent: Core successfully updated: version=1.4.0

To manage updates manually, disable auto-updates under Settings → Agents → [Your Pool].

Configuring a Workspace for Agent Execution

1. Go to Workspaces → [Your Workspace] in Terraform Cloud.
2. Under Settings → Execution Mode, select Agent.
3. Choose your development pool and save.

Running Terraform via the Agent

Trigger a run in the workspace. The agent logs will indicate progress:

2022-10-05T12:18:38.117Z [INFO] core: Job received: job.type=plan job.id=run-XXXXX
2022-10-05T12:19:38.105Z [INFO] terraform: Terraform CLI details: version=1.2.7
2022-10-05T12:19:38.717Z [INFO] terraform: Running terraform init
2022-10-05T12:19:48.210Z [INFO] terraform: Running terraform plan

Back in the UI, you’ll see the plan complete:

When changes are pushed, the agent will perform apply as well:

Scaling with Multiple Agents

To increase throughput, register additional agents to the same pool. Your Terraform Cloud license determines the maximum concurrent agents.

Managing Pools and Tokens

• Create multiple tokens per pool or assign one per agent.
• Rotate or revoke tokens under Settings → Agents → [Your Pool] → Tokens.
• Delete agents or pools when no longer in use—ensure they aren’t linked to active workspaces.

Terraform Cloud Agents enable secure, scalable execution of Terraform runs within your network perimeter, giving you full control over connectivity and resources.

References

• Terraform Cloud Agents Documentation
• Terraform Cloud Workspaces
• HashiCorp Releases