Terramantle
Get Started Free
Air-gapped

Running a Terraform and OpenTofu registry on the high side of a data diode

In defence, banking, healthcare and government networks, no internet access is the default, and most Terraform tooling quietly assumes the internet is there. This page covers what has to live inside the boundary, the exact OCI format artefacts cross it in, and how one OpenPGP signature over the manifest turns a pile of checksums into a chain of trust that also tells you precisely which blobs to send again.

Take the internet away and the Terraform ecosystem stops. The public registry is unreachable, provider downloads fail, and module sources that resolve over the internet don’t resolve at all. Security review isn’t a launch gate you pass once, either; it’s the daily condition of the environment. Anything you run inside the boundary has to assume it’s on its own.

What a provider mirror does not give you

The terraform providers mirror command and filesystem mirrors get provider binaries across, and they’re useful for that. They stop there. There’s no module distribution, no versioning workflow, no access control and no record of who published or consumed what. In a regulated environment that’s most of the job, which is why so many teams end up with a shared drive of tarballs and a wiki page or a markdown file that says which one is current.

Inside the boundary

Everything the workflow depends on lives on the high side: the registry API that serves the protocol, the artefact storage behind it, and the scan database that findings are checked against. Updates arrive as signed bundles across the boundary rather than as live fetches, and nothing inside reaches out. The one thing that never makes the trip is the signing key.

flowchart LR
  subgraph low["Low side (connected)"]
    direction TB
    Pub["Publishing pipeline"]
    Key["OpenPGP signing key<br/>private, never crosses"]
    Bundle["OCI bundle<br/>blobs + manifest + manifest.sig"]
    Pub --> Bundle
    Key -. signs the manifest .-> Bundle
  end
  Diode{{"Data diode<br/>one-way, hardware-enforced"}}
  subgraph high["High side (air-gapped)"]
    direction TB
    Import["Import + verify"]
    Reg["Terramantle registry"]
    Store[("Artefact storage")]
    Scan[("Scan / CVE database")]
    Import --> Reg
    Reg --> Store
    Reg --> Scan
  end
  Bundle ==>|"blob by blob"| Diode
  Diode ==> Import
  classDef key fill:#1e0838,stroke:#e27dff,color:#ffc2f5
  classDef diode fill:#2a1a05,stroke:#f59e0b,color:#ffd58a
  classDef verify fill:#1e0838,stroke:#8c25ea,color:#eef3fa
  class Key key
  class Diode diode
  class Import verify
What lives on the high side, and how updates arrive. The private key stays low-side; only its signature crosses.

Crossing the diode

A data diode, for readers who haven’t worked in these environments, is a hardware-enforced one-way link, often optical, with physically no return path. That rules out handshakes, acknowledgements and retransmit requests. The receiving side has to detect corruption and reassemble the transfer on its own, because it can never ask the sender for anything. Any format you push through it has to carry its own verification and has to fail in pieces, not as a whole.

That constraint is what makes the OCI Specificaltion the right wire format. While originally conceived for container images, now any artefact can be wrapped as an OCI artefact. Every blob in an OCI bundle is addressed by the SHA-256 of its own bytes, so verification is part of the addressing scheme rather than something bolted on afterwards. A bundle on disk is an OCI image layout: a marker file, an index, and a flat directory of blobs named by digest. The manifest is just another blob in that directory. Docker’s save format writes it out as manifest.json, and I’ll call it that below, but the point of the OCI layout is that the manifest is content-addressed like everything else, which is what makes it signable and verifiable in exactly the same way.

