> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running remote plan

> Run terraform plan locally while executing remotely on env zero with shared state, RBAC, cost estimation, and custom flows, with auditable results.

## Remote Plan

Remote Backend allows running your Terraform plan locally by triggering a remote plan in env zero.\
The remote plan uses your local Terraform files but actually runs it remotely in env zero while using the shared state and variables set for the env zero environment. Each remote plan creates a deployment in env zero so you will have an audit for each deployment.\
By running a remote plan you can build your IaC faster, and test your changes locally **before committing** them.

Additional benefits are the rest of the env zero features that are automatically integrated into your plan logs. It includes:

* [Role Based Access](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/user-management.md)
* [Custom Flows](https://docs.envzero.com/guides/admin-guide/custom-flows.md)
* [Cost Estimation](https://docs.envzero.com/guides/policies-governance/cost-estimation.md)
* [Variables and Secrets](https://docs.envzero.com/guides/admin-guide/variables.md)
* [Policies](https://docs.envzero.com/guides/policies-governance/policies.md)
* [Plugins](https://docs.envzero.com/guides/integrations/plugins.md)

![Terminal output showing terraform plan triggering a remote plan run in env zero](https://mintcdn.com/envzero-b61043c8/pvGFjFxaiqGDTFG3/images/guides/admin-guide/remote-backend/56b8b73-image_5.png?fit=max\&auto=format\&n=pvGFjFxaiqGDTFG3\&q=85\&s=41097d22f532e17c97138333b874409e)

![Remote plan output in the terminal showing plan results streamed from the env zero environment](https://mintcdn.com/envzero-b61043c8/pvGFjFxaiqGDTFG3/images/guides/admin-guide/remote-backend/a29345c-image_6.png?fit=max\&auto=format\&n=pvGFjFxaiqGDTFG3\&q=85\&s=01bb411d0563ce1121e3a5e141b5ad32)

## Save a plan and apply it later

Save a remote plan to a file, inspect it, and apply exactly that plan without planning again.

> [!WARNING]
>
> Saving and showing a plan requires the **Run Plan** permission. Applying it requires the **Run Apply** permission.

Requirements:

* OpenTofu 1.6 or later, or Terraform 1.6 or later
* The `cloud` block configuration from [Authenticate locally](https://docs.envzero.com/guides/admin-guide/remote-backend/login.md). The `backend "remote"` configuration can't save plans.
* Self-hosted agents: v5.1.0 or later

```bash OpenTofu theme={null}
tofu plan -out=<PLAN_FILE>
tofu show <PLAN_FILE>
tofu show -json <PLAN_FILE>
tofu apply <PLAN_FILE>
```

```bash Terraform theme={null}
terraform plan -out=<PLAN_FILE>
terraform show <PLAN_FILE>
terraform show -json <PLAN_FILE>
terraform apply <PLAN_FILE>
```

The plan runs as a remote plan deployment. The apply runs as a separate deployment, or as a destroy if you planned with `-destroy`. Running `apply` with the plan file is the confirmation, so the apply deployment does not wait for approval in env zero.

> [!WARNING]
>
> The output of `show -json` includes the values of sensitive variables and outputs in plain text. Treat the output as a secret.

Limitations:

* Apply a saved plan within 1 day of creating it.
* Each saved plan can be applied once. Applying it again fails.
* You can apply only a plan that succeeded.
* Workflow sub-environments do not support saved plans.

## .terraformignore

If cases where your gitrepo is particularly large, this will cause the remote plan to take a longer time to process (due to compressing and decompressing the gitrepo).  You can save time on the remote plan by adding a [`.terraformignore`](https://opentofu.org/docs/cli/cloud/settings/#excluding-files-from-upload-with-terraformignore) to the root of the repo.

```.terraformignore theme={null}
/**
!my-working-dir/
my-working-dir/.terraform
my-working-dir/.terraform/**
```

> [!WARNING]
>
> ignore the local `.terraform` folder
>
> If you have a local `.terraform` folder, please add it to the ignore list (like in the example above), otherwise you may get some errors such as `workspace not supported`

## Auditing

env zero UI can show you each remote plan deployment that has occurred, accesses its plan logs, and gives you visibility and audit on who actually trigged it from their local environment.

![env zero UI showing audit trail of remote plan deployments with user and commit information](https://mintcdn.com/envzero-b61043c8/pvGFjFxaiqGDTFG3/images/guides/admin-guide/remote-backend/ff2b45e-image_4.png?fit=max\&auto=format\&n=pvGFjFxaiqGDTFG3\&q=85\&s=2496b102e557e75501df60da4ed15da5)

## Local Executions

If you still wish to run a `plan` or `apply` locally, without a remote execution by env zero - you can do it by enabling terraform's `TF_FORCE_LOCAL_BACKEND` environment variable.

```shell theme={null}
TF_FORCE_LOCAL_BACKEND=1 terraform apply
```

> [!WARNING]
>
> Local Execution
>
> When running `plan` or `apply` locally, those deployments are not audited in env zero and RBAC and policy control are not enforced. In addition since the code you are running is not commited, we can't attach that deployment to a certain commit or a branch.
>
> You should avoid using Local Execution as much as possible.

## Next steps

When the plan output looks right, [run a remote apply](https://docs.envzero.com/guides/admin-guide/remote-backend/remote-apply.md) to deploy the change from your terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.