opentf/website/docs/language/settings/backends/remote.mdx

---
sidebar_label: remote
description: >-
  OpenTofu can store the state and run operations remotely, making it easier to
  version and work with in a team.
---

# Backend Type: remote

Most of the available backends provide different ways of storing state snapshots remotely. Therefore, they are often called remote state backends.
This page describes a special `remote` backend, not to be confused with the simpler remote state backends.

:::note
**We recommend using the [`cloud` built-in integration](../../../cli/cloud/settings.mdx)** instead of the `remote` backend. The `cloud` option includes an improved user experience and more features.
:::

The remote backend is unique among all other OpenTofu backends because it can both store state snapshots and execute CLI-driven run workflow operations for TF Automation and Collaboration Software ([TACOS](../../../intro/tacos.mdx)) backends. It used to be called an "enhanced" backend.

If your [TACOS](../../../intro/tacos.mdx) provider enables full remote operations, you can execute commands such as `tofu plan` or `tofu apply` within the [TACOS](../../../intro/tacos.mdx) runtime environment, with log output streaming directly to your local terminal. Remote plans and applies use variable values from the associated remote workspace.

You can also use [TACOS](../../../intro/tacos.mdx) with local operations, where only state is stored in the [TACOS](../../../intro/tacos.mdx) remote backend.

## Command Support

:::note
Features implementation might vary between different [TACOS](../../../intro/tacos.mdx).
:::

The remote backend supports the following OpenTofu commands:

- `apply`
- `console`
- `destroy`
- `fmt`
- `get`
- `graph`
- `import`
- `init`
- `output`
- `plan`
- `providers`
- `show`
- `state` (supports all sub-commands: list, mv, pull, push, rm, show)
- `taint`
- `untaint`
- `validate`
- `version`
- `workspace`

## Workspaces

The remote backend can work with either a single remote workspace, or with multiple similarly-named remote workspaces (like `networking-dev` and `networking-prod`). The `workspaces` block of the backend configuration
determines which mode it uses:

- To use a single remote workspace, set `workspaces.name` to the
  remote workspace's full name (like `networking-prod`).

- To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in
  all of the desired remote workspace names. For example, set
  `prefix = "networking-"` to use remote workspaces with
  names like `networking-dev` and `networking-prod`. This is helpful when
  mapping multiple OpenTofu CLI [workspaces](../../../language/state/workspaces.mdx)
  used in a single OpenTofu configuration to multiple remote workspaces.


The backend configuration requires either `name` or `prefix`. Omitting both or
setting both results in a configuration error.

If previous state is present when you run `tofu init` and the corresponding
remote workspaces are empty or absent, OpenTofu will create workspaces and
update the remote state accordingly. However, if your workspace requires variables or a specific version of OpenTofu for remote operations, we
recommend that you create your remote workspaces on [TACOS](../../../intro/tacos.mdx) before
running any remote operations against them.

### Workspace Names

OpenTofu uses shortened names without the common prefix to interact with workspaces on the command line. For example, if `prefix = "networking-"`, use `tofu workspace select prod` to switch to the OpenTofu CLI workspace `prod` within the current configuration. However, remote OpenTofu operations such as `plan` and `apply` for that OpenTofu CLI workspace will take place in the remote workspace `networking-prod`.

Because of this, the [`terraform.workspace`](../../../language/state/workspaces.mdx#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following:

- For local operations, `terraform.workspace` = `prod`
- For remote operations, `terraform.workspace`=  `networking-prod`

## Example Configurations

:::note
We recommend omitting the token from the configuration, and instead using
[`tofu login`](../../../cli/commands/login.mdx) or manually configuring
`credentials` in the [CLI config file](../../../cli/config/config-file.mdx#credentials).
:::

### Basic Configuration

```hcl
# Using a single workspace:
terraform {
  backend "remote" {
    hostname = "app.example.io"
    organization = "company"

    workspaces {
      name = "my-app-prod"
    }
  }
}

# Using multiple workspaces:
terraform {
  backend "remote" {
    hostname = "app.example.io"
    organization = "company"

    workspaces {
      prefix = "my-app-"
    }
  }
}
```

### Using CLI Input

```hcl
# main.tf
terraform {
  required_version = "~> 0.12.0"

  backend "remote" {}
}
```

Backend configuration file:

```hcl
# config.remote.tfbackend
workspaces { name = "workspace" }
hostname     = "app.example.io"
organization = "company"
```

Running `tofu init` with the backend file:

```sh
tofu init -backend-config=config.remote.tfbackend
```

### Data Source Configuration

```hcl
data "terraform_remote_state" "foo" {
  backend = "remote"

  config = {
    organization = "company"

    workspaces = {
      name = "workspace"
    }
  }
}
```

## Configuration Variables

:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTofu will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](../../../language/settings/backends/configuration.mdx#credentials-and-sensitive-data) for details.
:::

The following configuration options are supported:

- `hostname` - (Required) The remote backend hostname to connect to.
- `organization` - (Required) The name of the organization containing the
  targeted workspace(s).
- `token` - (Optional) The token used to authenticate with the remote backend.
  We recommend omitting the token from the configuration, and instead using
  [`tofu login`](../../../cli/commands/login.mdx) or manually configuring
  `credentials` in the
  [CLI config file](../../../cli/config/config-file.mdx#credentials).
- `workspaces` - (Required) A block specifying which remote workspace(s) to use.
  The `workspaces` block supports the following keys:

  - `name` - (Optional) The full name of one remote workspace. When configured,
    only the default workspace can be used. This option conflicts with `prefix`.
  - `prefix` - (Optional) A prefix used in the names of one or more remote
    workspaces, all of which can be used with this configuration. The full
    workspace names are used in [TACOS](../../../intro/tacos.mdx), and the short names
    (minus the prefix) are used on the command line for OpenTofu CLI workspaces.
    If omitted, only the default workspace can be used. This option conflicts with `name`.

:::note
You must use the `name` key when configuring a `terraform_remote_state`
data source that retrieves state from another remote workspace. The `prefix` key is only
intended for use when configuring an instance of the remote backend.
:::

## Command Line Arguments

For configurations that include a `backend "remote"` block, commands that
make local modifications to OpenTofu state and then push them back up to
the remote workspace accept the following option to modify that behavior:

- `-ignore-remote-version` - Override checking that the local and remote
  OpenTofu versions agree, making an operation proceed even when there is
  a mismatch.

  Normally state-modification operations require using a local version of
  OpenTofu CLI which is compatible with the OpenTofu version selected
  for the remote workspace as part of its settings. This is to avoid the
  local operation creating a new state snapshot which the workspace's
  remote execution environment would then be unable to decode.

  Overriding this check can result in a remote workspace that is
  no longer able to complete remote operations, so we recommend against
  using this option.

## Excluding Files from Upload with .terraformignore

When executing a remote `plan` or `apply` in a CLI-driven run,
an archive of your configuration directory is uploaded to [TACOS](../../../intro/tacos.mdx). You can define
paths to ignore from upload via a `.terraformignore` file at the root of your configuration directory. If this file is not present, the archive will exclude the following by default:

- `.git/` directories
- `.terraform/` directories (exclusive of `.terraform/modules`)

The `.terraformignore` file can include rules as one would include in a
[`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)

- Comments (starting with `#`) or blank lines are ignored
- End a pattern with a forward slash `/` to specify a directory
- Negate a pattern by starting it with an exclamation point `!`

Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration
directory is considered.