maf-sandbox-terraform

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.

Pass formatting=True to attach a second tool, terraform_format or opentofu_format, after validation. It accepts the same files and root_module arguments and runs fmt -recursive -no-color across the staged project. It skips initialization and needs no providers or modules, so the builtin image is sufficient. Its report contains a JSON mapping from store-relative paths to the complete formatted text of changed files; unchanged files are omitted. The model can write those whole files back with the host's file tools under the host's existing approvals. Neither sandbox tool writes to the store, and formatting does not validate the configuration.

Formatting returns all changed files or none. CLI output and returned file bytes share the 128 KiB allowance, and the complete JSON launcher report, including escaping and metadata, must also fit 128 KiB. A failed formatter, exceeded deadline, or oversized report returns Formatting INCOMPLETE without partial file text. Select a smaller complete manifest when necessary; one changed file larger than the allowance cannot be returned. Formatted text remains untrusted guest output, and hidden argument names withhold all returned text and locations. Formatting is disabled by default so hosts choose whether to attach or approve the additional tool.

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. 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 describes the evidence and remaining work.

Formatting requires a rebuilt image containing the launcher's fixed format mode. Rebuild base images and every derived prepared image together: preparation records the launcher's reader_sha256, so copying a new launcher into an old prepared image is not a supported update.