Remote State Management

Related Guides and Examples:

• Overview: Firefly Workflows and Guardrails: High-level concepts and options.

• Creating New Firefly Workflows: How to set up managed workflows.

• Creating Guardrail Rules in Firefly: How to define and enforce policies and best practices.

• Creating Projects: How to create projects to group IaC orchestration resources and control access.

• Triggering Workspace Deployment: How to trigger a workspace deployment from the Firefly UI.

• Local Execution (State-Only Workspaces): Use Firefly as your backend while running plan/apply yourself, with the workspace created on demand.

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.

Choosing a mode: This page covers using Firefly as your backend for workspaces whose execution is handled by a Firefly or self-hosted runner, with the workspace pre-created in the UI (using a backend "remote" block). If you would rather run plan/apply locally yourself and have Firefly auto-create a state-only, VCS-less workspace (using a cloud {} block), see Local Execution (State-Only Workspaces) instead.

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 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; 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:

export TF_TOKEN_api_gofirefly_io="<your-firefly-jwt>"

For how to obtain the JWT from your access and secret keys, see Authentication.

Firefly backend configuration

To use the Firefly remote backend, configure your backend block as follows. Replace <your-firefly-account-id> with your account ID from Integrations (top left corner, under Connected integrations), and <your-firefly-workspace-name> with the workspace name (no spaces in this field; see Limitations).

terraform {
  backend "remote" {
    hostname     = "api.gofirefly.io"
    organization = "<your-firefly-account-id>"
    workspaces {
      name = "<your-firefly-workspace-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:

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

Then run:

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:

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

1. Pull and validate the current state:

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

1. Replace the cloud block with the Firefly remote backend:

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

1. Reinitialize and push state:

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:

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.