Terraform Cloud Agents provide a secure mechanism to run Terraform operations inside private networks without exposing infrastructure to the public internet. Instead of requiring inbound access to internal systems, agents run within the target network and communicate outbound to Terraform Cloud, executing plan, apply, and destroy operations on behalf of the SaaS control plane.
What Terraform Cloud Agents Are
Terraform Cloud Agents are lightweight processes that poll Terraform Cloud for work, execute Terraform runs locally, and report results back. They are small binaries that can be installed in private clouds or on-premises that execute Terraform runs on behalf of the Terraform Cloud.
The agent architecture is pull-based, so no inbound connectivity is required. Any agent you provision will poll Terraform Cloud for work and carry out execution of that work locally. Agents connect to the Terraform Cloud API and process work items, allowing specific components such as Terraform plans and applies to run in external infrastructure, rather than on HashiCorp-hosted servers. This enables placing Terraform Cloud workloads in any network context desired.
Terraform Cloud Agents enable you to provision infrastructure in private networks that are isolated from the public internet. Instead of exposing your internal infrastructure to Terraform Cloud, agents run within your network and communicate outbound to Terraform Cloud, executing Terraform operations on your behalf.
Terraform Cloud is a SaaS application to provision and manage infrastructure using Terraform through a SOC 2 Type I Compliant and enterprise-ready solution for teams and companies. Terraform Cloud manages the Terraform state file and pulls changes in infrastructure from VCS providers like GitHub to trigger modifications on infrastructure.
Agents are small binaries, or a convenient docker image or a Kubernetes POD, that run inside a company data center on-premises infrastructure or in public or private cloud or both leveraging hybrid cloud. Terraform Cloud Agents are responsible for contacting the Terraform Cloud server to get instructions and execute the Terraform runs.
History and Availability
Terraform Cloud Agents are a new functionality announced by HashiCorp on August 12 2020 for its new Terraform Cloud Business Tier along with other enterprise functionality in the security and auditing space.
Terraform Cloud Agents are a paid feature, available as part of the Terraform Cloud for Business upgrade package. The number of agents you are eligible to deploy is determined by the number of concurrent runs your organization is entitled to.
Cloud agents are available across HCP Terraform tiers. The Free tier includes a limited number of agents, and paid tiers or Terraform Enterprise provide more. Organization admin or owner permissions and access to create agent pools and generate tokens are required.
Use Cases and Private Environments
Terraform Cloud Agents allow Terraform Cloud to communicate with isolated, private, or on-premises infrastructure. By deploying lightweight agents within a specific network segment, you can establish a simple connection between your environment and Terraform Cloud which allows for provisioning operations and management.
This is useful for on-premises infrastructure types such as vSphere, Nutanix, OpenStack, enterprise networking providers, and anything you might have in a protected enclave.
Until now companies that wanted to use Terraform Cloud needed to publish their infrastructure on the Internet, as each Terraform run was executed in HashiCorp servers in the public Cloud or had to install an on-premises edition named Terraform Enterprise. With Terraform Cloud Agents, a company can manage its private infrastructure as code and benefit from all the functionality of Terraform in a SaaS scenario.
Terraform allows companies to provision and manage cloud infrastructure using best practices by defining the infrastructure as code.
Deployment Options
Agents can be deployed as binaries, Docker containers, or Kubernetes pods.
The Terraform Cloud Agent handles auxiliary workloads for Terraform Cloud. Agents connect to the Terraform Cloud API and process work items, allowing specific components such as Terraform plans and applies to run in external infrastructure, rather than on HashiCorp-hosted servers.
The official container image is maintained by HashiCorp.
| Property | Value |
|---|---|
| Image name | hashicorp/tfc-agent |
| Content type | Image |
| Size | 334.5 MB |
| Example pull | docker pull hashicorp/tfc-agent:1.29.0 |
| Help command | docker run hashicorp/tfc-agent:latest help |
Detailed usage information may be obtained by pulling the container and running it with the "help" subcommand. Example:
docker run hashicorp/tfc-agent:latest help
For Kubernetes deployments, a Terraform Kubernetes Deployment resource can define agent configuration. Environment variables commonly used include:
TFC_AGENT_NAMETFC_AGENT_LOG_LEVEL
Example snippet:
env {
name = "TFC_AGENT_NAME"
value = "ditwl-agent-k8s-01"
}
env {
name = "TFC_AGENT_LOG_LEVEL"
value = "DEBUG"
}
The agent status can be viewed in the Terraform Cloud UI. Open https://app.terraform.io/ and go to Settings -> Agent page to see the status. A registered agent will show as ready to receive jobs.
To debug issues with the Agent or with Terraform, increase the log level, and check agent logs using the Kubernetes Dashboard or the command line. Do not set the environment variable TFLOG. TFLOG is used to debug Terraform plans in a command-line execution of Terraform, but if set the agent fails as it is not prepared to deal with debug messages from the Terraform binary in this way.
Prerequisites and Network Requirements
Network Requirements
The agent requires outbound HTTPS port 443 access to:
| Destination | Purpose |
|---|---|
| app.terraform.io | Terraform Cloud control plane, or your Terraform Enterprise hostname |
| registry.terraform.io | Provider downloads |
| Provider-specific endpoints | AWS, Azure, GCP APIs, etc. |
Test connectivity to Terraform Cloud:
curl -I https://app.terraform.io
Expected: HTTP/2 200 or similar success response
Test connectivity to the Terraform registry:
curl -I https://registry.terraform.io
Expected: HTTP/2 200 or similar success response
Supported Platforms and Versions
Supported Terraform Versions
Agents support Terraform versions 0.12 and above. Workspaces configured to use Terraform versions below 0.12 will not be able to select the agent-based execution mode.
Hardware Requirements
The host running the agent will have varying resource requirements depending on the workspace.
Supported Operating Systems are documented in the Terraform Cloud Agents documentation.
Before Install steps should be completed to ensure prerequisites are met.
Installing Terraform CLI on Ubuntu
While not strictly required for running the agent, having Terraform CLI installed helps with debugging and local testing.
Update package index:
sudo apt-get update
Install required dependencies:
sudo apt-get install -y gnupg software-properties-common curl
Add HashiCorp GPG key:
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
Verify the key fingerprint:
gpg --no-default-keyring --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg --fingerprint
Add the official HashiCorp repository:
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" |
The guide walks through everything you need to know to install, configure, and operate Terraform Cloud Agents on Ubuntu.
Agent Configuration and Operation
Terraform Cloud Agents are lightweight processes that poll Terraform Cloud for work, execute Terraform runs locally, and report results back.
With Terraform Cloud Agents, a company can manage its private infrastructure as code and benefit from all the functionality of Terraform in a SaaS scenario.
The pull-based architecture means no inbound connectivity is required. Agents run inside a company data center on-premises infrastructure or in public or private cloud or both leveraging hybrid cloud.
Terraform Cloud Agents enable you to provision infrastructure in private networks that are isolated from the public internet. Instead of exposing your internal infrastructure to Terraform Cloud, agents run within your network and communicate outbound to Terraform Cloud, executing Terraform operations on your behalf.
Hands-on: Try the Manage Private Environments with Terraform Cloud Agents tutorial on HashiCorp Learn.
Conclusion
Terraform Cloud Agents extend Terraform Cloud to private and hybrid environments without requiring public exposure of infrastructure. The pull-based, lightweight agent model enables secure execution of plan, apply, and destroy operations inside protected enclaves while retaining SaaS benefits such as state management, VCS-driven runs, and SOC 2 Type I compliant control plane.
Agents are available as binaries, Docker images, and Kubernetes pods, with support for Terraform 0.12 and above. Deployment requires outbound HTTPS access to app.terraform.io, registry.terraform.io, and provider endpoints, and is governed by Business tier licensing with agent counts tied to concurrent runs.
Operational practices include monitoring agent status via Settings -> Agent page, adjusting TFCAGENTLOGLEVEL for troubleshooting, and avoiding TFLOG which can cause agent failures. For Ubuntu hosts, installing the Terraform CLI via the official HashiCorp APT repository supports local debugging.
Together these capabilities allow organizations to manage vSphere, Nutanix, OpenStack, enterprise networking, and other on-premises resources as code within Terraform Cloud without opening inbound network paths.