volt/docs/bundles.md

Volt Bundles

volt bundle manages portable, self-contained application bundles. A bundle packages everything needed to deploy a stack — container images, VM disk images, a Constellation definition, configuration, and lifecycle hooks — into a single .vbundle file.

Quick Start

# Create a bundle from your Constellation
volt bundle create -o my-stack.vbundle

# Inspect a bundle
volt bundle inspect my-stack.vbundle

# Deploy a bundle
volt bundle import my-stack.vbundle

# Export a running stack as a bundle
volt bundle export my-stack -o my-stack.vbundle

Bundle Format

A .vbundle is a ZIP archive with this structure:

my-stack.vbundle
├── bundle.json           # Bundle manifest (version, platforms, service inventory, hashes)
├── compose.yaml          # Constellation definition / Voltfile (service topology)
├── images/               # Container/VM images per service
│   ├── web-proxy/
│   │   ├── linux-amd64.tar.gz
│   │   └── linux-arm64.tar.gz
│   ├── api-server/
│   │   └── linux-amd64.tar.gz
│   └── db-primary/
│       └── linux-amd64.qcow2
├── config/               # Per-service configuration overlays (optional)
│   ├── web-proxy/
│   │   └── nginx.conf
│   └── api-server/
│       └── .env.production
├── signatures/           # Cryptographic signatures (optional)
│   └── bundle.sig
└── hooks/                # Lifecycle scripts (optional)
    ├── pre-deploy.sh
    └── post-deploy.sh

Bundle Manifest (bundle.json)

The bundle manifest describes the bundle contents, target platforms, and integrity information:

{
  "version": 1,
  "name": "my-stack",
  "bundleVersion": "1.2.0",
  "created": "2025-07-14T15:30:00Z",
  "platforms": [
    { "os": "linux", "arch": "amd64" },
    { "os": "linux", "arch": "arm64" },
    { "os": "android", "arch": "arm64-v8a" }
  ],
  "services": {
    "web-proxy": {
      "type": "container",
      "images": {
        "linux/amd64": {
          "path": "images/web-proxy/linux-amd64.tar.gz",
          "format": "oci",
          "size": 52428800,
          "digest": "blake3:a1b2c3d4..."
        }
      }
    }
  },
  "integrity": {
    "algorithm": "blake3",
    "files": { "compose.yaml": "blake3:1234...", "..." : "..." }
  }
}

Multi-Architecture Support

A single bundle can contain images for multiple architectures. During import, Volt selects the right image for the host:

# Build a multi-arch bundle
volt bundle create --platforms linux/amd64,linux/arm64,android/arm64-v8a -o my-stack.vbundle

Supported Platforms

OS	Architecture	Notes
Linux	amd64 (x86_64)	Primary server platform
Linux	arm64 (aarch64)	Raspberry Pi 4+, ARM servers
Linux	armv7	Older ARM SBCs
Android	arm64-v8a	Modern Android devices
Android	armeabi-v7a	Older 32-bit Android
Android	x86_64	Emulators, Chromebooks

Image Formats

Format	Extension	Type	Description
oci	.tar, .tar.gz	Container	OCI/Docker image archive
rootfs	.tar.gz	Container	Plain filesystem tarball
qcow2	.qcow2	VM	QEMU disk image
raw	.raw, .img	VM	Raw disk image

CAS Integration

Instead of embedding full images, bundles can reference Stellarium CAS hashes for deduplication:

# Create bundle with CAS references (smaller, requires CAS access to deploy)
volt bundle create --cas -o my-stack.vbundle

In the bundle manifest, CAS-referenced images have path: null and a casRef field:

{
  "path": null,
  "format": "oci",
  "digest": "blake3:a1b2c3d4...",
  "casRef": "stellarium://a1b2c3d4..."
}

During import, Volt resolves CAS references from the local store or pulls from remote peers.

Commands

volt bundle create

Build a bundle from a Voltfile or running composition.

# From Constellation in current directory
volt bundle create -o my-stack.vbundle

# Multi-platform, signed
volt bundle create \
  --platforms linux/amd64,linux/arm64 \
  --sign --sign-key ~/.config/volt/signing-key \
  -o my-stack.vbundle

# From a running stack
volt bundle create --from-running my-stack -o snapshot.vbundle

# ACE-compatible (for Android deployment)
volt bundle create --format ace --platforms android/arm64-v8a -o my-stack.zip

