# Remote State Management

> **Related Guides and Examples:**
>
> * [Overview: Firefly Workflows and Guardrails](https://docs.firefly.ai/detailed-guides/workflows): High-level concepts and options.
> * [Creating New Firefly Workflows](https://docs.firefly.ai/detailed-guides/workflows/creating-workflows): How to set up managed workflows.
> * [Creating Guardrail Rules in Firefly](https://docs.firefly.ai/detailed-guides/workflows/creating-guardrail-rules): How to define and enforce policies and best practices.
> * [Creating Projects](https://docs.firefly.ai/detailed-guides/workflows/creating-projects): How to create projects to group IaC orchestration resources and control access.
> * [Triggering Workspace Deployment](https://docs.firefly.ai/detailed-guides/workflows/trigger-deploy): How to trigger a workspace deployment from the Firefly UI.

Firefly offers a sophisticated state backend synchronized with the rest of the application to manage your Terraform state and maximize security and convenience—available for workspaces configured with Firefly runner or Self-hosted runner pool.

## State History

You can view your stack's state history in Firefly. Navigate to the workspace, hover over the actions and select **View Assets**. In the modal that opens you can see all the assets created by this workspace, when each was created, and the ability to download the state file.

> **Note:** Not all runs or tasks will trigger a new state version, so you should not expect to see an exhaustive list of your runs and tasks in this list. For example, runs that produce no Terraform changes do not result in a new state version being created.

## Limitations

* **OpenTofu versions:** All versions are supported.
* **Workspace name format:** Workspace names cannot contain spaces in the HCL backend block. Note that while Firefly allows spaces in workspace names within the UI, the name used in your backend configuration must not contain spaces.

## Remote Management Workspace Set-up

### Workspace Configuration

To enable state management for a workspace:

**New Workspace**

In the Execution Configuration step, enable the **Firefly Remote Backend Configuration** option.

### Migration

#### Firefly Backend Configuration

To use the Firefly remote backend, configure your Terraform backend block as follows:

```hcl
terraform {
  backend "remote" {
    hostname     = "api.gofirefly.io"
    organization = "<your-organization-id>"
    workspaces {
      name = "<your-workspace-name>"
    }
  }
}
```

#### Migrating from Terraform remote backend to OpenTofu

If you are switching from Terraform to OpenTofu and currently use a remote backend, add `hostname = "app.terraform.io"` to your existing backend block, then run the migration command.

Existing backend block:

```hcl
terraform {
  backend "remote" {
    hostname     = "app.terraform.io"
    organization = "your-organization"
    workspaces {
      name = "your-workspace"
    }
  }
}
```

Then run:

```bash
tofu init -migrate-state
```

#### Migrating from Terraform cloud backend to OpenTofu + Firefly

If you are switching from Terraform to OpenTofu and currently use a cloud backend, follow these steps:

1. **Add hostname to your existing cloud block:**

```hcl
terraform {
  cloud {
    hostname     = "app.terraform.io"
    organization = "your-organization"
    workspaces {
      name = "your-workspace"
    }
  }
}
```

2. **Pull and validate the current state:**

```bash
tofu state pull > terraform.tfstate.backup
tofu show terraform.tfstate.backup   # If this succeeds, the state is valid
```

3. **Update your backend block** — replace the cloud block with the Firefly remote backend:

```hcl
terraform {
  backend "remote" {
    hostname     = "api.gofirefly.io"
    organization = "<your-organization-id>"
    workspaces {
      name = "<your-workspace-name>"
    }
  }
}
```

4. **Reinitialize and push state:**

```bash
rm -rf .terraform
tofu init -reconfigure
tofu state push terraform.tfstate.backup
```

> **Note:** If a state already exists on the workspace and you need to override it, append the `-force` flag:

```bash
tofu state push -force terraform.tfstate.backup
```