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.PATCHis always safe to upgrade;v0.MINORmay 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 prunecannot prune encrypted-manifest datasets. It needs to read the manifest chain to decide what is safe to delete, which it cannot do for--encrypt-manifestdatasets, 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.