Bifröst
Architecture & Deployment Models

Architecture & deployment models

How Bifrost's services fit together, and the network topologies it's built to run in.

"Air-gapped" isn't one thing — it's a spectrum, from a network with no external connectivity at all, to a restricted network that's allowed narrow, audited egress through a proxy. Bifrost is built as a set of small services specifically so it can be arranged differently for each of those cases, rather than assuming one topology and forcing everyone else to work around it.

Two things vary independently between deployments: how strictly the network is split (see Supported topologies), and what mechanism actually carries approved artifacts across the boundary (see Transfer mechanisms). This page covers both.

The core services

ServiceWhat it does
Orchestrator APIREST control plane: accepts download/schedule requests, tracks job state
Minion workersDo the fetching — one process family per package ecosystem
Message queueCarries jobs from the Orchestrator to Minions asynchronously
PostgresPersists job/schedule/auth state
KeycloakOAuth2/OIDC identity provider — every request is authenticated
Transfer mechanismMoves approved artifacts across the security boundary — its shape (and which components sit on which side) varies by deployment; see Transfer mechanisms

The low-side / high-side split

In a genuinely air-gapped setup, Bifrost's services split across two zones — though which services sit on which side depends on the transfer mechanism in use (see below):

  • Low side — has internet access. Always runs the Minion workers that reach out to Docker Hub, PyPI, npm, Maven Central, Hugging Face, etc. Depending on the deployment, it may also run the Orchestrator API and everything else — see Transfer mechanisms.
  • High side — has no internet access. Runs whatever consumes the downloaded artifacts. In some deployments it also runs the Orchestrator API and Postgres; in others those live on the low side too, and only approved artifacts cross.
  • The transfer mechanism — the only thing that crosses between the two zones. It moves approved, already-fetched artifacts from low side to high side under policy. Whether it's strictly one-way is a property of which mechanism is in use, not a given — see below.

This is the piece that changes most between deployments, and why "architecture" gets its own section instead of being folded into a single deployment guide.

Transfer mechanisms

However the network is split, something has to actually carry approved artifacts across the boundary. Bifrost supports three patterns today, and a fourth is planned. These are independent of network topology (below) — pick the split that matches your compliance boundary, then pick the mechanism that matches your operational constraints.

