Documentation · Infrastructure runs

Pointing a configuration at us

The cloud block, the hostname that serves discovery, and what a workspace holds — state versions, variables and their precedence.

Infrastructure runs speak the Terraform Enterprise API, so the client is the terraform or tofu CLI you already have. There is nothing to install.

terraform {
  cloud {
    hostname     = "tf.runners.io"
    organization = "your-organization"

    workspaces {
      name = "your-workspace"
    }
  }
}

tf.runners.io is the only host that serves Terraform's service discovery document. runners.io and www.runners.io are the website and answer a redirect, so a cloud block naming either of them will not initialise.

Your organisation name is on Settings, as the account on the Terraform card below the GitHub one, which is also where the first token comes from. See connect your account for that half.

export TF_TOKEN_tf_runners_io=<your token>
terraform init
terraform plan

The remote backend works too, and is what you need temporarily if you are migrating existing state.

A workspace named in a cloud block is created on first use. It holds the state, the variables, and the history of runs against it.

Opening one in the dashboard shows:

• Runs, newest first, each with its plan and apply output.

• State versions, each immutable, with a diff against the one before it and a download. Rollback creates a new version whose contents are an older one — it never edits history, and it does not by itself change infrastructure. A deleted version can be restored within its recovery window.

• Variables, both the workspace's own and every variable set applied to it.

• Settings, including whether destroy plans are allowed.

The same name can appear on a workspace and on one or more variable sets. The rules are Terraform's rather than ours:

1. A workspace variable always beats a variable set's.

2. Between two sets, a workspace-scoped set beats a global one.

3. Between two sets of equal scope, the lexically earlier name wins.

Category is part of a variable's identity. A Terraform variable region and an environment variable region are different variables and never conflict — the dashboard treats them as distinct, and so does a run.

Where a name is genuinely shadowed the workspace page says which value wins, rather than showing you two rows and leaving you to guess.

There are no projects. Workspaces belong to an organisation directly. If you are coming from HCP Terraform this changes the subject of a dynamic-credentials token — see dynamic credentials.