Terrapod

Open-source platform replacement for Terraform Enterprise.

Terrapod provides the collaboration, governance, state management, and UI layer that wraps around terraform or tofu as pluggable execution backends. It targets API compatibility with the HCP Terraform / TFE V2 API so that existing tooling -- the terraform CLI with cloud block, the go-tfe client, CI/CD integrations -- can point at a Terrapod instance with minimal reconfiguration.

Terrapod is not a fork of Terraform or OpenTofu. It orchestrates them.

Drop-in replacement for HCP Terraform. Point your existing cloud blocks, go-tfe clients, and CI/CD pipelines at Terrapod — zero code changes required.

AI-augmented plans. Every plan can carry an LLM-generated change description, risk assessment, and (on failure) suggested fixes — provider-agnostic via LiteLLM. Wire AWS Bedrock (Claude, Nova, gpt-oss) with native IAM auth, or point at OpenAI, Anthropic, Gemini, Azure OpenAI, or any OpenAI-compatible endpoint. See docs/ai-plan-summary.md.

Policy-as-code with OPA. Block applies on policy violations using Open Policy Agent and the Rego language — the open-source equivalent of TFE's proprietary Sentinel. Policy sets are scoped to workspaces with the same label-based model as roles, evaluated on the runner against the plan JSON, and gated as advisory (warn) or mandatory (block). See docs/policies.md.

Key Features

Screenshots

