Project maturity & compatibility

CargoShip is production-oriented software, but it is still in the v0.x series and maintained by a small open-source team. This page states plainly what is stable, what is still evolving, and what guarantees you can (and can't) rely on — so you can judge it against your own risk tolerance. For the semantic-versioning rules behind these levels, see API stability & versioning.

What the levels mean

Stable means the interface and archive format are intended for continued use and are protected by release-gating verification against real S3. It does not imply a commercial support SLA or a long production history.

That distinction is deliberate. Stable paths have had consequential defects found in them — v0.16.1 and v0.17.0 fixed last-file truncation in compressed chunks and a path traversal on the default download path. What the label promises is not that no bug will be found; it is that the path is covered by the release gate, that a fix ships, and that the format keeps its compatibility guarantee. Every release's verification evidence is published — see verification reports.

Beta means functional and used, but the command surface, configuration, or wire format may change between minor releases (documented per release). Experimental means a capability exists in the library but is not wired into the CLI, or has not been exercised enough to rely on.

For capabilities that are not in CargoShip — those removed (some because they were non-functional or simulated) or deferred, and what a real version would take — see the roadmap. Nothing there is a shipping feature.

For the capabilities that are here, each is mapped to the evidence that proves it (and CI enforces those citations resolve) on the capability verification page.

Component maturity

Capability	Status	What that means
Archive & manifest format	Stable	Documented in the format spec. Manifest is v2.2; v2.1/v2.0 remain readable. Backward-readable across the versions the spec states — your archives don't become unreadable on upgrade.
Core upload / verify / restore	Stable	The canonical cargoship upload, verify, download, and restore paths are covered by integration + regression tests.
Cost, budget & lifecycle	Stable	Estimation, budgets/quotas, and lifecycle commands are established.
Sharding & compression	Stable	Multi-prefix sharding and content-aware zstd are core to the pipeline.
Encryption (SSE / KMS-envelope manifest)	Stable	See the security model.
DVC integration	Beta	The Go dvc commands and Python plugin work; command surface and metadata may change between minor releases (changes are documented per release).
Magika AI file detection	Beta / opt-in	Requires pip install magika; degrades gracefully when absent.
Multi-region	Experimental	A library capability in pkg/multiregion, not wired into cargoship upload today — see the multi-region note. Use --region + sharding for in-region parallelism.
Ghostship fleet mode	Beta	Unattended write-only agents with per-writer isolation, signed config over S3, heartbeats, budget caps and an immutability audit — shipped across v0.32.0–v0.35.0 (#604). Functional and exercised against real S3 and real IAM, but the config schema and the fleet/ghostship command surface may still change between minor releases. See fleet mode and the NAS guide.
Legacy ghost-ship agents	Removed	The central controller, cargoship-launch agent and webui were removed in v0.20.0 (#340); nothing accepts remote commands. The current fleet mode is outbound-only and unrelated to that design — see Distributed / Enterprise.
Public Go API	Mixed	Stability is per-package — some packages are stable, others beta. See API stability.

Guarantees

• Archive compatibility — archives written by a given release stay readable by later releases within the format-version guarantees in the spec. This is the guarantee that matters most for archival software, and it's the one we hold most firmly.
• Semantic versioning — v0.PATCH is always safe to upgrade; v0.MINOR may carry documented breaking changes while pre-1.0. See versioning.
• Security — the current minor release receives security fixes; see the Security Policy.

What is not promised

• No support SLA. Issues and vulnerability reports are handled best-effort by a small team — there is no contractual response or resolution time.
• No recovery-time objective for fleet agents. A writer that stops is reported as stale by cargoship fleet monitor, but nothing restarts it for you.
• macOS binaries are not notarized (#407), so a downloaded release is quarantined by Gatekeeper — see installation.
• dataset prune cannot prune encrypted-manifest datasets. It needs to read the manifest chain to decide what is safe to delete, which it cannot do for --encrypt-manifest datasets, so those grow until pruned by hand or by an S3 lifecycle rule.
• Pre-1.0 API churn. Beta and experimental components may change shape between minor releases; pin a version if you need stability.

Using it in production today

Reasonable if you: pin a specific release, rely on the stable components, keep verify in your workflow (prove the round trip), and treat beta/experimental features as opt-in. The archive format's portability — plain tar.zst objects plus a documented JSON manifest — means your data isn't hostage to the tool even if you stop using it.

Judge the claim on the evidence rather than the label: per-release verification reports record what round-tripped byte-identical on real S3 for each published version, and the integrity model explains how to reproduce it yourself.