Quickstart

Goal: orchestrator + agent up locally, a repo with terraplane.yaml, and a PR comment that plans.

1. Prerequisites

Docker
A GitHub personal access token (orchestrator API access)
A webhook secret you’ll configure on the GitHub app/webhook
An SSH deploy key the agent can use to clone the Terraform repo

2. Run Terraplane

git clone https://github.com/terraplane-org/terraplane.git
cd terraplane
cp .env-example .env

Edit .env and set at least:

ORCHESTRATOR_GITHUB_ACCESS_TOKEN=...
ORCHESTRATOR_GITHUB_WEBHOOK_SECRET=...
AGENT_SCM_SSH_KEY_PATH=/absolute/path/to/deploy_key
SHARED_AUTH_TOKEN=some-shared-secret

Then:

docker compose up --build

Compose starts Postgres, migrates, brings the orchestrator up on :8080, and connects agents (including agent-dev) over WebSocket.

Confirm the orchestrator is healthy:

curl -f http://localhost:8080/health

3. Point GitHub at you

Expose :8080 somehow (ngrok, Cloudflare Tunnel, Tailscale Funnel — your call) and add a repository webhook:

Payload URL: https://<your-tunnel>/scm/webhook
Content type: application/json
Secret: same as ORCHESTRATOR_GITHUB_WEBHOOK_SECRET
Events: Issue comments (PR review comments travel as issue comments)

4. Configure a Terraform repo

In the repo you want Terraplane to manage, add terraplane.yaml:

stacks:
  - name: stg-apse2-foundation
    agent: agent-dev
    dir: terraform/environments/staging/ap-southeast-2/foundation

agent must match an agent id that’s connected (agent-dev in the default Compose file).

5. Plan from a pull request

Open a PR, then comment:

terraplane plan -s stg-apse2-foundation

Or plan everything in the file:

terraplane plan

You should get plan output back on the PR. When you’re ready:

terraplane apply -s stg-apse2-foundation

Stuck? Unlock and try again:

terraplane unlock -s stg-apse2-foundation

Get started — local Make targets and a bit more context
How it works — orchestrator ↔ agent path
Configuration — env vars
Deployment — Helm when you’re past Compose