Architecture

                              +---------------------+
                              |     Browser / CLI    |
                              +----------+----------+
                                         |
                                     HTTPS (TLS)
                                         |
                              +----------v----------+
                              |      Ingress         |
                              +----------+----------+
                                         |
                              +----------v----------+
                              |   Next.js Frontend   |  (BFF pattern)
                              |   (Web UI + Proxy)   |
                              +----+------------+---+
                                   |            |
                        /app/*     |            |  /api/*  /.well-known/*
                        (pages)    |            |  (rewrite to API)
                                   |            |
                              +----v------------v---+
                              |   FastAPI API Server |
                              +--+------+------+----+
                                 |      |      |
                    +------------+   +--+--+   +------------+
                    |                |     |                 |
              +-----v-----+  +-----v-+ +-v----------+ +----v-------+
              | PostgreSQL |  | Redis | | Object     | | VCS Polls  |
              | (data,     |  | (sess | | Storage    | | (GitHub,   |
              |  state     |  |  ions,| | (S3/Azure/ | |  GitLab)   |
              |  metadata) |  |  locks| |  GCS/FS)   | +------------+
              +-----------+   +------+  +-----------+
                                              ^
                              +---------------+
                              |               |
                    +---------v----------+    |
                    |  Runner Listener   |    |  (one or more, each
                    |  (K8s Deployment,  |    |   joins a pool via
                    |   joins pool via   |    |   join token)
                    |   join token)      |    |
                    +---------+----------+    |
                              |               |
                    +---------v----------+    |
                    |  K8s Jobs          |    |
                    |  (ephemeral        |    |
                    |   terraform/tofu)  |    |
                    +--------------------+    +

Design Principles

• API-first -- every UI action is backed by a public API endpoint
• BFF pattern -- Next.js frontend is the single ingress entry point; browser never talks to the API directly
• Kubernetes-native -- deployed exclusively via Helm chart; runner Jobs are ephemeral K8s Jobs
• ARC-pattern execution -- listener creates Jobs on demand (like GitHub Actions Runner Controller)
• OpenTofu-first -- OpenTofu is the recommended execution backend; terraform is also supported
• Single organization -- one org per instance; every Terrapod API path that contains an organization segment uses the literal name default
• Native object storage -- speaks each cloud provider's native SDK (S3, Azure Blob, GCS) with filesystem fallback for dev

Quick Start

Prerequisites

• A local Kubernetes cluster (Rancher Desktop, Docker Desktop, minikube, kind, or OrbStack)
• Tilt installed
• mkcert for local TLS

Setup

# Install mkcert and create local CA
brew install mkcert && mkcert -install

# Add hosts entry
sudo sh -c 'echo "127.0.0.1 terrapod.local" >> /etc/hosts'

# Start Terrapod
make dev

Tilt starts on port 10352. Open https://terrapod.local in your browser.

Create Your First Workspace

# Login (default admin credentials from bootstrap)
export TERRAPOD_TOKEN="<your-api-token>"

# Create a workspace
curl -X POST https://terrapod.local/api/v2/organizations/default/workspaces \
  -H "Authorization: Bearer $TERRAPOD_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "workspaces",
      "attributes": {
        "name": "my-first-workspace"
      }
    }
  }'

Configure OpenTofu (or Terraform)

# main.tf
terraform {
  cloud {
    hostname     = "terrapod.local"
    organization = "default"

    workspaces {
      name = "my-first-workspace"
    }
  }
}

tofu login terrapod.local
tofu init
tofu plan
tofu apply

For detailed instructions, see docs/getting-started.md.

Production Deployment

Terrapod is deployed via Helm chart on Kubernetes. Images and chart are published to GHCR.

helm install terrapod oci://ghcr.io/mattrobinsonsre/terrapod \
  --namespace terrapod \
  --create-namespace \
  --set ingress.enabled=true \
  --set ingress.hostname=terrapod.example.com \
  --set postgresql.url="postgresql+asyncpg://user:pass@db:5432/terrapod" \
  --set redis.url="redis://redis:6379"

Required infrastructure:

• PostgreSQL (v14+) for relational data
• Redis (v7+) for sessions, locks, and listener heartbeats
• Object storage (S3, Azure Blob, GCS, or PVC-backed filesystem)

See docs/deployment.md for the full production deployment guide.

Authentication

Terrapod supports multiple authentication methods:

• Local passwords -- PBKDF2-SHA256 hashed, with zxcvbn strength validation
• OIDC -- Auth0, Okta, Azure AD, and any standards-compliant provider via authlib
• SAML -- Azure AD SAML and other SAML 2.0 providers via python3-saml
• terraform login -- OAuth2 Authorization Code with PKCE for CLI authentication
• API tokens -- long-lived tokens for automation, SHA-256 hashed at rest

See docs/authentication.md for setup guides.

Documentation

Tech Stack

Development

All builds, tests, and linting run in Docker -- no local Python or Node.js install needed.

make dev          # Start local dev environment (Tilt)
make dev-down     # Stop local dev environment
make test         # Run pytest in Docker (with LocalStack for S3)
make lint         # Run ruff + mypy in Docker
make images       # Build production Docker images

Conventions

• Commits: conventional commits (feat:, fix:, docs:, chore:)
• Branches: feature branches off main; never push directly to main
• API contract: JSON:API spec; compatibility tested against go-tfe client
• Migrations: Alembic with async SQLAlchemy
• Local dev: Tilt with live_update for Python and Node.js hot reload

Security Testing

Terrapod includes a three-layer pen testing framework. All tools run in Docker.

make pentest-sast     # Static analysis (Semgrep)
make pentest-images   # Container image CVE scan (Trivy)
make pentest-dast     # Dynamic testing against live stack (Nuclei)
make pentest          # All three layers

Reports are written to reports/pentest/. See SECURITY.md for the full security policy.

Comparison with Alternatives

Terrapod is the only open-source project that covers the full TFE surface: state management, agent execution, private registry, RBAC, VCS integration, drift detection, OPA policy enforcement, and a production-grade UI -- all in a single self-hosted Kubernetes deployment.

Terrapod is a single, self-hosted platform covering the full TFE surface (state + runs + registry + governance + UI + API) under a copyleft (GPLv3) license.

License

GPLv3 -- strong copyleft ensures Terrapod and all derivative works remain open source.

Trademarks

Terrapod is not affiliated with, endorsed by, or a product of HashiCorp, Inc. or IBM. Terraform is a trademark of HashiCorp, Inc. OpenTofu is a project of the Linux Foundation.

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository and create a feature branch from main
2. Follow conventional commit format (feat:, fix:, docs:, chore:)
3. Run tests (make test) and linting (make lint) before submitting
4. Ensure all CI checks pass
5. Open a pull request with a clear description of the change

For architecture questions or major changes, open an issue first to discuss the approach.