MechanismWhat crossesDirectionComponents on low sideComponents on high sideOperational overhead
Bridge sync (reference setup)Job requests down, artifacts back upTwo-way. Either a single live connection (simplest, no physical one-way guarantee), or a matched pair of diodes — one per direction — each leg still strictly one-wayMinion workers, plus a queue and a bridge instance when diode-pairedOrchestrator API, Postgres, Keycloak, plus a queue and a bridge instance when diode-pairedLow (live connection) to medium (diode-paired) — automated either way
Diode relayOnly artifact files (and their metadata)Strictly one-way, by construction of the diode hardware — not by policy or software trustOrchestrator API, Minions, Postgres, Keycloak — everything except ingestAn ingest watcher (e.g. NiFi, or a simple directory watcher) that picks up replicated filesMedium — automated, but requires diode hardware and an ingest step
Manual carryWhatever an operator chooses to exportOne-way, enforced procedurally (there's no automated path at all, in either direction)Everything — Orchestrator API, UI, Minions, Postgres, KeycloakNothing Bifrost-specific; artifacts are imported by handHigh — no live software crosses the boundary; relies entirely on operator process

Bridge sync can be wired two ways. The simplest is a single live connection: one NiFi instance bridges directly across the boundary in real time. That's easy to operate, but doesn't physically guarantee one-way traffic — a misconfigured or compromised bridge could open a path back. For a hard guarantee, some deployments instead run a message queue and a NiFi instance on each side, and sync the two queues across the gap through a matched pair of diodes — one file-based or HTTP-based diode per direction. Each diode is itself strictly one-way, same as in diode relay below; running one per direction is what gives you a genuinely two-way sync without ever opening a single bidirectional channel.

Bridge sync, diode-paired variantA message queue and NiFi bridge run on the high side, and a matching queue and bridge run on the low side. The two are synced across the gap through a matched pair of one-way diodes — one carrying job requests down, one carrying artifacts back up — so the two-way sync never opens a single bidirectional channel.High side — no internet accessOrchestrator APIPostgresstateKeycloakauthQueueRabbitMQBridge (NiFi)high siderequestsartifactsLow side — has internet accessBridge (NiFi)low sideQueueRabbitMQMinion workers

In the diode relay pattern, Minions write approved output to a drop point — a local directory today, with a network share also supported and S3 planned as a drop point — and a single diode replicates that drop point one-way to the high side, where a watcher ingests new files into the registry or repo.

Diode relay transfer mechanismOn the low side, the Orchestrator API, Minion workers, Postgres, and Keycloak run together and Minions write approved output to a drop point. A single hardware diode replicates the drop point one-way to the high side, where a watcher ingests new files into the registry or repo.Low side — has internet accessOrchestrator APIPostgresstateKeycloakauthMinion workersDrop pointdirectory · sharediode — one-wayHigh side — no internet accessIngest watcherNiFi or directory watcherRegistry / repohigh-side target

Bridge sync (live connection) is the best fit when you need near-real-time delivery and don't need a hard one-way guarantee; bridge sync (diode-paired) gets you the same near-real-time, two-way experience with that guarantee, at the cost of running doubled infrastructure. Diode relay is the best fit when you only ever need artifacts to flow one direction and some ingest latency is acceptable. Manual carry is the simplest to stand up and audit, at the cost of the most recurring operator effort — often a reasonable choice for low volume or as a fallback path alongside one of the other two.

Manual carry transfer mechanismEvery Bifrost component — Orchestrator API, UI, Minion workers, Postgres, Keycloak — runs on the low side. An operator exports an approved bundle and carries it across the boundary by hand, on physical media. Nothing Bifrost-specific runs on the high side; the operator imports the bundle themselves.Low side — has internet accessOrchestrator API + UIPostgresstateKeycloakauthMinion workersExport bundleoperator selects & signscarried by handno live connectionHigh side — no internet accessImported by handno Bifrost component on this side

Supported topologies

This is the other axis: how strictly the network itself is split, as distinct from what mechanism carries data across it (above). Any of the transfer mechanisms above can in principle be used within any of these topologies.

  • Fully air-gapped, dual-bridge — physically separate networks, with a one-way (or tightly mediated two-way) transfer mechanism as the only connection. Highest assurance, most operational overhead.
  • DMZ relay — a single hardened relay zone brokers transfers between an internal network and the internet, rather than the internal network talking to Minions directly.
  • Proxied restricted network — no hard air gap, but all outbound traffic is forced through an inspected, allow-listed proxy. Lower operational overhead, appropriate when the constraint is "controlled egress" rather than "no egress."
Fully air-gapped, dual-bridge topologyTwo physically separate networks — low side and high side — with a transfer mechanism as their only connection. Which services sit on which side, and which mechanism carries data across, both depend on the chosen transfer mechanism.Low side networkBifrost servicesplacement depends on mechanismHigh side networkBifrost servicesplacement depends on mechanismTransfermechanism DMZ relay topologyAn internal network runs the Orchestrator API, Postgres, and Keycloak. It never talks to the internet directly — instead a hardened DMZ relay zone, running the Minion workers, brokers every transfer between the internal network and the internet.Internal networkInternal servicesOrchestrator, Postgres, KeycloakDMZ relayMinion workershardened relayInternetPackage registries Proxied restricted network topologyAll Bifrost services — Orchestrator API, Minion workers, Postgres, Keycloak — run together in one restricted network, with no hard air gap. Every outbound request is forced through an inspected, allow-listed proxy before it reaches the internet.Restricted network — no hard air gapBifrost servicesOrchestrator, Minions, Postgres, KeycloakProxyinspectedInternet

Which topology fits depends on your actual compliance boundary — this page will grow with policy-configuration guidance for each as the docs mature.

Next steps

Overview

What Bifrost is and how its pieces fit together.

Deployment — Docker Compose

Run the full Bifrost stack locally with the reference docker-compose.yaml.

On this page

The core servicesThe low-side / high-side splitTransfer mechanismsSupported topologiesNext steps