bundle-0042/
├── oci-layout                   {"imageLayoutVersion": "1.0.0"}
├── index.json                   one entry: the manifest, by digest
├── manifest.sig                 detached OpenPGP signature over the manifest blob
└── blobs/sha256/
    ├── ce7214c1…b783ed4a        the manifest ("manifest.json" in Docker's save format)
    ├── f816d021…1d4c29e4        config: the bundle inventory
    ├── 899fbc7f…10fec697        module tarball        acme/vpc/aws 3.4.1
    ├── d86da3aa…2fa4aaf8        provider zip, chunk 1  terramantle/aws 5.70.0 linux_amd64
    ├── c5cd9935…6d961ca         provider zip, chunk 2
    ├── cf86a3ab…7470e1b0        provider SHA256SUMS
    ├── 279661b6…dc86b53a        provider SHA256SUMS.sig
    ├── 81197ca1…d8ccf32d        provider SBOM (SPDX)
    └── 6d9ff790…7cedfaa6        CVE database delta    2026-10-29 -> 2026-11-05

The manifest is where a bundle stops being a generic container image and becomes a Terramantle transfer artefact. OCI only fixes the frame: a schemaVersion, a config descriptor, a list of layers, and free-form annotations. Every descriptor carries a mediaType, a digest and a size. The media types are ours to define, and standard tooling (oras, skopeo, crane) doesn’t care what they say, because it only ever moves bytes by digest. So Terramantle uses the vendor-tree names for what the blobs actually are:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.terramantle.bundle.v1",
  "config": {
    "mediaType": "application/vnd.terramantle.bundle.config.v1+json",
    "digest": "sha256:f816d02194d3c58175f2b34ba3c8e508150ff3581ca84a3355b12e161d4c29e4",
    "size": 1482
  },
  "layers": [
    {
      "mediaType": "application/vnd.terramantle.module.v1.tar+gzip",
      "digest": "sha256:899fbc7f7328668265c5e544d4ba579fef087815c407b87c367d91ed10fec697",
      "size": 48213,
      "annotations": {
        "org.opencontainers.image.title": "acme-vpc-aws-3.4.1.tgz",
        "dev.terramantle.module": "acme/vpc/aws",
        "dev.terramantle.version": "3.4.1"
      }
    },
    {
      "mediaType": "application/vnd.terramantle.provider.v1.zip",
      "digest": "sha256:d86da3aa882b23ea85ad4cf525cb2926b213f3e0bf8803c463e99b622fa4aaf8",
      "size": 67108864,
      "annotations": {
        "org.opencontainers.image.title": "terraform-provider-aws_5.70.0_linux_amd64.zip",
        "dev.terramantle.provider": "terramantle/aws",
        "dev.terramantle.version": "5.70.0",
        "dev.terramantle.platform": "linux_amd64",
        "dev.terramantle.chunk": "1/2",
        "dev.terramantle.chunk.whole": "sha256:d34d3d7e39fc217d600d0ddac78355a898f001cd10eb6ec6be805b2fb4f1be9c"
      }
    },
    {
      "mediaType": "application/vnd.terramantle.provider.v1.zip",
      "digest": "sha256:c5cd993587342833830d0eefde061ee92804513fce8ce9b0418a901446d961ca",
      "size": 41287903,
      "annotations": {
        "org.opencontainers.image.title": "terraform-provider-aws_5.70.0_linux_amd64.zip",
        "dev.terramantle.provider": "terramantle/aws",
        "dev.terramantle.version": "5.70.0",
        "dev.terramantle.platform": "linux_amd64",
        "dev.terramantle.chunk": "2/2",
        "dev.terramantle.chunk.whole": "sha256:d34d3d7e39fc217d600d0ddac78355a898f001cd10eb6ec6be805b2fb4f1be9c"
      }
    },
    {
      "mediaType": "application/vnd.terramantle.provider.sha256sums.v1",
      "digest": "sha256:cf86a3abda4e0e5cf29fd29f8e991771544a2659660087795b0ac0497470e1b0",
      "size": 1211,
      "annotations": { "dev.terramantle.provider": "terramantle/aws", "dev.terramantle.version": "5.70.0" }
    },
    {
      "mediaType": "application/vnd.terramantle.provider.sha256sums.sig.v1",
      "digest": "sha256:279661b63276df4664c52e11cef0565f276783cb64ed4427912bdf11dc86b53a",
      "size": 566,
      "annotations": { "dev.terramantle.provider": "terramantle/aws", "dev.terramantle.version": "5.70.0" }
    },
    {
      "mediaType": "application/vnd.terramantle.sbom.spdx.v1+json",
      "digest": "sha256:81197ca1c1ea6d05c2c9a559d1585882e91555f00174f3fdb5c79db8d8ccf32d",
      "size": 912044,
      "annotations": { "dev.terramantle.provider": "terramantle/aws", "dev.terramantle.version": "5.70.0" }
    },
    {
      "mediaType": "application/vnd.terramantle.cve-db.delta.v1.tar+zstd",
      "digest": "sha256:6d9ff7906ab62d6fb71fc8f15b5747473f88b6ec48983b0c5f7ed52e7cedfaa6",
      "size": 23068672,
      "annotations": { "dev.terramantle.cve-db.from": "2026-10-29", "dev.terramantle.cve-db.to": "2026-11-05" }
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2026-11-05T09:14:02Z",
    "dev.terramantle.bundle.source": "registry.low.example.internal",
    "dev.terramantle.bundle.sequence": "42",
    "dev.terramantle.bundle.previous": "sha256:4b1e0c9a7d2f6e3b8c5a1d0f9e8b7c6d5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d"
  }
}

Three parts of that are doing real work. The config blob is the bundle’s inventory: which modules, provider versions and platforms it carries, which scan-database window it covers, and which low-side instance exported it. It is small, it is read first, and it means the high side knows what a complete import looks like before a single layer has arrived. The layers are one blob per artefact, each typed by media type so the importer knows whether it is looking at a module tarball, a provider zip, the provider’s own SHA256SUMS and signature, an SPDX SBOM or a CVE-database delta, and never has to guess from a filename. A provider zip over the diode’s transfer unit is split into chunk layers, each with its own digest and a dev.terramantle.chunk annotation pointing back at the digest of the whole file, so a corrupted chunk is isolated on its own and the fix is one blob, not a hundred-megabyte archive. The annotations are the routing: the registry coordinates the importer files each layer under, and at the manifest level the bundle sequence number and the digest of the previous manifest, so a missed transfer window shows up as a gap rather than silently producing a registry that is one bundle behind.

Standard OCI tooling exists on both sides of the boundary, so there is nothing bespoke to build to move the bytes and nothing bespoke to put through accreditation. What the tooling cannot tell you is whether those bytes came from your publishing pipeline.

Digests prove integrity, not authenticity

A digest proves a blob’s bytes are intact. It does not prove who produced them. An attacker or a corrupt process that can alter a blob on the destination side can also recompute its digest and rewrite the manifest, swapping a binary while leaving the whole bundle self-consistent. Every digest still matches, and nothing looks wrong. The manifest is the single document the whole bundle hangs from, so the manifest is what has to be signed.

Terramantle closes the gap with one detached OpenPGP signature over the manifest bytes, made on the low side with a private key that never crosses the diode. It is the same signing mechanism that already sits behind every provider Terramantle rebuilds: a binary detached signature over SHA256SUMS, made with gpg --detach-sign and SHA-256 as the digest algorithm, which is exactly what tofu init and terraform init verify before they will install a provider. The bundle applies it one level up, to the manifest that names the SHA256SUMS and everything else. The signature travels as a sidecar, manifest.sig, because across a diode a sidecar file is simpler than an OCI 1.1 referrer manifest and the tooling moving the blobs does not need to understand it.

On the high side the public key is provisioned out of band, as a fingerprint checked by a human rather than a file that arrived over the same link it is meant to vouch for. Verification then runs in a fixed order, and each step only trusts what the previous one proved:

# 1. The manifest is the one index.json names
jq -r '.manifests[0].digest' index.json           # sha256:ce7214c1…
sha256sum blobs/sha256/ce7214c1…                   # must match

# 2. The manifest is the one the low side signed.
#    The public key arrived out of band (not over the diode) and lives in its own keyring.
gpg --no-default-keyring --keyring ./terramantle-bundle.gpg \
    --verify manifest.sig blobs/sha256/ce7214c1…

# 3. Every blob the signed manifest lists is present and intact
jq -r '.config.digest, .layers[].digest' blobs/sha256/ce7214c1… \
  | sed 's#^sha256:\(.*\)#\1  blobs/sha256/\1#' \
  | sha256sum -c --quiet

That order is the chain of trust. The key you hold proves the signature; the signature proves the manifest bytes; the manifest proves which digests belong in the bundle; each digest proves which bytes belong to it. Break any link and the import fails by name. Rewrite the manifest and the signature fails. Swap a blob and its digest no longer appears in the manifest that did pass. Point index.json at a different manifest and the signature does not cover it. There is no position on the far side of the diode from which a checksum can be changed without breaking the signature that sits above it.

Verifying the manifest first also answers the question a diode never lets you ask the sender: what is missing? Once the signature passes, the manifest is a trusted list of every digest that should be present, so the importer can account for each one and say which did not arrive or arrived damaged. Blobs that verify are kept, because a blob whose digest is in a signed manifest is as trustworthy on its own as it is in company. Artefacts whose blobs are all present are imported and served; the rest are held, and the report names the exact digests to send again in the next transfer window.

$ terramantle bundle import ./bundle-0042
manifest    sha256:ce7214c1…  signature OK   key 7F3A 9C21 … (Terramantle bundle signing)
config      sha256:f816d021…  ok
layer 1/7   sha256:899fbc7f…  ok              module    acme/vpc/aws 3.4.1
layer 2/7   sha256:d86da3aa…  ok              provider  terramantle/aws 5.70.0 linux_amd64 (chunk 1/2)
layer 3/7   sha256:c5cd9935…  MISSING         provider  terramantle/aws 5.70.0 linux_amd64 (chunk 2/2)
layer 4/7   sha256:cf86a3ab…  ok              provider  SHA256SUMS
layer 5/7   sha256:279661b6…  ok              provider  SHA256SUMS.sig
layer 6/7   sha256:81197ca1…  ok              sbom      terramantle/aws 5.70.0
layer 7/7   sha256:6d9ff790…  DIGEST MISMATCH cve-db    2026-10-29 -> 2026-11-05

Imported 1 of 3 artefacts: acme/vpc/aws 3.4.1 is now served.
Held: terramantle/aws 5.70.0 (1 blob missing), cve-db delta (1 blob corrupt).
Verified blobs are kept. 2 blobs need resending in the next window:
  sha256:c5cd993587342833830d0eefde061ee92804513fce8ce9b0418a901446d961ca
  sha256:6d9ff7906ab62d6fb71fc8f15b5747473f88b6ec48983b0c5f7ed52e7cedfaa6

Where this stands: the OpenPGP signer is in production and signs every rebuilt provider today. The bundle exporter and the importer above are the design built on that signer, not yet a released command.

sequenceDiagram
  autonumber
  participant L as Low side
  participant D as Data diode
  participant H as High side
  L->>L: Assemble bundle: blobs + manifest
  L->>L: Detached OpenPGP signature over the manifest bytes
  L->>D: manifest + manifest.sig (small, sent first)
  D->>H: deliver (no ack, no retransmit)
  H->>H: Verify signature against the out-of-band public key
  Note over H: The manifest is now the trusted list of digests
  loop each blob
    L->>D: blob, addressed by its digest
    D->>H: deliver
    H->>H: sha256(bytes) == a digest in the signed manifest?
  end
  alt every listed digest present and matching
    H->>H: Import. The registry serves the new versions
  else any digest missing or wrong
    H->>H: Keep the verified blobs, print the digests still needed
    Note over L,H: The operator carries that list back. Only those blobs are resent
  end
Manifest and signature cross first, so the high side verifies the list before the blobs; each blob is then checked against that list, and what fails is named by digest for the next window.

Running it

Install Terramantle self-hosted on the high side against your own storage, database and identity provider. Import modules and providers from an internal pipeline over OIDC against your internal identity provider, so there are no long-lived tokens even inside the boundary. Consume it from a workspace with the usual source address, and run offline scans against the imported CVE database. None of these steps reach the internet.

The keyless publishing flow is the one described in no runners, no agents, and it works the same way under OpenTofu; see the private OpenTofu registry page.

The chain of trust is itself evidence

You get an audit trail of who published and consumed what, and SPDX SBOMs per provider version for security review. The signed manifest is accreditation evidence in its own right: it demonstrates that what runs on the high side is provably what was signed on the low side, with no point along the way, including the import itself, where an artefact could be swapped without detection.

Air-gap FAQ

How do updates cross a data diode?

You export the modules, providers and scan-database updates you want as an OCI bundle on the connected (low) side, sign its manifest, and send it across the diode as individually addressed blobs. The air-gapped (high) side verifies the signature on the manifest first, then checks every blob against the digests that signed manifest lists, and only then imports. Nothing on the high side ever reaches back out.

How do you stop artefacts being tampered with in transit?

Digests alone are not enough, because anything that can alter a blob on the destination can also recompute its digest and rewrite the manifest so the bundle stays self-consistent. The signature closes that gap. The manifest is signed with an OpenPGP key that never crosses the diode, and the high side verifies it against a public key provisioned out of band. A rewritten manifest fails the signature; a swapped blob fails its digest against the manifest that did pass.

Why sign the manifest rather than every blob?

Because the manifest already names every blob by digest, one signature over it covers all of them. Verification on the high side is one signature check plus one hash per blob, and a blob that fails is identified by its digest, so the operator knows exactly what to resend. Signing each blob separately would multiply the signatures without proving anything the manifest signature does not already prove.

Is the bundle transfer available today?

The signing pipeline is: Terramantle produces a binary detached OpenPGP signature over the SHA256SUMS of every provider it rebuilds, and tofu init verifies it. The bundle exporter and importer described on this page are the design built on that signer and are not yet a released command.

Does Terramantle need any outbound internet access?

No. Terramantle runs fully self-hosted with no outbound dependency. You bring your own S3-compatible storage and database, you mirror the providers you need, and no module, provider, or state data leaves your infrastructure. Supply-chain scanning and OPA policy checks run locally against the artefacts you host.

Last reviewed

Terramantle is a private Terraform and OpenTofu registry. See pricing or read the FAQ.