# Dry run
volt bundle create --dry-run

volt bundle import

Deploy a bundle to the local system.

# Basic import
volt bundle import my-stack.vbundle

# With verification and hooks
volt bundle import --verify --run-hooks prod.vbundle

# With environment overrides
volt bundle import --set DB_PASSWORD=secret --set APP_ENV=staging my-stack.vbundle

# Import without starting
volt bundle import --no-start my-stack.vbundle

# Force overwrite existing
volt bundle import --force my-stack.vbundle

volt bundle export

Export a running composition as a bundle.

# Export running stack
volt bundle export my-stack -o my-stack.vbundle

# Include volume data
volt bundle export my-stack --include-volumes -o full-snapshot.vbundle

volt bundle inspect

Show bundle contents and metadata.

$ volt bundle inspect my-stack.vbundle
Bundle: my-stack v1.2.0
Created: 2025-07-14 15:30:00 UTC
Platforms: linux/amd64, linux/arm64
Signed: Yes (ed25519)

Services:
  NAME          TYPE        IMAGES            CONFIG FILES   SIZE
  web-proxy     container   2 (amd64, arm64)  1              95 MB
  api-server    container   1 (amd64)         1              210 MB
  db-primary    vm          1 (amd64)         1              2.1 GB

# Show full bundle manifest
volt bundle inspect my-stack.vbundle --show-manifest

# JSON output
volt bundle inspect my-stack.vbundle -o json

volt bundle verify

Verify signatures and content integrity.

$ volt bundle verify prod.vbundle
✓ Bundle signature valid (ed25519, signer: karl@armoredgate.com)
✓ Manifest integrity verified (12 files, BLAKE3)
Bundle verification: PASSED

# Deep verify (check CAS references)
volt bundle verify --deep cas-bundle.vbundle

volt bundle push / volt bundle pull

Registry operations.

# Push to registry
volt bundle push my-stack.vbundle --tag v1.2.0 --tag latest

# Pull from registry
volt bundle pull my-stack:v1.2.0

# Pull for specific platform
volt bundle pull my-stack:latest --platform linux/amd64

volt bundle list

List locally cached bundles.

$ volt bundle list
NAME          VERSION   PLATFORMS         SIZE     CREATED              SIGNED
my-stack      1.2.0     amd64,arm64       1.8 GB   2025-07-14 15:30    ✓
dev-env       0.1.0     amd64             450 MB   2025-07-13 10:00    ✗

Lifecycle Hooks

Hooks are executable scripts that run at defined points during deployment:

Hook	Trigger
validate	Before deployment — pre-flight checks
pre-deploy	After extraction, before service start
post-deploy	After all services are healthy
pre-destroy	Before services are stopped
post-destroy	After cleanup

Hooks are opt-in — use --run-hooks to enable:

volt bundle import --run-hooks my-stack.vbundle

Review hooks before enabling:

volt bundle inspect --show-hooks my-stack.vbundle

Signing & Verification

Bundles support Ed25519 cryptographic signatures for supply chain integrity.

# Create a signed bundle
volt bundle create --sign --sign-key ~/.config/volt/signing-key -o prod.vbundle

# Verify before deploying
volt bundle import --verify prod.vbundle

# Trust a signing key
volt config set bundle.trusted_keys += "age1z3x..."

Every file in a bundle is content-hashed (BLAKE3) and recorded in the bundle manifest's integrity field. Verification checks both the signature and all content hashes.

ACE Compatibility

Volt bundles are an evolution of the ACE (Android Container Engine) project bundle format. ACE bundles (ZIP files with compose.json and images/ directory) are imported transparently by volt bundle import.

# Import an ACE bundle directly
volt bundle import legacy-project.zip

# Create an ACE-compatible bundle
volt bundle create --format ace -o project.zip

Configuration Overlays

The config/ directory contains per-service configuration files applied after image extraction:

config/
├── web-proxy/
│   └── nginx.conf          # Overwrites /etc/nginx/nginx.conf in container
└── api-server/
    └── .env.production     # Injected via volume mount

Config files support ${VARIABLE} template expansion, resolved from the Constellation's environment definitions, env_file references, or --set flags during import.

Full Specification

See the complete Volt Bundle Format Specification for:

• Detailed bundle.json schema and JSON Schema definition
• Platform/architecture matrix
• CAS reference resolution
• Signature verification flow
• Registry HTTP API
• Error handling and recovery
• Comparison with OCI Image Spec