HCP Terraform Execution Modes

​

Execution modes — at a glance

• Remote (default)
• Local
• Agent (self-hosted)

​

Remote (default)

• Team collaboration and visibility: runs, plans, and who triggered them are visible in the HCP UI.
• Full feature access: remote execution enables features such as policy enforcement, cost estimation, notifications, run logs, and detailed run output.
• Secure, managed environment: HCP handles ephemeral worker provisioning, isolation, and maintenance.

• Terraform state is stored remotely in the workspace. HCP manages locking, versioning, and encryption for the remote state.

• Recommended for most teams that want the full HCP feature set and consistent, auditable runs.

​

Local

• Developers who want to run Terraform locally while retaining remote state, locking, and state history in HCP.

• The workspace state remains in HCP (remote state), so you still get locking, encryption, and version history. The actual plan/apply executes locally.

# Create plan locally
terraform plan -out=tfplan

# Apply the locally created plan
terraform apply tfplan

• Workspace variables and variable sets configured in the HCP UI are NOT injected into local CLI runs. When you run locally, Terraform reads variables from:
  • Command-line flags: -var 'key=value' or -var-file=secrets.tfvars
  • Local .tfvars files
  • Environment variables: TF_VAR_<NAME>

# Using an inline var
terraform plan -var 'region=us-west-2'

# Using a var-file
terraform plan -var-file="envs/prod.tfvars"

# Using an environment variable
export TF_VAR_db_password='s3cr3t'
terraform apply

​

Agent (self-hosted agent)

• The agent establishes an outbound connection to HCP. The HCP control plane sends run requests to the agent over that connection.
• Plan and apply operations execute on the self-hosted agent, enabling the agent to reach resources that HCP-managed workers cannot.
• The same agent model can support both HCP Terraform and Terraform Enterprise, allowing consistent execution behavior across products.

• Managing resources in private datacenters or networks without inbound access.
• Environments that require execution to remain on customer-controlled infrastructure.
• Workflows that need agents to access internal APIs, VMWare, private clouds, or isolated Kubernetes clusters.

• Agents communicate outbound to HCP, which simplifies firewall rules (no inbound required).
• You are responsible for securing and maintaining the agent hosts according to your organization’s policies.

• As with other modes, workspace state is stored remotely in HCP. The agent performs the execution but relies on HCP for state coordination, locking, and history.

​

Execution modes comparison

​

Putting it all together — practical examples

• Networking or application workspace that benefits from HCP features: use remote execution to leverage policy enforcement, cost estimation, and run visibility.
• Monitoring or infrastructure that must reach private resources: use agent mode to keep execution inside the private network while using HCP for state coordination.
• A database or operations team that prefers to run applies from laptops: use local execution but ensure CLI receives necessary variables via -var, -var-file, or TF_VAR_*.

• Execution mode is configured per workspace. Choose the mode that matches access constraints, security requirements, and desired HCP features for each workspace.

​

Links and references

• HCP Terraform: https://learn.kodekloud.com/user/courses/hashicorp-terraform-cloud
• Terraform CLI docs: https://learn.kodekloud.com/user/courses/terraform-basics-training-course
• Terraform Enterprise documentation: https://www.hashicorp.com/products/terraform-enterprise
• Best practices for remote state: https://www.terraform.io/docs/state/index.html