volt/docs/getting-started.md

Getting Started with Volt

Volt is the unified Linux platform management CLI by Armored Gates LLC. One binary replaces systemctl, journalctl, machinectl, ip, nft, virsh, and dozens of other tools.

Volt manages three engines:

• Voltainer — Containers built on systemd-nspawn
• Voltvisor — Virtual machines built on KVM/QEMU with the Neutron Stardust VMM
• Stellarium — Content-addressed storage (CAS) shared by both engines

Security is enforced via Landlock LSM and seccomp-bpf — no heavyweight security modules required.

Prerequisites

• Linux with systemd (Debian 12+, Ubuntu 22.04+, Fedora 38+, Rocky 9+)
• Root access (or membership in the volt group)
• For VMs: KVM support (/dev/kvm accessible)
• For containers: systemd-nspawn installed (systemd-container package)

Installation

Install Volt with a single command:

curl https://get.armoredgate.com/volt | sh

This downloads the latest Volt binary, places it at /usr/local/bin/volt, and creates the required directory structure.

Verify the installation:

volt --version

Manual Installation

If you prefer to install manually:

# Download the binary
curl -Lo /usr/local/bin/volt https://releases.armoredgate.com/volt/latest/volt-linux-amd64
chmod +x /usr/local/bin/volt

# Create required directories
sudo mkdir -p /etc/volt
sudo mkdir -p /var/lib/volt/{containers,vms,images,volumes,cas,kernels,units}
sudo mkdir -p /var/run/volt
sudo mkdir -p /var/cache/volt/{cas,images,dns}
sudo mkdir -p /var/log/volt

# Initialize configuration
sudo volt config reset
volt config validate

Start the Daemon

sudo volt daemon start
volt daemon status

Quick Start

Pull an Image

volt image pull nginx:alpine

Create and Start a Container

# Create a container with port mapping
volt container create nginx:alpine --name my-web -p 8080:80

# Start it
volt start my-web

Your web server is now running at http://localhost:8080.

Interact with the Container

# Open a shell
volt container shell my-web

# Execute a single command
volt container exec my-web -- cat /etc/os-release

# View logs
volt container logs my-web

# Follow logs in real-time
volt container logs -f my-web

Copy Files In and Out

# Copy a config file into the container
volt container cp ./myapp.conf my-web:/etc/myapp.conf

# Copy logs out
volt container cp my-web:/var/log/syslog ./container-syslog.log

Stop and Clean Up

volt container stop my-web
volt container delete my-web

Key Concepts

Stellarium CAS

Every image and filesystem in Volt is backed by Stellarium, the content-addressed storage engine. Files are stored by their BLAKE3 hash, giving you:

• Automatic deduplication — identical files across images are stored once
• Integrity verification — every object can be verified against its hash
• Efficient snapshots — only changed files produce new CAS blobs

# Check CAS store health
volt cas status

# Verify integrity
volt cas verify

ORAS Registry

Volt includes a built-in OCI Distribution Spec compliant registry backed by Stellarium CAS. Push and pull OCI artifacts using any standard client:

# Start the registry
volt registry serve --port 5000

# Push artifacts using ORAS or any OCI-compliant tool
oras push localhost:5000/myapp:v1 ./artifact

See Registry for full documentation.

Landlock Security

All workloads are isolated using Landlock LSM (Linux Security Module) combined with seccomp-bpf and cgroups v2. This provides kernel-enforced filesystem access control without requiring complex security profiles.

The Unified Process View

volt ps is the flagship command. It shows every running workload — containers, VMs, and services — in one view:

volt ps

NAME             TYPE        STATUS     CPU%    MEM       UPTIME
my-web           container   running    2.3%    256M      1h 15m
db-primary       vm          running    8.7%    4.0G      3d 2h
nginx            service     active     0.1%    32M       12d 6h

Filter by Type

volt ps containers     # Only containers
volt ps vms            # Only VMs
volt ps services       # Only services

Output Formats

volt ps -o json        # JSON output for scripting
volt ps -o yaml        # YAML output
volt ps -o wide        # All columns

Managing Services

Volt wraps systemctl with a cleaner interface:

# List running services
volt service list

# Check a specific service
volt service status nginx

# Create a new service without writing unit files
sudo volt service create --name my-app \
  --exec "/usr/local/bin/my-app --port 8080" \
  --user my-app \
  --restart on-failure \
  --enable --start

# View service logs
volt service logs -f my-app

Scheduled Tasks

Replace crontab with systemd timers:

# Run a backup every day at 2 AM
sudo volt task create --name nightly-backup \
  --exec "/usr/local/bin/backup.sh" \
  --calendar "*-*-* 02:00:00" \
  --enable

# Run a health check every 5 minutes
sudo volt task create --name health-check \
  --exec "curl -sf http://localhost:8080/health" \
  --interval 5min \
  --enable

Networking Basics

View Network Status

volt net status
volt net bridge list

Create a Network

sudo volt net create --name backend --subnet 10.30.0.0/24

Connect Workloads

volt net connect backend web-frontend
volt net connect backend db-primary

Workloads on the same network can communicate by name.

Constellations (Compose Stacks)

Define multi-service Constellations in a volt-compose.yaml:

version: "1"
name: my-stack

containers:
  web:
    image: armoredgate/nginx:1.25
    ports:
      - "80:80"
    networks:
      - frontend

  api:
    image: armoredgate/node:20
    ports:
      - "8080:8080"
    networks:
      - frontend
      - backend

networks:
  frontend:
    subnet: 10.20.0.0/24
  backend:
    subnet: 10.30.0.0/24
    internal: true

Deploy it:

volt compose up -d
volt compose ps
volt compose logs -f
volt compose down

System Health

# Platform overview
volt system info

# Health check all subsystems
volt system health

# Backup configuration
sudo volt system backup

Getting Help

Every command has built-in help. Three equivalent ways:

volt net --help
volt net help
volt help net

Global Flags

These work on every command:

Flag	Short	Description
--help	-h	Show help
--output	-o	Output format: table, json, yaml, wide
--quiet	-q	Suppress non-essential output
--debug		Enable debug logging
--no-color		Disable colored output
--config		Config file path (default: /etc/volt/config.yaml)
--timeout		Command timeout in seconds (default: 30)

Next Steps

Now that you have Volt installed and running, explore these areas:

• CLI Reference — Every command documented
• Registry — Host your own OCI-compliant artifact registry
• GitOps — Automated deployments from Git pushes
• Compose — Constellation / Voltfile format specification
• Networking — Network architecture, ingress proxy, and firewall
• Bundles — Portable, self-contained application bundles
• Architecture — How Volt works internally
• Troubleshooting — Common issues and fixes