# HCP Terraform: pick the right execution mode per workspace

## 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.

## 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.