BoxFerry

BoxFerry is an open-source CLI and Rust library for source-aware conversion of container application definitions between Docker Compose, Podman resources, and Podman Quadlet. Every conversion passes through a format-neutral model, so incompatible intent remains visible as structured diagnostics instead of being silently discarded.

Website · Getting started · crates.io · Rust API

What it converts

Input	Compose	Podman	Quadlet
Compose	Generated Compose	Reviewable Podman artifacts	Generated unit files
Podman	Generated Compose	Reviewable Podman artifacts	Generated unit files
Quadlet	Generated Compose	Reviewable Podman artifacts	Generated unit files

All nine routes use the same importer → neutral model → exporter pipeline. Same-format conversion is never a native passthrough. Docker Engine resources and Kubernetes are not yet implemented.

Quick start

BoxFerry supports Linux and client-side conversion on macOS. On Windows, run the Linux CLI inside WSL2. See installation for release archives and platform limits.

cargo install boxferry --locked
boxferry convert compose quadlet --input-file compose.yaml --output-directory quadlet-output

The output directory may be absent or empty. BoxFerry refuses to overwrite an existing entry.

Safety model

• Podman input is read-only. The CLI checks only conventional local sockets unless the user supplies an explicit socket; embedded callers retain a caller-selected transport boundary.
• Podman output is review material, not an observed inventory or an apply operation.
• BoxFerry never executes generated commands or units. A user who runs the command script performs real Podman operations.
• Runtime mutation and infrastructure deployment are outside the product.
• Compose interpolation starts with --env, --env-file, or --interpolate; BoxFerry reads no implicit .env file.
• Secrets are redacted from diagnostics and reports by default.

Choose the next document

• Install and run a first conversion
• Follow a conversion guide
• Use the CLI reference
• Understand the model and loss policy
• Develop BoxFerry

The same pages are published at boxferry.dev/docs. Every displayed BoxFerry command is executed by repository tests.

Rust libraries

The boxferry crate is the supported facade. Component crates expose the neutral model, engine, and individual adapters. ComposeLens, PodmanLens, and QuadletLens own their native formats.

Open source

BoxFerry is maintained by Martin “Becks” Beckert through Strukturpiloten OHG and released under the Mozilla Public License 2.0. Contributions, issue reports, and practical migration feedback are welcome.

Use ./scripts/format-lint.sh --fix (or the VS Code task BoxFerry: Format and lint only (no tests)) for quick pre-push cleanup on a smaller development computer. It deliberately executes no tests and is not validation evidence. Run the complete development gate with ./scripts/check-all.sh when resources permit; protected GitHub checks remain authoritative for every pull request.