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:

```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