Skip to content

Documentation · Infrastructure runs

Terraform quickstart

From no account to a finished terraform plan: sign up, add a card, connect Terraform, and paste one cloud block. Nothing to install.

From no account to a finished terraform plan: sign up, add a card, connect Terraform, and put one block in your configuration. The terraform or tofu CLI you already have is the client; there is nothing to install. Any release of OpenTofu works, and Terraform 1.6 or later. Terraform 1.5 and earlier are refused when the workspace is created.

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

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

  1. Create an account. Go to runners.io/login?mode=signup and sign up with a work email and a password, or with Continue with GitHub. An organisation is created for you, and you are its owner. An email sign-up is confirmed by a link we email you: open it in the same browser and it signs you in.

  2. Add a card. On Settings → Billing, press Add a payment method. Stripe's checkout page asks for the card and a billing address, and places a temporary authorisation to check the card is real, which is released, never charged. Until a card is on file every run is refused. What a run costs is on the pricing page.

  3. Connect Terraform. On Settings → Integrations, press Connect on the Terraform card. Only an owner or an admin can. A panel opens with two things to copy: an export line holding your API token, and the cloud block above with your organisation's name already filled in. Copy the token now. It is not stored anywhere we can read it, so this is the only time it is shown.

  4. Give the CLI the token. Paste the export line into your shell:

    bash
    export TF_TOKEN_tf_runners_io=<your token>

    The variable name is Terraform's own convention: the hostname with its dots replaced by underscores. OpenTofu reads the same variable.

  5. Point a configuration at us. In a directory of its own, save the block from the panel as main.tf. To have something to plan before you bring a real configuration, add a resource that needs no provider and no cloud credentials:

    hcl
    resource "terraform_data" "hello" {
  input = "hello from runners.io"
}

    The workspace named in the block does not need to exist. It is created the first time you initialise.

  6. Plan.

    bash
    terraform init
terraform plan

    tofu init and tofu plan work the same way. The plan runs on our side and its output streams back to your terminal, ending:

    Plan: 1 to add, 0 to change, 0 to destroy.

    The link the CLI prints under To view this run in a browser takes you to the run's page in the dashboard, by way of the sign-in page if you are not signed in. tf.runners.io itself has no pages.

The time OpenTofu itself spends running, in run-minutes: a plan and an apply are each measured separately and each rounded up to a whole minute, so a plan that takes a few seconds is one minute. Waiting in the queue and the sandbox starting up are not counted. API calls, state reads and writes, the module registry and the provider mirror have no charge of their own. The state we keep for you is billed by what it stores over time, whether your runs execute here or on your own machines; how you are billed has the rest, and the pricing page the rates.

  • Required token could not be found. The CLI did not see the token in this shell. Check the variable is exported and spelled TF_TOKEN_tf_runners_io, with underscores where the hostname has dots.

  • Failed to read organization … unauthorized. The token is not one we issued, or it has been revoked. Issue a new one: an owner or an admin presses Connect on the Terraform card again. Your own tokens are listed, and can be revoked, under Settings → Integrations → Your Terraform API tokens.

  • The plan is refused because the organisation has no payment method. Add a card (step 2) and plan again; runs are accepted within a minute of the card being on file, and nothing needs to be re-initialised.

  • The plan is refused because the organisation has not yet been approved to run Terraform applies. It is waiting for us to review it. Write to us from how we support you and name the organisation.

  • The plan stops at downloading engine with a 404. See the warning after step 6: the workspace asks for an OpenTofu version that does not exist.

  • terraform init fails with unsupported terraform version. Your terraform is older than 1.6, the first version OpenTofu released, and the workspace is refused when the CLI creates it. Upgrade Terraform, or use tofu; nothing was created, so run init again afterwards.