Review & implement locally
Run the InfraDots review and implement agents on your own machine. It is free, needs no InfraDots account, and nothing is sent to InfraDots. Only the model calls leave your machine.
Prerequisites
- The
idpCLI. Download the archive for your platform from the releases page and putidpon yourPATH. - Docker. The CLI runs the public image
public.ecr.aws/e5i7i1j1/idp-agent. Without Docker, use--nativewith an installedidp-agent. - A model. Set
ANTHROPIC_API_KEY, or setMODEL_PROVIDER=bedrock|vertex|foundrywithMODEL_MAPand that provider's credentials.
Review
idp agent review --offline # current directory
idp agent review --offline ./infra # a path
The review covers everything since the branch left the base branch, committed or not, including new files. The repository is mounted read-only.
| Option | Meaning |
|---|---|
--base BRANCH | Branch to compare against. Default: the remote's default branch |
--plan FILE | A plan to review alongside the code |
--guidance FILE | Team guidance file. Default: .infradots/guidance.md if present |
--instructions "focus on IAM" | Extra focus for this review |
--model | Model to use |
--iac terraform|tofu | Which tool runs the fmt check. It uses terraform/tofu from your PATH and is skipped if missing |
-f json | JSON output |
--native | Run idp-agent directly instead of Docker |
--image | Use a different agent image |
--dry-run | Show what would run without running it |
Exit codes: 0 approved, 1 changes requested, 2 error.
Reviewing a plan
terraform plan -out tfplan
terraform show -json tfplan > plan.json
idp agent review --offline --plan plan.json
--plan accepts the JSON from terraform show -json, or the text output of terraform plan. The streaming terraform plan -json log is refused.
In CI
idp agent review --offline --base origin/main -f json > review.json
The exit code fails the job when the agent requests changes (1) or errors (2). The review needs the base branch's history to find where your branch left it, so check out the full history (for example fetch-depth: 0 with actions/checkout).
As a pre-push hook
Each review calls the model, so run it before you push rather than on every commit. Save this as .git/hooks/pre-push and make it executable:
#!/bin/sh
idp agent review --offline || exit 1
Team guidance
Put your team's standards in .infradots/guidance.md in the repository, or pass another file with --guidance. This file is used by offline reviews only. Reviews on the platform use your organization's reviewer guidance.
Implement
idp agent implement --offline "add a lifecycle rule that expires logs after 90 days" ./infra
The request must be an infrastructure-code request. It first passes an input gate, and anything else is declined. The agent works in a git worktree on a new branch idp-agent/<timestamp>-<random>, cut from your last commit. Your checkout and uncommitted work are untouched, and uncommitted changes are not on the branch. It commits as you (your git user.name and user.email, without running hooks or signing) and never pushes.
| Option | Meaning |
|---|---|
--patch | Include the full diff in the report |
-f json | JSON output |
--model, --iac, --native, --image, --dry-run | Same as for review |
The report lists the commits, a diffstat and the commands to:
- review:
git diff BASE...BRANCH - try:
git switch BRANCH - discard:
git branch -D BRANCH
If nothing changed, no branch is left. Exit codes: 0 a branch was made, 1 nothing changed (or not an infrastructure request), 2 error.
What the agents look up
Agents check the public Terraform and OpenTofu registries for the newest provider and module versions and for a resource's reference (arguments, attributes, examples). With --iac tofu, the OpenTofu registry is asked first. This needs outbound HTTPS to registry.terraform.io and api.opentofu.org.
Docker or --native
By default the CLI runs the agent in the idp-agent Docker image (Docker Desktop, Colima and OrbStack all work), with the repository mounted read-only for a review and read-write for an implementation, which commits its branch to it. Use --native to run an idp-agent installed on your machine instead, or --image to pick a specific image.
Troubleshooting
| Symptom | Fix |
|---|---|
Exit code 2 with a message about a missing key | Set ANTHROPIC_API_KEY, or MODEL_PROVIDER with MODEL_MAP and credentials |
| Docker not found | Install and start Docker, or use --native |
| Plan file refused | Use terraform show -json tfplan, not the streaming terraform plan -json log |
| Registry access blocked | The agent says the lookup failed and carries on without it |
Next steps
- Agents - what the agents do on the platform
- Self-hosted Runners - run agents in your own cluster
- Reviewer Guidance - org-wide guidance for platform reviews