Vox portability SSOT

This page defines the normative portability contract for deployed .vox applications.

Sibling contract (end-user app installers): shipping desktop/mobile installable artifacts (MSI/DMG/APK/IPA, etc.) is documented in Vox application packaging SSOT (2026). That lane complements this page’s Docker/OCI deploy focus and does not relax server-portability requirements here.

For background and rationale, see:

Portability contract

Vox application portability means:

a .vox project can declare deploy intent once,
the resolved project state can be packaged into a standardized deployable artifact contract,
and that artifact can be executed on supported runtime surfaces with documented caveats.

Vox portability does not guarantee:

identical kernel behavior across host operating systems,
transparent equivalence between Linux and Windows containers,
support for every host/runtime combination,
or secret management embedded inside application images.

Canonical source-of-truth boundaries

Concern	Canonical authority
Project desired state	`Vox.toml`
Project resolved state	`vox.lock`
Dependency resolution / fetch / cache / materialization	`vox-package`
Runtime-specific packaging and deployment	`vox-container`
User-visible CLI contract	`contracts/cli/command-registry.yaml`
Operator/runtime reference policy	`docs/src/reference/`
Toolchain release portability for `vox`	`crates/vox-install-policy/src/lib.rs`

Required invariants

Desired-state and resolved-state

Vox.toml must remain the project desired-state contract.
vox.lock must remain the project resolved-state contract.
Deploy packaging must not rely on undocumented implicit host state once a lock-bound lane is in effect.

Packaging and artifact policy

Portable app deployment must use Docker/OCI-backed packaging as the primary boundary.
Deployable images should be published as multi-architecture artifacts where portability claims require it.
Base images should be pinned by digest in reproducibility-sensitive lanes.
Promoted deploy artifacts should carry OCI metadata for source, revision, version, documentation, and license where supported.

Supply-chain and verification

Release-grade portability lanes should generate SBOM data.
Release-grade portability lanes should generate provenance attestations.
Signing policy should be applied to promoted immutable artifacts, especially where registry or deployment policy depends on verification.

Config and secrets

Per-deploy configuration must not be hardcoded into application code.
Secrets must not be baked into committed images.
Deploy configuration should use environment-variable conventions documented in Environment variables (SSOT).
Secret resolution must stay aligned with Secrets SSOT.

Runtime support statement

Docker is the primary documented portability abstraction for deployed .vox applications.
Podman compatibility is required where vox-container advertises runtime parity, especially for rootless/operator workflows.
Runtime detection is an execution concern, not a replacement for project-level deploy intent.
WASI/Wasmtime is a complementary execution/isolation lane and not the primary deployed-app portability boundary.
Stock-phone execution of the full Vox CLI/toolchain is not a portability requirement for this contract.
Mobile support is primarily browser-app portability plus remote control of a non-phone Vox host.

Portable backend artifact lane

For backend portability workstreams, use a single release-grade lane with explicit provenance:

Build artifacts from lock-bound project state (Vox.toml + vox.lock).
Publish OCI images with source/revision metadata labels.
Generate and retain SBOM + provenance attestations for promoted builds.
Apply signing policy before promotion to runtime environments.
Avoid embedding secrets in images; runtime secret resolution remains Clavis-managed.

Repo-local artifact markers (`vox deploy`)

When VOX_BACKEND_ARTIFACT_SBOM_REQUIRED or VOX_BACKEND_ARTIFACT_SIGNING_REQUIRED are truthy (environment SSOT), vox deploy requires marker files under <repo_root>/.vox/backend-artifact/ (resolved via vox_config::paths::repo_backend_artifact_dir) before a non–dry-run deploy on OCI-facing targets (container, compose, kubernetes, fly, coolify):

SBOM (at least one): sbom.json, sbom.spdx.json, or sbom.cyclonedx.json
Signing (at least one): signing.attestation.json or artifact.sig

Compatibility caveats

Containers share the host kernel. Portability claims apply to the artifact/runtime contract, not to kernel identity.
Linux-container portability and Windows-container portability are separate concerns.
Architecture mismatches remain relevant unless multi-arch publication is in place.
Docker Desktop on macOS and Windows introduces VM-backed behavior differences for Linux containers.
Volume mounts, file watching, permissions, and local networking can differ across Docker, Docker Desktop, and Podman.
Compose-as-OCI workflows have limitations around bind mounts, local includes, and build-only services.

Conformance checklist

Use this checklist when defining or validating portability-sensitive lanes: