Volt Docs
⌘K

Getting Started

Go from zero to running containers in under five minutes. This guide covers installation, your first container, multi-service constellations, and migrating from Docker.

Installation #

Quick Install (recommended)

The fastest way to install Volt on any supported Linux distribution:

shell 
$ curl -fsSL https://get.armoredgate.com/volt | sudo bash

This script detects your distribution, installs dependencies, and sets up the Volt daemon with sane defaults. It supports:

  • Ubuntu 22.04+
  • Debian 12+
  • Rocky Linux / AlmaLinux 9+
  • Fedora 39+
  • Arch Linux (btw)
Kernel Requirements
Volt requires Linux kernel 5.10+ with CONFIG_NAMESPACES, CONFIG_CGROUPS, and systemd-nspawn available. Most modern distributions meet these requirements out of the box.

Manual Installation

If you prefer to install manually or are on a distribution not listed above:

Install dependencies
shell 
# Ubuntu / Debian
$ sudo apt install -y systemd-container debootstrap skopeo jq

# Rocky / Fedora
$ sudo dnf install -y systemd-container skopeo jq
Download the Volt binary
shell 
$ VOLT_VERSION="0.9.4-beta"
$ curl -Lo /usr/local/bin/volt \
    "https://releases.armoredgate.com/volt/v${VOLT_VERSION}/volt-linux-amd64"
$ chmod +x /usr/local/bin/volt
Initialize and start the daemon
shell 
$ sudo volt system init
$ sudo systemctl enable --now voltd

Verify Installation

shell 
$ volt version
Volt v0.9.4-beta (build a3f8c21)
Engine: systemd-nspawn 255.4
Runtime: voltainer 2.1.0

$ volt system status
● voltd.service — Volt Container Daemon
   Active: active (running) since Mon 2025-01-20 14:23:01 CST
   Containers: 0 running, 0 stopped
   Networks: 1 (volt0 — bridge)
   Storage: /var/lib/volt (42.1 GB available)
Shell Completions
Enable tab completions for your shell: volt completion bash > /etc/bash_completion.d/volt. Supports bash, zsh, and fish.

Your First Container #

Let's run an nginx web server. Volt pulls OCI images and runs them inside hardened systemd-nspawn machines:

shell 
$ volt container run --name my-web -p 8080:80 nginx

Pulling nginx:latest... done (42.3 MB)
Converting to nspawn filesystem... done
Applying security profile: default-hardened
Starting container my-web...

✔ Container my-web is running
  Address: 10.42.0.2
  Ports:   8080 → 80/tcp
  Machine: volt-my-web.nspawn

That's it. Your container is running. Let's verify:

shell 
$ curl localhost:8080
<!DOCTYPE html>
<html>
<head><title>Welcome to nginx!</title>...

$ volt container ls
NAME     IMAGE          STATUS    PORTS        UPTIME
my-web   nginx:latest   running   8080→80/tcp  32s

Essential Container Commands

Command Description
volt container ls List all containers
volt container stop <name> Gracefully stop a container
volt container exec <name> -- bash Open a shell inside a container
volt container logs <name> Stream container logs (via journald)
volt container inspect <name> Show detailed container info as JSON
volt container rm <name> Remove a stopped container
Root Required
Container operations require root privileges (or membership in the volt group). Run sudo usermod -aG volt $USER to allow non-root usage, then log out and back in.

Your First Constellation #

Constellations are Volt's multi-container applications — similar to Docker Compose but with native networking, health-aware scheduling, and declarative state management.

Create a constellation.volt file:

yaml — constellation.volt 
name: my-app

containers:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - api

  api:
    image: node:20-slim
    command: node server.js
    environment:
      DATABASE_URL: postgres://db:5432/app
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_PASSWORD: changeme
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Deploy the constellation:

shell 
$ volt constellation up

Reading constellation.volt...
Creating network my-app_default (10.42.1.0/24)
Pulling 3 images... done
Starting db.......... ✔ healthy
Starting api......... ✔ healthy
Starting web......... ✔ ready

✔ Constellation my-app is running (3 containers)
  web:  http://localhost:8080
  api:  10.42.1.3:3000 (internal)
  db:   10.42.1.2:5432 (internal)

Containers in a constellation automatically get a shared private network with DNS-based service discovery — api can reach db just by hostname.

Hot Reloading
Edit constellation.volt and run volt constellation up again — Volt will diff the config and only recreate changed containers. Zero-downtime updates by default.

Migrating from Docker #

Already have Docker containers or Compose files? Volt's compatibility layer makes migration painless.

Compatibility Mode

Enable the Docker-compatible CLI interface:

shell 
$ volt compat docker --enable

Docker compatibility mode enabled.
Symlink created: /usr/local/bin/docker → volt
You can now use 'docker' commands — they'll run through Volt.

With compat mode, your existing scripts and muscle memory work as-is. docker run, docker ps, docker-compose up — all routed through Volt's hardened engine.

Convert Docker Compose Files

Automatically convert a docker-compose.yml to a Volt constellation:

shell 
$ volt compat convert docker-compose.yml

Analyzing docker-compose.yml...
  ✔ 4 services detected
  ✔ 2 volumes mapped
  ✔ 1 network converted
  ⚠ 1 warning: 'privileged: true' on service 'builder' — mapped to capability set

Written: constellation.volt

Review the generated file, then run:
  volt constellation up
Review Before Deploying
Always review the converted constellation.volt before deploying. The converter maps Docker concepts to Volt equivalents, but some Docker features (like --privileged) are intentionally restricted. The converter will warn you about these.

Conversion Reference

Docker Concept Volt Equivalent Notes
docker run volt container run Near-identical flags
docker-compose.yml constellation.volt Auto-converted
Dockerfile Voltfile Superset of Dockerfile syntax
docker network volt network Native systemd-networkd
docker volume volt volume Backed by btrfs subvolumes
--privileged Capability sets Granular — no blanket root

Next Steps #

You've installed Volt, run a container, deployed a constellation, and learned about Docker migration. Here's where to go next:

→ CLI Reference
Every command and flag, documented
→ Networking Guide
Mesh, DNS, and service discovery
→ Security Hardening
Landlock LSM, capabilities, and secrets
→ Voltfile Reference
Build custom container images