HCP Terraform: pick the right execution mode per workspace

TL;DR

Use when runs must reach private networks, on-prem systems, or use local tooling. A workspace set to Remote runs on HCP's machines; a workspace set to Local runs on whatever machine triggered it, and HCP only stores state and variables. The run UI shows the full log. Use when you need private network access but want centralized execution without tying runs to a laptop.

When to use

You are seeing this: Runs execute on HCP Terraform's disposable VMs with a consistent environment. Use this skill when you run into "HCP Terraform: pick the right execution mode per workspace".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

The three modes

1. Remote (default). Runs execute on HCP Terraform's disposable VMs with a consistent environment. Best when your runs need no private network access. The run UI shows the full log.
2. Local. Terraform runs on the operator's machine or CI runner; HCP stores state, variables, and run history. Use when runs must reach private networks, on-prem systems, or use local tooling.
3. Agent. Runs execute on your own long-lived agent VMs that poll HCP. Use when you need private network access but want centralized execution without tying runs to a laptop.

A project can set a default execution mode, and individual workspaces override it.

Rules for agents

1. If a run fails with network errors to private endpoints, check the execution mode before debugging the config. A Remote-mode workspace cannot reach your VPC.
2. Local mode means the machine running Terraform needs the right CLI version and provider credentials. Version drift between machines becomes your problem.
3. Do not flip a workspace to Local to dodge a Remote-mode failure without understanding why it failed. The mode is load-bearing.
4. Variable sets and run triggers behave the same across modes; only the execution environment changes.

Why

HCP Terraform workspaces can execute runs in three places, and the default is not always what an agent expects. A workspace set to Remote runs on HCP's machines; a workspace set to Local runs on whatever machine triggered it, and HCP only stores state and variables.

HCP Terraform workspace settings define Execution Mode: Project Default, Remote (runs on HCP's disposable VMs), Local, and Agent. Verified on the live workspaces settings docs page. Verified against live docs 2026-09-26.