Terraform Cloud Agents provide a secure bridge between HCP Terraform and infrastructure that cannot be reached from the public internet. Instead of exposing internal APIs and endpoints to the internet, the agent runs inside the protected network and initiates outbound communication to Terraform Cloud. This model preserves network security while enabling provisioning and management of on-premises and private cloud resources.
Understanding Terraform Cloud Agents
Terraform Cloud Agents are lightweight processes that poll Terraform Cloud for work, execute Terraform runs locally, and report results back.
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.
HCP Terraform agents let you manage isolated, private, or on-premises infrastructure while keeping your network secure.
Note: Your HCP Terraform plan determines the number of agents you can use. Refer to HCP Terraform pricing for details.
HCP Terraform Agents allow HCP Terraform 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 HCP Terraform, facilitating provisioning and management operations. This is useful for on-premises infrastructure types such as vSphere, Nutanix, OpenStack, enterprise networking providers, and any systems in a protected enclave.
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.
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.
Architecture and Connectivity Model
The agent requires only outbound connectivity to HCP Terraform, enabling private networks to remain secure. No special networking configuration or exceptions are typically needed.
The agent requires outbound HTTPS, port 443 access to:
- app.terraform.io
- or your Terraform Enterprise hostname
- registry.terraform.io for provider downloads
- Any provider-specific endpoints such as 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
The agent software runs on your own infrastructure. The token you provide when starting the agent assigns it to an HCP Terraform agent pool.
If you have your Agent pool and token already set up, start the agent using the official Docker image.
Each agent process runs a single Terraform run at a time. Multiple agent processes can be concurrently run on a single instance, license limit permitting.
The agent distributes as a standalone binary that runs on any supported system. By default, the agent runs in the foreground as a long-running process that continuously polls for workloads from HCP Terraform
Agents do not guarantee a clean working environment per Terraform execution. Each execution occurs in its own temporary directory with a clean environment, but references to absolute file paths or other machine state may cause interference between Terraform executions. We strongly recommend that you write your Terraform code to be stateless and idempotent. You may also want to consider using single-execution mode to ensure your agent only runs a single workload.
You may choose to run multiple agents within your network, up to the organization's purchased agent limit. If there are multiple agents available within an organization, HCP Terraform selects the first available agent within the target pool.
Supported Platforms and Requirements
Before Install considerations include supported operating systems and 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
The following table summarizes platform and version constraints.
| Category | Detail |
|---|---|
| Minimum Terraform version | 0.12 and above |
| Network | Outbound HTTPS 443 only, no inbound required |
| Operating system support | Any supported system with standalone binary |
| Execution model | Pull-based polling, foreground long-running process |
| Concurrency per process | One Terraform run at a time |
The agent requires only outbound connectivity to HCP Terraform, enabling private networks to remain secure.
Note: Your HCP Terraform plan determines the number of agents you can use. Refer to HCP Terraform pricing for details.
Terraform Cloud Agents are a paid feature, available as part of the Terraform Cloud for Business upgrade package. Learn more about Terraform Cloud pricing here. The number of agents you are eligible to deploy is determined by the number of concurrent runs your organization is entitled to.
Terraform Enterprise supports HCP Terraform Agents. Refer to HCP Terraform Agents on Terraform Enterprise for Terraform Enterprise specific documentation and requirements.
Installation Guide for Ubuntu
The guide walks you through everything you need to know to install, configure, and operate Terraform Cloud Agents on Ubuntu.
Network Requirements verification
The agent requires outbound HTTPS, port 443 access to:
app.terraform.io
or your Terraform Enterprise hostname
registry.terraform.io for provider downloads
Any provider-specific endpoints
Test connectivity commands are shown above.
Installing Terraform CLI
While not strictly required for running the agent, having Terraform CLI installed helps with debugging and local testing.
sudo apt-get update
sudo apt-get install -y gnupg software-properties-common curl
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
gpg --no-default-keyring --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg --fingerprint
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" |
Create Environment File
Create secure environment file for the agent token
```
sudo tee /etc/tfc-agent.env << 'EOF'
Terraform Cloud Agent Configuration
This token authenticates the agent with Terraform Cloud
TFCAGENTTOKEN=your-agent-token-here
Optional: Custom agent name for identification in Terraform Cloud UI
TFCAGENTNAME=ubuntu-prod-agent-01
Optional: Set log level (trace, debug, info, warn, error)
TFCAGENTLOG_LEVEL=info
Optional: Custom data directory
TFCAGENTDATA_DIR=/var/lib/tfc-agent
Optional: Disable automatic updates (recommended for production)
TFCAGENTAUTO_UPDATE=disabled
EOF
sudo chmod 600 /etc/tfc-agent.env
sudo chown root:root /etc/tfc-agent.env
```
Log file location reference used in operational setups
/var/log/tfc-agent
Configuration and Systemd Service
Create systemd Service Unit
```
sudo tee /etc/systemd/system/tfc-agent.service << 'EOF'
[Unit]
Service description for systemd
Description=Terraform Cloud Agent
Documentation=https://developer.hashicorp.com/terraform/cloud-docs/agents
Start after network is available
After=network-online.target
Wants=network-online.target
[Service]
Run as dedicated user for security
User=tfc-agent
Group=tfc-agent
Load environment variables from secure file
EnvironmentFile=/etc/tfc-agent.env
Agent binary location
ExecStart=/opt/tfc-agent/tfc-agent
Restart policy - always restart on failure
Restart=on-failure
RestartSec=5
Stop timeout - allow time for graceful shutdown
TimeoutStopSec=30
Security hardening
EOF
```
The token you provide when starting the agent assigns it to an HCP Terraform agent pool.
The agent architecture is pull-based, so no inbound connectivity is required.
Operational Behavior and Limits
Hands-on: Try the Manage Private Environments with HCP Terraform Agents tutorial.
Hands-on: Try the Manage Private Environments with Terraform Cloud Agents tutorial on HashiCorp Learn.
Account access prerequisites
- 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
- Access to create agent pools and generate tokens
Operational characteristics
- Each agent process runs a single Terraform run at a time
- Multiple agent processes can be concurrently run on a single instance, license limit permitting
- Agent distributes as standalone binary that runs on any supported system
- By default, the agent runs in the foreground as a long-running process that continuously polls for workloads from HCP Terraform
Limitations
Agents do not guarantee a clean working environment per Terraform execution. Each execution occurs in its own temporary directory with a clean environment, but references to absolute file paths or other machine state may cause interference between Terraform executions. We strongly recommend that you write your Terraform code to be stateless and idempotent. You may also want to consider using single-execution mode to ensure your agent only runs a single workload.
Terraform Cloud Agents vs AWS DevOps Agent
Getting started with AWS DevOps Agent using Terraform provides a different agent model focused on AWS DevOps.
Overview
This guide shows you how to use Terraform to create and deploy AWS DevOps Agent resources. The Terraform configuration automates the creation of an agent space, IAM roles, an operator app, and AWS account associations.
The Terraform approach automates the manual steps described in the CLI onboarding guide by defining all required resources as infrastructure as code.
AWS DevOps Agent is available in the following 6 AWS Regions:
- US East (N. Virginia)
- US West (Oregon)
- Asia Pacific (Sydney)
- Asia Pacific (Tokyo)
- Europe (Frankfurt)
- Europe (Ireland)
For more information about supported Regions, see Supported Regions.
Prerequisites
Before you begin, make sure you have the following:
- Terraform >= 1.0 installed
- AWS CLI installed and configured with appropriate credentials
- One AWS account for the monitoring (primary) account
- Optional: A second AWS account if you want to set up cross-account monitoring
What this guide covers
This guide is divided into two parts:
- Part 1 — Deploy an agent space with an operator app and an AWS association in your monitoring account. After completing this part, the agent can monitor issues in that account.
- Part 2 (Optional) — Add a source AWS association for a service account and deploy a cross-account IAM role plus an echo Lambda into that account
The AWS DevOps Agent workflow is distinct from HCP Terraform Agents, which focus on outbound polling to Terraform Cloud for Terraform run execution in private networks.
Best Practices and Security Hardening
The agent requires only outbound connectivity to HCP Terraform, enabling private networks to remain secure. No special networking configuration or exceptions are typically needed.
Secure the environment file with chmod 600 and ownership root:root.
Run the agent as a dedicated user for security, as shown in the systemd unit.
Disable automatic updates for production environments via TFCAGENTAUTO_UPDATE=disabled.
Set log level appropriately and store logs under /var/log/tfc-agent.
Write Terraform code to be stateless and idempotent to avoid interference between executions.
Consider single-execution mode to ensure your agent only runs a single workload.
Use agent pools and tokens to assign agents to specific workloads and limit exposure.
Conclusion
Terraform Cloud Agents provide a practical way to keep private and on-premises infrastructure isolated while still enabling Terraform Cloud to drive provisioning and management operations. The pull-based architecture eliminates the need for inbound firewall rules and reduces attack surface, since agents initiate outbound HTTPS connections only to app.terraform.io, registry.terraform.io, and provider endpoints. Deployment on Ubuntu follows a consistent pattern of installing the binary, securing a token via an environment file, and running the process as a systemd service with a dedicated user and restart policy.
Operational limits are important to respect. Each agent process handles one Terraform run at a time, and organizations are limited to the number of agents permitted by their HCP Terraform plan. The agent does not guarantee a fully clean machine state between runs, so stateless and idempotent Terraform code is strongly recommended, with single-execution mode available for stricter isolation. Version support starts at Terraform 0.12 and above, and hardware requirements scale with workspace complexity.
For AWS-focused observability, AWS DevOps Agent offers a separate Terraform-driven workflow to create agent spaces, IAM roles, operator apps, and cross-account associations in six supported AWS Regions. The prerequisites include Terraform >= 1.0, AWS CLI configuration, and at least one monitoring AWS account.
Together, these capabilities let teams extend Terraform automation securely into protected enclaves without compromising network posture.