# Remote State Management > **Related Guides and Examples:** > > * [Overview: Firefly Workflows and Guardrails](/detailed-guides/workflows.md): High-level concepts and options. > * [Creating New Firefly Workflows](/detailed-guides/workflows/creating-workflows.md): How to set up managed workflows. > * [Creating Guardrail Rules in Firefly](/detailed-guides/workflows/creating-guardrail-rules.md): How to define and enforce policies and best practices. > * [Creating Projects](/detailed-guides/workflows/creating-projects.md): How to create projects to group IaC orchestration resources and control access. > * [Triggering Workspace Deployment](/detailed-guides/workflows/trigger-deploy.md): 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. * **Workspace creation only:** An existing workspace cannot be edited to use Firefly state management. To use this feature, create a new workspace and enable Firefly state management during the creation process. ## 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 #### Prerequisites, account ID, Workspace and authentication Before migrating state into Firefly: * **Workspace:** Create the Firefly workspace first and enable **Firefly Remote Backend Configuration** (see [Workspace configuration](#workspace-configuration) above). The workspace name you use in HCL must match an existing workspace; migration targets that workspace’s remote state. * **`organization` in the backend block:** This value is your **Firefly account ID** (it is not an arbitrary label). In the Firefly console, open [**Integrations**](https://app.firefly.ai/integrations); the account ID appears in the **top left corner**, under **Connected integrations**. * **API token:** Commands that talk to `api.gofirefly.io` must authenticate. Set a Firefly JWT (from an API key pair) in the environment variable Terraform/OpenTofu expects for this hostname: ```bash export TF_TOKEN_api_gofirefly_io="" ``` For how to obtain the JWT from your access and secret keys, see [Authentication](/general-information/api/auth.md#authentication). #### Firefly backend configuration To use the Firefly remote backend, configure your backend block as follows. Replace `` with your account ID from **Integrations** (top left corner, under **Connected integrations**), and `` with the workspace name (no spaces in this field; see [Limitations](#limitations)). ```hcl terraform { backend "remote" { hostname = "api.gofirefly.io" organization = "" workspaces { name = "" } } } ``` #### Migrating from Terraform remote backend to OpenTofu If you are switching from Terraform to OpenTofu and currently use Terraform Cloud’s `remote` backend, add `hostname = "app.terraform.io"` to your existing backend block, then run the migration command. This step moves your working copy to OpenTofu while state remains on Terraform Cloud. 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` block, use the manual pull/push flow (not `-migrate-state` across `cloud` → `remote` to Firefly). 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 init tofu state pull > terraform.tfstate.backup tofu show terraform.tfstate.backup # If this succeeds, the state is valid ``` 3. **Replace the `cloud` block** with the Firefly `remote` backend: ```hcl terraform { backend "remote" { hostname = "api.gofirefly.io" organization = "" workspaces { 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 ``` > **Note:** A Firefly workspace’s remote state is **unique** to that workspace. You cannot point several different backends or stacks at the **same** workspace name and treat them as separate state buckets—each upload targets that single workspace, and the **latest** push or successful apply **replaces** the stored state for it. Use **one workspace per distinct state** (or split stacks at the Terraform/OpenTofu level) so you do not overwrite another environment’s state by mistake. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.firefly.ai/detailed-guides/workflows/remote-state-management.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.