Architecture Overview

Volt is built on Linux-native primitives rather than custom daemons. Containers use systemd-nspawn, VMs use KVM, storage uses content-addressed hashing, and everything is managed through systemd. No Docker daemon. No containerd. No shims.

Platform Components

┌──────────────────────────────────────────────────────────────────┐
│                         volt CLI                               │
│                    (single Go binary)                            │
└──────────────┬──────────────┬──────────────┬────────────────────┘
               │              │              │
     ┌─────────▼──────┐ ┌────▼────────┐ ┌───▼──────────┐
     │   Voltainer    │ │  Voltvisor  │ │  Stellarium  │
     │  (containers)  │ │   (VMs)     │ │    (CAS)     │
     ├────────────────┤ ├─────────────┤ ├──────────────┤
     │ systemd-nspawn │ │ KVM/QEMU    │ │ SHA256 store │
     │ machinectl     │ │ Stardust    │ │ dedup blobs  │
     │ nsenter        │ │ cloud-init  │ │ refs/manifst │
     └───────┬────────┘ └──────┬──────┘ └──────┬───────┘
             │                 │               │
     ┌───────▼─────────────────▼───────────────▼───────┐
     │                    systemd                       │
     │  units · targets · journald · cgroups · timers  │
     └───────────────────────┬─────────────────────────┘
                             │
     ┌───────────────────────▼─────────────────────────┐
     │                  Linux Kernel                    │
     │   namespaces · cgroups v2 · KVM · nftables      │
     │   Landlock · seccomp · capabilities             │
     └─────────────────────────────────────────────────┘

The volt CLI is a single statically-compiled Go binary that orchestrates three subsystems: Voltainer for containers, Voltvisor for virtual machines, and Stellarium for content-addressed storage. All three are unified under the Workload abstraction.

Voltainer — Container Runtime

Voltainer runs containers using systemd-nspawn, the container runtime built into systemd. No daemon process — containers are first-class systemd services.

How It Works

1. Image → Rootfs: volt image pull uses debootstrap to create clean root filesystems, or volt image import to import existing tarballs.
2. Create: volt container create copies the image rootfs into /var/lib/volt/containers/<name>/ and generates a .nspawn config + systemd unit file.
3. Start: volt container start activates the systemd unit, which launches systemd-nspawn with the configured isolation.
4. Exec: volt container exec uses nsenter to enter the running container's namespaces.
5. Logs: All output goes to journald — unified with system logs, queryable with journalctl.

Backend Architecture

Volt uses a pluggable backend interface (ContainerBackend) with two implementations:

Backends register via init() functions, making the system extensible.

Container Lifecycle

  image pull        container create        container start
       │                    │                       │
       ▼                    ▼                       ▼
  ┌──────────┐     ┌────────────────┐      ┌────────────────┐
  │ Download │     │ Copy rootfs    │      │ systemctl      │
  │ rootfs   │────▶│ Generate unit  │─────▶│ start unit     │
  │ (deboot) │     │ Write .nspawn  │      │ (nspawn runs)  │
  └──────────┘     └────────────────┘      └───────┬────────┘
                                                   │
                            ┌──────────────────────┤
                            │                      │
                            ▼                      ▼
                   container exec         container stop
                   │                       │
                   ▼                       ▼
              ┌──────────┐          ┌────────────┐
              │ nsenter  │          │ systemctl  │
              │ into ns  │          │ stop unit  │
              └──────────┘          └────────────┘

Voltvisor — Virtual Machine Management

Voltvisor manages KVM-based virtual machines through the same volt CLI. VMs get the same lifecycle commands as containers but with hardware-level isolation.

Capabilities

• Create: volt vm create generates a VM directory with config.yaml and a systemd unit
• SSH: volt vm ssh resolves the VM's IP and connects
• Storage: volt vm attach links storage to VMs via symlinks
• Desktop: volt desktop provides full VDI with ODE profiles (terminal, office, creative, gaming)

VM File Structure

Stellarium — Content-Addressed Storage

Stellarium is Volt's content-addressed storage (CAS) system. Every blob is stored by its SHA256 hash, providing automatic deduplication and integrity verification.

How CAS Works

# Build a directory into CAS
sudo volt cas build /path/to/app

# Check CAS status
sudo volt cas status

# Verify integrity of all objects
sudo volt cas verify

# Garbage collect unreferenced objects
sudo volt cas gc --dry-run
sudo volt cas gc

Storage Layout

The two-level directory structure prevents filesystem limitations (ext4's ~64K files per directory limit) while keeping lookups fast.

Bundles

Volt can package CAS objects into portable .vbundle files — ZIP archives containing manifests and blobs with SHA256 verification:

sudo volt bundle create myapp-v1.vbundle --ref myapp-v1
sudo volt bundle inspect myapp-v1.vbundle
sudo volt bundle import myapp-v1.vbundle
sudo volt bundle verify myapp-v1.vbundle

Unified Workload Abstraction

The Workload layer abstracts across containers, VMs, and services. A single command can list, start, stop, or inspect any workload type:

# List all workloads (containers + VMs + services)
sudo volt ps

# Inspect any workload
sudo volt ps inspect myapp

# Freeze/thaw (containers: cgroup freezer; VMs: SIGSTOP/SIGCONT)
sudo volt workload freeze myapp
sudo volt workload thaw myapp

Constellations — Multi-Service Stacks

Constellations are Volt's compose system. Define multi-container stacks in a volt-compose.yaml file and manage them as a unit:

version: "1"
services:
  web:
    image: debian-minimal
    command: nginx -g "daemon off;"
    ports:
      - "80:80"
    volumes:
      - webdata:/var/www
    depends_on:
      - db
  db:
    image: debian-minimal
    command: postgres
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  webdata:
  pgdata:

# Deploy the stack
sudo volt compose up

# Check services
sudo volt compose ps

# View logs
sudo volt compose logs

# Tear down
sudo volt compose down

Under the hood, Constellations create a systemd target with individual service units, bridge networks, and volumes.

File Layout

State Management

Volt stores state in simple files — no database required:

All JSON writes use atomic operations (write to temp file, then rename) to prevent corruption.