Skip to main content
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
Agents use a pull-based model and require only outbound TCP/443 access to Terraform Cloud.

​
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.
ComponentDescriptionExample Command
Agent PoolLogical grouping of agentsManage under Settings → Agents
API TokenScoped to one pool; used by each registered agentCreated via the Create token button
Agent NameUnique identifier for each host/containereast-dc-1, us-west-2
  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.
Keep your agent tokens confidential. Rotate or revoke tokens regularly to maintain security.

​
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
The image shows a software interface displaying agent pool information, including agent names, core versions, statuses, IDs, IP addresses, and last seen times. The sidebar includes navigation options like "Agents," "API tokens," and "Authentication."

​
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.
The image shows a dashboard interface for a DevOps application, displaying details of a recent run, including policy checks, estimated cost increase, and resource changes. It includes navigation options like Overview, Runs, States, Variables, and Settings.
The image shows a Terraform Cloud workspace settings page with options for execution mode, including Remote, Local, and Agent. A warning indicates that the selected agent pool has no registered agents.
The image illustrates a datacenter setup with production and non-production environments, showing workloads, Vault, Kubernetes nodes, and an agent. It highlights outbound connectivity to HashiCorp Terraform Cloud via TCP/443, with no inbound connectivity required.

​
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:
The image shows a Terraform Cloud interface where a run has been triggered via the UI, indicating that the plan finished with no changes needed to the infrastructure. It includes details like the commit message, execution mode, and agent pool information.
When changes are pushed, the agent will perform apply as well:
The image shows a Terraform Cloud interface displaying the progress of a run, including details like configuration, commit, and execution mode, with steps such as plan, cost estimation, policy check, and apply status.

​
Scaling with Multiple Agents

To increase throughput, register additional agents to the same pool. Your Terraform Cloud license determines the maximum concurrent agents.
The image shows a user interface for managing agent pools in Terraform Cloud, displaying details such as agent names, core versions, statuses, IDs, IP addresses, and last seen times. The sidebar includes options for organization settings, integrations, and security.

​
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.
The image shows a settings page for an "Agent pool" named "development" with options to grant access to workspaces and manage tokens. The left sidebar displays various organization settings and integrations.
The image shows a user interface for managing workspaces and tokens, with options to grant access to workspaces and manage tokens, including creating and revoking them. The sidebar includes navigation options like General, Tags, Teams, and Agents.
Terraform Cloud Agents enable secure, scalable execution of Terraform runs within your network perimeter, giving you full control over connectivity and resources.

​
References

Watch Video