Metadata-Version: 2.4
Name: maf-sandbox-terraform
Version: 0.1.1
Summary: Offline Terraform and OpenTofu validation in disposable sandboxes for Agent Framework.
Keywords: terraform,opentofu,sandbox,agent-framework
Author: SOKOLAI BV
Author-email: SOKOLAI BV <info@sokolai.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Dist: maf-sandbox>=0.40.0,<0.41
Requires-Dist: agent-framework-core>=1.18.0,<2
Requires-Python: >=3.12, <3.15
Project-URL: Homepage, https://www.sokol.ai
Project-URL: Source, https://github.com/sokolaidev/maf-extensions
Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
Description-Content-Type: text/markdown

# maf-sandbox-terraform

[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-terraform)](https://pypi.org/project/maf-sandbox-terraform/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-terraform)](https://pypi.org/project/maf-sandbox-terraform/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-terraform/LICENSE)

> **Experimental.** This package warns on import with `MafSandboxTerraformExperimentalWarning`. Releases before 1.0 may change or remove APIs without notice.

Offline configuration validation for Terraform and OpenTofu, as a sibling of `maf-sandbox-bicep`. Not yet released; run from this workspace until the first package release.

The host calls `make_terraform_tools(router, file_store, agent_id, context, engine="terraform", image=...)`. The accepted engine options are exactly `terraform` (default) and `opentofu`. They attach `terraform_validate` and `opentofu_validate`, respectively, with separate sandbox kinds. Each tool accepts `files: list[str]` and `root_module: str = "."`. No engine fallback or model-selected CLI flags are supported.

The tool stages the explicit manifest, runs `init -backend=false -input=false -no-color`, `validate -json`, and `fmt -check -recursive -no-color`, and returns separate validation and formatting verdicts. Initialization failure means validation is incomplete. Malformed or inconsistent reports never produce a pass. A supplied root `.terraform.lock.hcl` adds `-lockfile=readonly`; otherwise initialization may create a lock only inside that call's disposable guest. No files are written back to the store, and no formatted text is returned. The tool description and the fixed guidance say so, so a model fixes formatting by editing the files.

Include every configuration sibling in each selected directory, every local module, and referenced text assets. Select a root module containing at least one recognized configuration file. Relative paths preserve local references such as `../modules/child`; uploads cannot contain `..` segments. Terraform accepts `.tf` and `.tf.json`; OpenTofu also accepts `.tofu` and `.tofu.json`, with its native precedence. Terraform mode refuses `.tofu` files rather than silently validating an empty directory. The listing completeness check covers only files the host shares with this tool.

State, plans, variable files, CLI credential/configuration paths, plugin binaries, and reserved directories are refused. Files must be text and fit the core transfer limits (64 files, 8 MiB per file, 32 MiB total). Reads retain the listing's provenance and all reads and writes must succeed before execution begins. Guest results carry untrusted source integrity; fixed standing guidance is a separate item. When argument names contain hidden content, diagnostic prose and locations are withheld.

The spec requires POSIX, container isolation or stronger, closed egress, call isolation, and disposal. The host may configure a stronger router. The guest launcher clears inherited environment variables, uses a fixed filesystem provider mirror without a direct-install fallback, bounds combined CLI output to 128 KiB, and shares one deadline across CLI phases. `exec_timeout_seconds` defaults to 120 and accepts finite values in `(0, 600]`. Host execution allows an additional five seconds for transport and process cleanup. Cancellation waits for that bounded execution before core-owned disposal.

Provider validation executes native provider code. Expressions can read other guest files. Directory staging is not a confinement boundary: use a dedicated immutable image containing no credentials, host mounts, or sensitive content. This package does not support warm reuse, online dependency resolution, variable-dependent initialization, plan, apply, destroy, import, state commands, tests, or policy/security linting. A valid configuration does not establish that a deployment will succeed.

Build instructions, platform and dependency pins, and a runnable checkout example are in [the image README](https://github.com/sokolaidev/maf-extensions/blob/main/images/terraform-sandbox/README.md). Python wheels contain no engine or provider binaries. The initial measured guest platform is Linux amd64 on Docker; ACAS and WSLC have not been verified for this workload. [The kind guide](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/kinds/terraform.md) describes the evidence and remaining work.
