What the agent does
The agent clones the configuration into its own cloud sandbox and reads every .tf file before it touches the backend. In a root module like hashicorp-education/learn-terraform-provision-eks-cluster, terraform.tf pins required_version = "~> 1.3", requires the aws provider at ~> 5.47.0 together with random, tls and cloudinit, and carries a commented-out cloud {} block that was never finished. main.tf builds a VPC from terraform-aws-modules/vpc/aws 5.8.1 and an EKS cluster from terraform-aws-modules/eks/aws 20.8.5 with two managed node groups, variables.tf declares only region with a default of us-east-2, and .gitignore already excludes *.tfstate, *.tfstate.* and *.tfvars. There is no backend block anywhere, so state lives in a local terraform.tfstate on whoever ran apply last. The .terraform.lock.hcl is committed and pins aws to 5.47.0, so the agent leaves provider versions alone.
Remote state has a chicken-and-egg problem: the bucket must exist before terraform init can write to it. The agent adds a small bootstrap/ root module beside the main one with its own provider block and a single aws_s3_bucket plus aws_s3_bucket_versioning set to Enabled, aws_s3_bucket_server_side_encryption_configuration with SSE-S3 or a KMS key when the prompt asks for one, aws_s3_bucket_public_access_block with all four flags true, and prevent_destroy = true in its lifecycle so a stray destroy cannot take the state with it. The bucket name comes from a variable so the same bootstrap serves several accounts. Locking is the second decision: S3's own lockfile needs a Terraform release newer than the ~> 1.3 floor in terraform.tf, so the agent either raises required_version and sets use_lockfile = true, or keeps the floor and adds an aws_dynamodb_table with a LockID hash key for the classic lock. It picks whichever the prompt names and says why in the pull request.
The main module then gets a backend "s3" block inside the existing terraform {} block in terraform.tf, next to required_providers, with bucket, key, region and encrypt = true. Because a backend block cannot read variables, the agent writes a backend.hcl example with the bucket and table names and documents terraform init -backend-config=backend.hcl in the README, so a fork of the repository does not inherit someone else's bucket. The dead cloud {} comment goes, since two backends cannot coexist and leaving it invites a future conflict. outputs.tf in the bootstrap module exports the bucket and table names so the values in backend.hcl can be copied rather than retyped.
Proof comes from Terraform itself. The agent runs terraform fmt -check -recursive and terraform init -backend=false followed by terraform validate in both the main and the bootstrap modules, so the new blocks are parsed and type-checked without any AWS credentials. It writes the migration sequence into the README as commands to run once: terraform init and apply in bootstrap/, then terraform init -migrate-state -backend-config=backend.hcl in the root, which copies the local state file into the bucket and asks for confirmation. If the Project holds AWS credentials as secrets, the prompt can ask the agent to run that sequence too; otherwise it stops at validation and says so.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Move this Terraform root module's state to a remote S3 backend. Read every .tf file, .terraform.lock.hcl, .gitignore and the README first, and keep provider versions as they are. Add a bootstrap/ root module that creates the state bucket (versioning enabled, server-side encryption, public access blocked, prevent_destroy) and a DynamoDB lock table with a LockID hash key, with the bucket name as a variable and both names as outputs. Add a backend \"s3\" block to the terraform {} block in terraform.tf with encrypt = true, remove the commented-out cloud block, and add a backend.hcl example plus README steps for terraform init -backend-config=backend.hcl and terraform init -migrate-state. Run terraform fmt -check -recursive, terraform init -backend=false and terraform validate in both modules. Do not run apply. Open a pull request that lists the files, the migration commands in order, and the validate output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that adds bootstrap/main.tf, bootstrap/variables.tf and bootstrap/outputs.tf, edits terraform.tf to add the backend "s3" block and drop the commented cloud {} block, adds backend.hcl with placeholder bucket and table names, and extends the README with the one-time bootstrap and migration steps. main.tf, variables.tf, outputs.tf and .terraform.lock.hcl are untouched, because a backend change moves where state is stored and changes no resource.
The description quotes the terraform validate result for both modules, names the locking method and why it was chosen against the required_version floor, and lists the commands a maintainer runs in order. The transcript at GET /o/{org}/sessions/{id}/messages keeps every terraform command and its output, so a reviewer can see that fmt found nothing to change and that init -backend=false succeeded rather than take the pull request's word for it.
Before merging, a reviewer checks that the bucket's public access block is complete, that encrypt = true is set on the backend, that the key is unique to this root module so a second module in the same bucket cannot overwrite it, and that the README tells people to keep terraform.tfstate.backup until the first remote plan shows no changes. A follow-up on the same session can add workspace_key_prefix for per-environment workspaces or switch the lock from DynamoDB to the S3 lockfile once the team's Terraform is new enough.
Run it on every new Terraform root module
A platform team that owns several root modules with local state runs this once per repository. From a script, send the body above to POST /o/{org}/sessions with each repository in resources, one run per repository, and a request_id that is a UUID v5 of the repository name so a retry is safe. Give the key a webhook_url, and every run the key starts posts run.completed with data.session_url when its turn ends; a handler reads the pull request link from the session and posts it where the team triages.
To stop local state from creeping back, add an automation to the Project with a github trigger on pull_request.opened and pull_request.synchronize and a prompt that fails the review when a new root module appears without a backend block. The trigger clones the pull request's branch and places the event after the prompt, and the automation starts at most max_runs_per_hour runs in an hour.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Moving state is a small diff with a large blast radius: a wrong key or a missing public access block is a problem that shows up months later. The agent reads the actual required_version, the provider pins and the .gitignore before it decides between a lockfile and a lock table, and it validates both modules in its own sandbox with a Terraform binary already installed, so the pull request arrives checked rather than typed.
Each terraform fmt, init and validate and its output stay in the run's transcript, so the review is of a log rather than a promise, and the laptop that handed off the task is free while it happens. Several root modules can get the same backend at once, each in its own sandbox and its own pull request, with the same bucket layout in every one.
Frequently asked questions
Will the agent migrate my existing state file?
Only if the Project gives it AWS credentials as secrets and the prompt asks for it. By default it adds the backend, validates both modules without credentials and writes the terraform init -migrate-state steps into the README for a maintainer to run once. Migration copies the local state into the bucket and asks for confirmation before it does.
DynamoDB lock table or S3 lockfile?
Both prevent two people from applying at once. The S3 lockfile needs a Terraform release newer than the ~> 1.3 floor in this module's terraform.tf, so the agent uses it only when the prompt allows raising required_version; otherwise it adds a DynamoDB table with a LockID hash key, which works on every version the module already accepts.
Will this change any of my AWS resources?
No. A backend block changes where Terraform stores state, not what it manages, so the first terraform plan after migration should show no changes. The bootstrap module creates only the bucket and the lock table, in its own state, and marks the bucket prevent_destroy so it cannot be removed by accident.
Can several environments share one bucket?
Yes. Each root module gets its own key, and workspaces are separated by workspace_key_prefix. The agent sets a key specific to this module and leaves a note in the README on how a second module or a staging workspace picks a different one, so two configurations never write to the same object.
Why not finish the commented-out Terraform Cloud block instead?
Because the prompt asks for S3 and a configuration can declare only one backend. The agent removes the dead comment so nobody later uncomments it next to the S3 block. If you would rather use HCP Terraform, a follow-up message on the same session can swap the backend for the cloud block and drop the bootstrap module.
More Terraform jobs
More jobs like this: Hand off a long task
- Make a Maven Build Reproducible (Maven)
- Add Request ID Logging to an Actix Web App (Actix Web)
- Add Request ID Logging to an AdonisJS App (AdonisJS)