Volt CLI: source-available under AGPSL v5.0

Complete infrastructure platform CLI: - Container runtime (systemd-nspawn) - VoltVisor VMs (Neutron Stardust / QEMU) - Stellarium CAS (content-addressed storage) - ORAS Registry - GitOps integration - Landlock LSM security - Compose orchestration - Mesh networking Copyright (c) Armored Gates LLC. All rights reserved. Licensed under AGPSL v5.0
2026-03-21 00:30:23 -05:00
commit 81ad0b597c
106 changed files with 35984 additions and 0 deletions
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -0,0 +1,337 @@
+# 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:
+
+```bash
+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:
+
+```bash
+volt --version
+```
+
+### Manual Installation
+
+If you prefer to install manually:
+
+```bash
+# 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
+
+```bash
+sudo volt daemon start
+volt daemon status
+```
+
+## Quick Start
+
+### Pull an Image
+
+```bash
+volt image pull nginx:alpine
+```
+
+### Create and Start a Container
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+# 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](registry.md) 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:
+
+```bash
+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
+
+```bash
+volt ps containers     # Only containers
+volt ps vms            # Only VMs
+volt ps services       # Only services
+```
+
+### Output Formats
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+volt net status
+volt net bridge list
+```
+
+### Create a Network
+
+```bash
+sudo volt net create --name backend --subnet 10.30.0.0/24
+```
+
+### Connect Workloads
+
+```bash
+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`:
+
+```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:
+
+```bash
+volt compose up -d
+volt compose ps
+volt compose logs -f
+volt compose down
+```
+
+## System Health
+
+```bash
+# 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:
+
+```bash
+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](cli-reference.md)** — Every command documented
+- **[Registry](registry.md)** — Host your own OCI-compliant artifact registry
+- **[GitOps](gitops.md)** — Automated deployments from Git pushes
+- **[Compose](compose.md)** — Constellation / Voltfile format specification
+- **[Networking](networking.md)** — Network architecture, ingress proxy, and firewall
+- **[Bundles](bundles.md)** — Portable, self-contained application bundles
+- **[Architecture](architecture.md)** — How Volt works internally
+- **[Troubleshooting](troubleshooting.md)** — Common issues and fixes